finos / finos/architecture-as-code

Validate uploaded documents in CalmHub via CALM server sidecar

Open
#2,716 4 comments 0 reactions 0 assignees View on GitHub
calm-hub validator
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 6h
Merged PRs (30d)
38

Description

## Feature Proposal

### Target Project:
CalmHub

### Description of Feature:
Add a configurable endpoint to CalmHub for an instance of the calm server. That will be used to validate all uploaded architectures, patterns and so on.
Also include CLI server in CalmHub image as a sidecar by default.

### User Stories:
As an architect, I want a guarantee that my patterns and architectures in CalmHub are valid.

### Current Limitations:
No validation in the Java framework.

### Proposed Implementation:
- CalmHub validation service that calls calm server
- Call this on pattern, architecture, control, etc. upload
- Use the $schema if present to validate these documents
- Include calm server binary in docker image and start it alongside calmhub
- Possible escape hatch header to skip validation eg X-CalmHub-Skip-Validation: true

### Alternatives Considered:
- Validation library in java - rejected as it means a complete rewrite of all CLI logic in Java + ongoing maintenance
- Validate in CLI - this is a soft guarantee as users can still use API endpoints directly to upload invalid architectures to CalmHub

### Testing Strategy:
- Integration testing against real calm server
- Unit testing with mocked calm server responses

### Documentation Requirements:
Docs on how to configure calmhub to use this server in case folks can't use default docker image

### Implementation Checklist:
- [ ] Design reviewed and approved
- [ ] Implementation completed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Relevant workflows updated (if needed)
- [ ] Performance impact assessed

### Additional Context:
- #689 — Expose the CALM CLI as a RESTful API (origin of the "CLI server as a local sidecar" pattern).
- #2051 — CALM Server: extracted the validation server into the standalone `@finos/calm-server` package (the server this proposal would run as a sidecar).

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the CalmHub validation-service proposal and the referenced patterns in #689 and #2051, then define how the sidecar endpoint, uploads, schema handling, and skip-validation header should interact. Validate the design before implementation; done means approved integration and unit tests, a Docker image with the CALM server sidecar, configuration documentation, and assessed workflow or performance impact.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, java, typescript
Domain
api, backend, devops
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.