# finos/architecture-as-code architecture

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

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

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Specification
    subgraph "Specification"
        SpecDoc["CALM Specification (JSON Schemas)"]:::document
    end

    %% CLI Tool
    subgraph "CLI Tool"
        CLI["CLI Entrypoint"]:::service
        CLIHealth["Health Route"]:::service
        CLIValidation["Validation Route"]:::service
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        Parser["Parser"]:::library
        Resolver["Resolver"]:::library
        TemplateEngine["Template Engine"]:::library
        Docifier["Docifier"]:::library
        Spectral["Spectral Rules"]:::library
    end

    %% Backend Service
    subgraph "Backend Service"
        RestAPI["REST API Controllers"]:::service
        Security["Security Filters"]:::service
        StoreInterface["Store Abstraction Interfaces"]:::service
        MongoImpl["MongoDB Implementations"]:::service
        NitriteImpl["Nitrite Implementations"]:::service
        StoreProducer["Store Producers"]:::service
        DomainModel["Domain Models"]:::service
        Config["Configuration Classes"]:::service
    end

    %% Frontend App
    subgraph "Frontend App"
        AppShell["App Shell & Routing"]:::service
        AuthService["AuthService & ProtectedRoute"]:::service
        HubViewer["Hub Viewer Components"]:::service
        Visualizer["Visualizer & CytoscapeRenderer"]:::service
        HTTPService["HTTP Service Wrappers"]:::service
        Navbar["Navbar"]:::service
    end

    %% Documentation Site
    subgraph "Documentation Site"
        DocsSource["Docs Source"]:::service
        DocsConfig["Docusaurus Config"]:::service
        DocsComponents["Custom Components"]:::service
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Keycloak["Keycloak"]:::external
        MongoDB["MongoDB"]:::database
        NitriteDB["Nitrite Embedded DB"]:::database
        DockerCompose["Docker Compose"]:::infra
        K8s["Kubernetes Manifests"]:::infra
    end

    %% CI/CD
    subgraph "CI/CD"
        CLI_CI["Build CLI"]:::infra
        Shared_CI["Build Shared"]:::infra
        Backend_CI["Build Backend"]:::infra
        UI_CI["Build UI"]:::infra
        Docs_CI["Build Docs"]:::infra
    end

    %% Relationships
    SpecDoc -->|imports| Parser
    SpecDoc -->|defines rules| Spectral

    Parser -->|used by| CLI
    Resolver -->|used by| CLI
    Spectral -->|used by| CLIValidation
    TemplateEngine -->|used by| DocsSource
    Docifier -->|used by| DocsSource

    CLI -->|exposes| CLIHealth
    CLI -->|exposes| CLIValidation

    AppShell -->|routes| HubViewer
    AppShell -->|uses| AuthService
    AuthService -->|auth via| Keycloak
    HubViewer -->|renders| Visualizer
    Visualizer -->|layout by| HTTPService
    Navbar -->|calls| HTTPService
    HTTPService -->|calls| RestAPI

    RestAPI -->|validates via| Security
    Security -->|token introspection| Keycloak
    RestAPI -->|uses| DomainModel
    RestAPI -->|selects impl via| StoreProducer
    StoreProducer -->|implements interface| StoreInterface
    StoreInterface -->|implemented by| MongoImpl
    StoreInterface -->|implemented by| NitriteImpl
    MongoImpl -->|connects| MongoDB
    NitriteImpl -->|embeds| NitriteDB

    DockerCompose -->|deploys| RestAPI
    DockerCompose -->|deploys| Keycloak
    DockerCompose -->|deploys| MongoDB
    K8s -->|deploys| RestAPI
    K8s -->|deploys| Keycloak
    K8s -->|deploys| MongoDB

    CLI_CI -->|builds| CLI
    Shared_CI -->|builds| Parser
    Shared_CI -->|builds| Resolver
    Shared_CI -->|builds| TemplateEngine
    Shared_CI -->|builds| Docifier
    Shared_CI -->|builds| Spectral
    Backend_CI -->|builds| RestAPI
    UI_CI -->|builds| AppShell
    Docs_CI -->|builds| DocsSource

    %% Click Events
    click SpecDoc "https://github.com/finos/architecture-as-code/tree/main/calm/"
    click CLI "https://github.com/finos/architecture-as-code/blob/main/cli/src/cli.ts"
    click CLIHealth "https://github.com/finos/architecture-as-code/blob/main/cli/src/server/routes/health-route.ts"
    click CLIValidation "https://github.com/finos/architecture-as-code/blob/main/cli/src/server/routes/validation-route.ts"
    click Parser "https://github.com/finos/architecture-as-code/blob/main/shared/src/parser/parser.ts"
    click Resolver "https://github.com/finos/architecture-as-code/blob/main/shared/src/resolver/calm-reference-resolver.ts"
    click TemplateEngine "https://github.com/finos/architecture-as-code/blob/main/shared/src/template/template-engine.ts"
    click Docifier "https://github.com/finos/architecture-as-code/blob/main/shared/src/docify/docifier.ts"
    click Spectral "https://github.com/finos/architecture-as-code/blob/main/shared/src/spectral/rules-architecture.ts"
    click RestAPI "https://github.com/finos/architecture-as-code/blob/main/calm-hub/src/main/java/org/finos/calm/resources/AdrResource.java"
    click Security "https://github.com/finos/architecture-as-code/blob/main/calm-hub/src/main/java/org/finos/calm/security/AccessControlFilter.java"
    click StoreInterface "https://github.com/finos/architecture-as-code/blob/main/calm-hub/src/main/java/org/finos/calm/store/AdrStore.java"
    click MongoImpl "https://github.com/finos/architecture-as-code/blob/main/calm-hub/src/main/java/org/finos/calm/store/mongo/MongoAdrStore.java"
    click NitriteImpl "https://github.com/finos/architecture-as-code/blob/main/calm-hub/src/main/java/org/finos/calm/store/nitrite/NitriteAdrStore.java"
    click StoreProducer "https://github.com/finos/architecture-as-code/blob/main/calm-hub/src/main/java/org/finos/calm/store/producer/AdrStoreProducer.java"
    click DomainModel "https://github.com/finos/architecture-as-code/blob/main/calm-hub/src/main/java/org/finos/calm/domain/Architecture.java"
    click Config "https://github.com/finos/architecture-as-code/blob/main/calm-hub/src/main/java/org/finos/calm/config/NitriteDBConfig.java"
    click AppShell "https://github.com/finos/architecture-as-code/blob/main/calm-hub-ui/src/App.tsx"
    click AuthService "https://github.com/finos/architecture-as-code/blob/main/calm-hub-ui/src/ProtectedRoute.tsx"
    click HubViewer "https://github.com/finos/architecture-as-code/blob/main/calm-hub-ui/src/hub/Hub.tsx"
    click Visualizer "https://github.com/finos/architecture-as-code/blob/main/calm-hub-ui/src/visualizer/Visualizer.tsx"
    click HTTPService "https://github.com/finos/architecture-as-code/blob/main/calm-hub-ui/src/service/calm-service.tsx"
    click Navbar "https://github.com/finos/architecture-as-code/blob/main/calm-hub-ui/src/components/navbar/Navbar.tsx"
    click DocsSource "https://github.com/finos/architecture-as-code/tree/main/docs/docs/"
    click DocsConfig "https://github.com/finos/architecture-as-code/blob/main/docs/docusaurus.config.js"
    click DocsComponents "https://github.com/finos/architecture-as-code/tree/main/docs/src/components/"
    click DockerCompose "https://github.com/finos/architecture-as-code/blob/main/calm-hub/deploy/docker-compose.yml"
    click Keycloak "https://github.com/finos/architecture-as-code/blob/main/calm-hub/keycloak-dev/docker-compose.yml"
    click K8s "https://github.com/finos/architecture-as-code/blob/main/calm-hub/k8s/calm-hub.yml"

    %% Styles
    classDef service fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef library fill:#E8F5D0,stroke:#6BB700,color:#6BB700;
    classDef database fill:#FFD0D0,stroke:#D60000,color:#D60000,shape:cylinder;
    classDef external fill:#F0E8FF,stroke:#6E00D6,color:#6E00D6,shape:hexagon;
    classDef document fill:#FFF5D0,stroke:#D69E00,color:#D69E00;
    classDef infra fill:#E8E8E8,stroke:#666666,color:#333333;
```
