How finos-labs/architecture-as-code works
Project type & purpose
• This is a full-stack, multi-module monorepo that delivers:
– A JSON-based Common Architecture Language Model (CALM) specification.
– A CLI tool (Node/TypeScript) for generating and validating architecture code.
– A shared library (TypeScript) with core parsing, validation, docification, and templating capabilities.
– A backend service (“calm-hub”, Java/Spring Boot) exposing REST APIs to persist and query architectural artifacts.
– A frontend UI (“calm-hub-ui”, React + Vite) for interacting with the backend.
– A documentation site (Docusaurus) generated from the CALM model and shared templates.
• Use cases include: generating architecture artifacts, validating specifications, browsing/editing via web UI, and publishing docs.
File structure & README
• Top-level folders correspond to sub-projects:
– calm/ → core JSON schema & sample models
– cli/ → TypeScript CLI (npm workspace)
– shared/ → shared TypeScript library (npm workspace)
– calm-hub/ → Java backend (Maven project)
– calm-hub-ui/ → React frontend (npm + Vite)
– docs/ → Docusaurus site
– template-bundles/ → custom Handlebars templates for docs/CLI
• Configuration files (pom.xml, package.json, tsconfig, GitHub workflows) reveal build and CI/CD pipelines.
• calm-hub/src/main shows Spring Boot + multiple store implementations (MongoDB, Nitrite), plus Keycloak integration under security.
Main components & their relationships
a. Components:
1. Developer Local Environment (VSCode DevContainer)
2. Monorepo Source (all sub-projects)
3. GitHub Actions CI/CD
4. CLI Tool (Node/TypeScript)
5. Shared Library (TypeScript)
6. CALM Specification (JSON schemas + samples)
7. calm-hub Backend (Java Spring Boot)
8. Authentication Service (Keycloak)
9. Databases (MongoDB cluster, optional embedded Nitrite)
10. calm-hub-ui Frontend (React + Vite)
11. Docs Site (Docusaurus)
12. External Services:
• Container Registry (Docker Hub/Azure)
• npm Registry
• S3 (Docs hosting, video sync)
b. Interactions & data flows:
– Developer pushes code to GitHub → CI/CD workflows run builds/tests → publish artifacts (Docker images, npm packages), sync docs to S3.
– CLI imports shared library; reads CALM JSON from local FS or fetches from calm-hub API; runs generate/validate commands; outputs files or reports.
– calm-hub-ui served to browser; uses authService to obtain tokens from Keycloak; calls calm-hub REST endpoints (e.g., /api/adr, /api/architecture); displays and updates models.
– calm-hub backend enforces access via AccessControlFilter, persists to MongoDB (or embedded Nitrite), and returns JSON.
– Docs site template-drives content from CALM schemas and samples via shared/docify modules.
Architectural patterns & design principles
• Monorepo with logical modules → clear separation of concerns (specification, CLI, shared, backend, frontend, docs).
• Micro-service style for calm-hub backend + UI as separate deployables.
• Library-first approach: shared business logic (parsing, validation, templating) in a reusable TS library.
• Standard CI/CD via GitHub Actions: build/test per module, security & license scanning.
• Pluggable store implementations in Java (Mongo vs Nitrite) via Producer pattern and Spring qualifiers.
• OpenID Connect authentication via Keycloak.