How finos/architecture-as-code works
Project type and purpose
• This is a full-stack monorepo (“architecture-as-code”) that hosts:
• A JSON-schema-based Common Architecture Language Model (CALM) specification (“calm/…”)
• A TypeScript CLI tool (“cli/”) and shared TS libraries (“shared/”) for generation & validation
• A Java-based backend service (“calm-hub/”) exposing REST APIs to store and serve CALM artifacts
• A React+Vite frontend (“calm-hub-ui/”) that presents architectures graphically
• A Docusaurus docs site (“docs/”)
• Brand assets, template bundles, Docker/K8s configs for local/dev deployment
Main components
a. CALM Specification
• JSON Schemas & sample artifacts under “calm/” (core language model)
b. CLI & Shared Libraries
• CLI (Node/TypeScript) – commands for generate, validate, serve (health & validation HTTP routes)
• Shared TS libraries – parser, resolver, template engine, spectral rules
c. Backend (“calm-hub”)
• REST API layer (JAX-RS or Spring controllers in org.finos.calm.resources)
• Security filters integrating with Keycloak (AccessControlFilter, UserAccessValidator)
• Store abstraction → MongoDB (in k8s/mongo.yml) or Nitrite embedded DB (fallback)
• Business/domain models (org.finos.calm.domain)
• Producer beans for selecting store implementation at runtime
d. Frontend (“calm-hub-ui”)
• React components (Visualizer, Hub viewer, JSON rendering, navbar)
• AuthService + ProtectedRoute (calls Keycloak for authentication)
• CytoscapeRenderer for graph layouts
• HTTP service wrappers calling calm-hub REST endpoints
e. Authentication & External Services
• Keycloak (docker-compose under calm-hub/keycloak-dev/) for OAuth2 device-code flow
• Kubernetes & Docker for deployment (calm-hub/deploy/docker-compose.yml, calm-hub/k8s/*.yml)
f. Database
• MongoDB (runtime) & embedded Nitrite (dev/test)
Relationships & interactions
• Frontend → (HTTPS/REST) → Backend
• Backend → (MongoDB driver) → MongoDB
• Backend → (Keycloak REST) → Keycloak for token validation & scopes
• CLI → (spectral + JSON Schema) → Local file system / Shared libraries for parsing & validation
• CLI → (HTTP) → CLI-server routes for validation if launched as server
• Docs build → Shared libraries for templating (docifier)
Architectural patterns & design principles
• Monorepo with clearly separated modules by function
• Layered backend: Controller (REST) → Service (security / validation) → Store (DAO) → Persistence
• Adapter pattern for multiple store implementations (Mongo / Nitrite)
• Micro frontends concept: CLI, UI, backend as separate deployables
• Reuse of shared library code across CLI, docs, and UI tooling
• Infrastructure-as-code for deployments (Docker, Kubernetes manifests)
Detailed component breakdown
• REST layer (AdrResource, FlowResource, …)
• Security (AccessControlFilter → Keycloak)
• Store abstraction + implementations (MongoAdrStore, NitriteAdrStore)
• React modules (Visualizer, JsonRenderer, ValueTable)
• Spectral validation rules in shared/src/spectral
• Template engine & docifier in shared/src/docify