# finos-labs/architecture-as-code architecture

> Architecture diagram of the GitHub repository finos-labs/architecture-as-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/finos-labs/architecture-as-code
- Repository: https://github.com/finos-labs/architecture-as-code

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    DevEnv["Developer Local Environment<br/>(VSCode DevContainer)"]:::dev
    click DevEnv "https://github.com/finos-labs/architecture-as-code/blob/main/.devcontainer/devcontainer.json"

    %% CI/CD
    CI["GitHub Actions CI/CD"]:::ci
    click CI "https://github.com/finos-labs/architecture-as-code/tree/main/.github/workflows/"

    DevEnv -->|"push code"| CI

    %% Monorepo Boundary
    subgraph "Monorepo Source" 
        direction TB
        Repo["Monorepo Source<br/>(root modules)"]:::repo
        click Repo "https://github.com/finos-labs/architecture-as-code/blob/main/tsconfig.base.json"

        subgraph "CALM Specification" 
            CALM["CALM JSON Schemas & Samples"]:::schema
            click CALM "https://github.com/finos-labs/architecture-as-code/tree/main/calm/"
        end

        subgraph "Shared Library" 
            Shared["Shared TS Lib<br/>(parsing/validation/docify/templating)"]:::lib
            click Shared "https://github.com/finos-labs/architecture-as-code/tree/main/shared/"
        end

        subgraph "CLI Tool" 
            CLI["CLI Tool<br/>(Node/TypeScript)"]:::service
            click CLI "https://github.com/finos-labs/architecture-as-code/tree/main/cli/"
        end

        subgraph "Template Bundles" 
            Templates["Template Bundles<br/>(Handlebars)"]:::artifact
            click Templates "https://github.com/finos-labs/architecture-as-code/tree/main/template-bundles/"
        end

        subgraph "calm-hub Backend" 
            Backend["calm-hub Backend<br/>(Java Spring Boot REST)"]:::service
            click Backend "https://github.com/finos-labs/architecture-as-code/tree/main/calm-hub/"
            subgraph "Data & Security"
                KeycloakDev["Keycloak Dev Instance"]:::cloud
                click KeycloakDev "https://github.com/finos-labs/architecture-as-code/tree/main/calm-hub/keycloak-dev/"
                MongoDB["MongoDB Cluster"]:::db
                click MongoDB "https://github.com/finos-labs/architecture-as-code/blob/main/calm-hub/mongo/init-mongo.js"
                NitriteDB["Nitrite Embedded DB"]:::db
                click NitriteDB "https://github.com/finos-labs/architecture-as-code/blob/main/calm-hub/nitrite/init-nitrite.sh"
            end
        end

        subgraph "Frontend UI" 
            UI["calm-hub-ui<br/>(React + Vite)"]:::frontend
            click UI "https://github.com/finos-labs/architecture-as-code/tree/main/calm-hub-ui/"
        end

        subgraph "Docs Site" 
            Docs["Docs Site<br/>(Docusaurus)"]:::docs
            click Docs "https://github.com/finos-labs/architecture-as-code/tree/main/docs/"
        end
    end

    CI -->|"build/test/publish Docker"| Backend
    CI -->|"publish npm packages"| CLI
    CI -->|"publish npm packages"| Shared
    CI -->|"deploy docs to S3"| Docs

    %% Monorepo interactions
    Shared -->|dependency| CLI
    Shared -->|dependency| Docs
    CALM -->|reads fs/HTTP| CLI
    CALM -->|feeds templates| Docs
    Templates -->|used by| CLI
    Templates -->|used by| Docs

    UI -->|REST/HTTP| Backend
    UI -->|OIDC| KeycloakDev
    Backend -->|REST JSON| UI
    Backend -->|persist| MongoDB
    Backend -->|optional embed| NitriteDB
    Backend -->|auth via OIDC| KeycloakDev

    CLI -->|HTTP/REST| Backend
    Docs -->|deployed to| S3

    %% External Services
    subgraph "External Infra" 
        direction TB
        Keycloak["Keycloak (Auth Service)"]:::cloud
        NPM["npm Registry"]:::cloud
        DockerReg["Container Registry<br/>(Docker Hub/Azure)"]:::cloud
        S3["S3 Bucket"]:::cloud
    end

    CI -->|push images| DockerReg
    CI -->|push packages| NPM
    Docs -->|sync docs| S3

    %% Styles
    classDef dev fill:#FFD580,stroke:#333,stroke-width:1px
    classDef ci fill:#B0E0E6,stroke:#333,stroke-width:1px
    classDef repo fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef schema fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef lib fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef service fill:#FFE4E1,stroke:#333,stroke-width:1px
    classDef frontend fill:#F0FFF0,stroke:#333,stroke-width:1px
    classDef docs fill:#F5F5DC,stroke:#333,stroke-width:1px
    classDef db fill:#FAFAD2,stroke:#333,stroke-width:1px
    classDef cloud fill:#E0FFFF,stroke:#333,stroke-width:1px
    classDef artifact fill:#D3D3D3,stroke:#333,stroke-width:1px
```
