# accordproject/concerto architecture

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

- Interactive diagram: https://gitdiagram.com/accordproject/concerto
- Repository: https://github.com/accordproject/concerto

## Overview

##### Main components
- Concerto-Core: This is the heart of the project and includes libraries for model management, parsing, validation, and serialization. It also handles the introspection APIs that let you explore the defined models.
- Concerto-CTO: The dedicated package for parsing the .cto domain-specific language. It transforms the textual model definitions into the internal metamodel representation.
- Concerto-Analysis: Contains tools for comparing model files and reporting changes (e.g., detecting added or changed fields).
- Concerto-Vocabulary: Manages model vocabularies, localization, and related metadata.
- Concerto-Util: Provides utility functions and generic libraries used by other modules, decoupled from the modeling language itself.
- Concerto-Types: Supplies TypeScript type definitions that are critical for proper integration and static type checking.
- Additional supporting tools: There is mention of a CLI tool (concerto-cli) that serves as the primary user interface for interacting with the modeling functionality. There are also build and workflow scripts that facilitate continuous integration and deployment.

##### Relationships and Interactions
- The CLI tool interacts with the core components: invoking the SDK for validations, parsing (.cto files), and performing model comparisons.
- The Concerto-CTO package relies on the Concerto-Core for constructing the proper metamodel from parsed input.
- The Analysis package consumes model representations (from core or cto) to compare and generate change reports.
- The Vocabulary package may interact with the Core to inject localization metadata into models.
- Utility modules are supporting all the above packages by providing logging, file handling, and common error management.
- The TypeScript definitions (concerto-types) serve as an interface layer to support both development and external integration.

##### Architectural Patterns and Design Principles
- Modular and layered architecture: Each package in the repository serves a distinct part of the overall system. This separation of concerns is essential and should be emphasized.
- Plugin-like design: The parser, translator, validator, and analysis tools are developed as independent modules which can be updated or replaced independently.
- Reusability and interoperability: Core functionality, like the metamodel and serialization, is shared across packages.

##### Recommend Inclusion of Technologies and Frameworks
- Node.js and npm workspaces form the basis of the project’s integration mechanism.
- Testing frameworks like Jest (as seen in some test folders) indicate unit testing is an integral part of the design.
- Build and CI/CD workflows hint at the use of GitHub Actions for continuous integration.
- Static analysis and type-checking (e.g., ESLint and TypeScript, as indicated in the presence of tsconfig files and type definition packages).

##### Essential Elements
– Core modules (concerto-core, concerto-cto)
– Supporting modules (concerto-util, concerto-types)
– Analysis and extension modules (concerto-analysis, concerto-vocabulary)
– External interfacing (CLI tool, publishing pipelines)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Interfaces"
        CLI("CLI Tool - User Interface"):::external
        CICD("CI/CD Pipeline - GitHub Actions"):::pipeline
    end

    subgraph "Core Modules"
        CORE("Concerto-Core - Model management, validation and introspection"):::core
        CTO("Concerto-CTO - Parses .cto DSL to metamodel"):::core
        VOCAB("Concerto-Vocabulary - Manages vocabularies and localization"):::core
    end

    subgraph "Supporting Modules"
        ANALYSIS("Concerto-Analysis - Model comparison and change reporting"):::extension
        UTIL("Concerto-Util - Utility functions and libraries"):::support
        TYPES("Concerto-Types - Type definitions for integration"):::support
    end

    CLI -->|"invoke"| CORE
    CLI -->|"invoke"| CTO
    CLI -->|"invoke"| ANALYSIS

    CTO -->|"depends"| CORE
    VOCAB -->|"injectsMetadata"| CORE

    CORE -->|"providesModels"| ANALYSIS
    CTO -->|"providesModels"| ANALYSIS

    CORE -->|"uses"| UTIL
    CTO -->|"uses"| UTIL
    VOCAB -->|"uses"| UTIL
    ANALYSIS -->|"uses"| UTIL

    CORE -->|"typedBy"| TYPES
    CTO -->|"typedBy"| TYPES
    VOCAB -->|"typedBy"| TYPES
    ANALYSIS -->|"typedBy"| TYPES

    CICD -->|"buildTest"| CORE
    CICD -->|"buildTest"| CTO
    CICD -->|"buildTest"| VOCAB
    CICD -->|"buildTest"| ANALYSIS
    CICD -->|"buildTest"| UTIL
    CICD -->|"buildTest"| TYPES

    classDef core fill:#FCD581,stroke:#333,stroke-width:2px;
    classDef extension fill:#B7E4C7,stroke:#333,stroke-width:2px;
    classDef support fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef external fill:#FFC8A2,stroke:#333,stroke-width:2px;
    classDef pipeline fill:#D8BFD8,stroke:#333,stroke-width:2px;

    click CORE "https://github.com/accordproject/concerto/tree/main/packages/concerto-core"
    click CTO "https://github.com/accordproject/concerto/tree/main/packages/concerto-cto"
    click VOCAB "https://github.com/accordproject/concerto/tree/main/packages/concerto-vocabulary"
    click ANALYSIS "https://github.com/accordproject/concerto/tree/main/packages/concerto-analysis"
    click UTIL "https://github.com/accordproject/concerto/tree/main/packages/concerto-util"
    click TYPES "https://github.com/accordproject/concerto/tree/main/packages/concerto-types"
```
