# twinlogix/mondrian-framework architecture

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

- Interactive diagram: https://gitdiagram.com/twinlogix/mondrian-framework
- Repository: https://github.com/twinlogix/mondrian-framework

## Overview

##### Project type and purpose
- This is an open-source, TypeScript monorepo implementing the “Mondrian” backend framework.
- It provides a modular core (model, module), protocol adapters (REST via Fastify, GraphQL via Yoga), build-time tools (CLI, CI tools), AWS Lambda wrappers, and example+docs.
- Its purpose is to let developers declare type-safe data models and service functions, then automatically expose them as OpenAPI, GraphQL, Protobuf, Lambda, cron jobs, etc., without code generation.

##### File structure
- Top-level: configuration (ESLint, Prettier, Dockerfile, GitHub Actions), changelog manager, and high-level docs/assets.
- packages/ group:
- Core packages:
– @mondrian-framework/model (data typing/encode/decode)
– @mondrian-framework/module (function definition, dependency injection, security)
- Protocol adapters:
– @mondrian-framework/rest-fastify
– @mondrian-framework/graphql-yoga
– aws-lambda-rest, aws-lambda-sqs, aws-sqs, cron, direct
- Tooling:
– cli-commander, cli, ci-tools
– utils (shared helpers)
- Documentation and examples:
– example (template project with Prisma integration)
- Configuration and build orchestrator: Vite, tsconfig.json, package.json (workspace), Dockerfile for containerized spin-up, GitHub workflows for CI and docs deployment.

##### Key architectural insights from README
- Core design is “define model → define functions → build module → bind to transports → serve”.
- Emphasizes plugin-style architecture: providers for DI, automatic OpenAPI/GraphQL generation, security policies layered into function execution.
- Example shows integration with Prisma, Fastify, GraphQL Yoga, OpenTelemetry.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Workspace
    subgraph "Developer Workspace (Monorepo Root)"
        direction TB

        %% Core Framework
        subgraph "Core Framework"
            direction TB
            ModelEngine["Model Engine"]:::core
            ModuleEngine["Module Engine"]:::core
        end

        %% Protocol Adapters
        subgraph "Protocol Adapters"
            direction TB
            RESTAdapter["REST Adapter (Fastify)"]:::adapter
            GraphQLAdapter["GraphQL Adapter (Yoga)"]:::adapter
            subgraph "AWS Lambda Adapters"
                direction TB
                LambdaREST["AWS Lambda REST Wrapper"]:::adapter
                LambdaSQS["AWS Lambda SQS Wrapper"]:::adapter
                SQSConsumer["AWS SQS Consumer (SDK)"]:::adapter
            end
            CronScheduler["Cron Scheduler Adapter"]:::adapter
            DirectSDK["Direct/SDK Layer"]:::adapter
        end

        %% Tools & CI
        subgraph "Tooling & CI"
            direction TB
            CLITools["CLI Tools"]:::tool
            CITools["CI Tools"]:::tool
            GitHubActions["GitHub Actions"]:::tool
            DockerBuild["Docker Build"]:::tool
        end

        %% Documentation & Examples
        subgraph "Documentation & Examples"
            direction TB
            DocsSite["Documentation Site"]:::docs
            ExampleApp["Example Application"]:::docs
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Database["Database (Prisma Client)"]:::external
        AWS["AWS Services (SQS, Lambda)"]:::external
        Monitoring["Monitoring/Tracing (OpenTelemetry)"]:::external
    end

    %% Data & Control Flows
    RESTAdapter -->|"invokes"| ModuleEngine
    GraphQLAdapter -->|"invokes"| ModuleEngine
    LambdaREST -->|"invokes"| ModuleEngine
    LambdaSQS -->|"invokes"| ModuleEngine
    CronScheduler -->|"triggers"| ModuleEngine
    DirectSDK -->|"calls"| ModuleEngine

    ModuleEngine -->|"uses models"| ModelEngine
    ModuleEngine -->|"executes business logic"| Database
    ModuleEngine -->|"publishes events"| AWS

    ModelEngine -->|"provides metadata"| RESTAdapter
    ModelEngine -->|"provides metadata"| GraphQLAdapter

    ExampleApp -->|"wires to"| RESTAdapter
    ExampleApp -->|"wires to"| GraphQLAdapter
    ExampleApp -->|"uses"| DirectSDK

    CLITools -->|"runs on"| DeveloperWorkspace
    CITools -->|"processes code"| DeveloperWorkspace
    GitHubActions -->|"CI/CD pipeline"| DeveloperWorkspace
    DockerBuild -->|"builds container"| DeveloperWorkspace

    DocsSite -->|"consumes diagrams & config"| DeveloperWorkspace

    Monitoring -->|"collects traces from"| RESTAdapter
    Monitoring -->|"collects traces from"| GraphQLAdapter
    Monitoring -->|"collects traces from"| LambdaREST

    %% Click Events
    click ModelEngine "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/model"
    click ModuleEngine "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/module"
    click RESTAdapter "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/rest-fastify"
    click GraphQLAdapter "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/graphql-yoga"
    click LambdaREST "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/aws-lambda-rest"
    click LambdaSQS "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/aws-lambda-sqs"
    click SQSConsumer "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/aws-sqs"
    click CronScheduler "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/cron"
    click DirectSDK "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/direct"
    click CLITools "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/cli-commander"
    click CLITools "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/cli"
    click CITools "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/ci-tools"
    click DocsSite "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/docs"
    click ExampleApp "https://github.com/twinlogix/mondrian-framework/tree/develop/packages/example"
    click GitHubActions "https://github.com/twinlogix/mondrian-framework/blob/develop/.github/workflows/ci-checks.yml"
    click GitHubActions "https://github.com/twinlogix/mondrian-framework/blob/develop/.github/workflows/deploy-docs.yml"
    click DockerBuild "https://github.com/twinlogix/mondrian-framework/tree/develop/Dockerfile"

    %% Styles
    classDef core fill:#a3c4f3,stroke:#0366d6,color:#000
    classDef adapter fill:#b2f2bb,stroke:#2f9e44,color:#000
    classDef tool fill:#ffd8a8,stroke:#e67700,color:#000
    classDef docs fill:#e9ecef,stroke:#495057,color:#000
    classDef external fill:#e0d7f3,stroke:#6f42c1,color:#000
```
