# modiimedia/arri architecture

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

- Interactive diagram: https://gitdiagram.com/modiimedia/arri
- Repository: https://github.com/modiimedia/arri

## Overview

Based on our analysis, this project is a monorepo for Arri RPC – a code-first RPC framework that automatically generates type-safe clients from your server code. It supports multiple programming languages for both server implementations and client generators and even bundles tooling (like a CLI, code-generation utilities, JSON schema converters, and type definitions) together with extensive testing and documentation.

##### Main Components
- Arri CLI & Tooling: At the heart of the system, the Arri CLI (located in the tooling/cli directory) orchestrates the entire workflow, running code generators and managing dependencies.
- Server Implementations: Under the “languages” folder you have separate sub-projects for different server implementations (e.g., Typescript, Go) that generate an “Arri App Definition” (which is essentially a snapshot of your procedures and types).
- Client Generators: Also in the “languages” folder (e.g., ts-codegen, dart-codegen, rust-codegen, kotlin-codegen, swift-codegen), these generators convert the app definition into language-specific client code.
- Code Generation Utilities & Schema Tools: The project contains several directories (e.g., tooling/codegen-utils, tooling/json-schema-to-atd, languages/ts/ts-schema) that help build and validate the schema, ensuring consistency across definitions.
- App Definition: This is the central contract that represents the procedures, parameters, and responses. It is either created automatically by the server implementations or manually by the user (as described in the README). It plays a pivotal role by being the artifact that is passed from the server side to the CLI, and then onward to the client generators.
- Tests and Specifications: The tests directory (covering clients and servers) and the specifications directory (with documents like arri_app_definition.md) provide validation and a detailed outline of expected behavior.

##### Relationships and Data Flow
- The process starts with the server code (which lives in folders such as languages/ts/ts-server, languages/go/go-server, etc.) that defines procedures and types.
- Client generators (in languages/*/codegen projects) use the App Definition to generate type-safe client libraries.
- Additional utilities (such as schema validation from @arrirpc/schema) interact with both server code and code generators. Represent them as supportive utilities interfacing with both the server-side and generator components.

##### Architectural Patterns and Design Principles
- Modular Design & Pluggable Components: Each language-specific implementation is isolated within its own directory. This promotes a clear separation of concerns.
- Code-first API Definition: The framework relies on generating the API definition directly from server code, minimizing manual client coding.
- Automated Workflows: The CLI (along with scripts and tooling) automates server building, client generation, and hot-reloading (for development).
- Monorepo Organization: All components (server implementations, client generators, tooling, and tests) are co-located in one repository, allowing tight integration and easy cross-module reference.

##### Additional Elements to Capture
- Continuous Integration/Deployment (CI/CD): Given the presence of GitHub workflows and configurations, consider a small section showing how tests are run automatically.
- Build scripts and Developer Tooling: Note the various scripts in the “internal/scripts” directory which aid in tasks like testing, version synchronization, and scaffolding.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["Arri CLI & Tooling"]:::cli
    end

    %% Server Layer
    subgraph "Server Layer"
        TS["TypeScript Server"]:::server
        GO["Go Server"]:::server
        Artifact["App Definition (Artifact)"]:::artifact
    end

    %% Client Layer
    subgraph "Client Layer"
        TSClient["TypeScript Client Generator"]:::client
        DartClient["Dart Client Generator"]:::client
        KotlinClient["Kotlin Client Generator"]:::client
        RustClient["Rust Client Generator"]:::client
        SwiftClient["Swift Client Generator"]:::client
    end

    %% Utilities & Tools Layer
    subgraph "Utilities & Tools"
        CodeGen["Code Generation Utilities"]:::utility
        JsonSchema["JSON Schema Tools"]:::utility
        BuildScripts["Build Scripts & Developer Tooling"]:::utility
    end

    %% Tests & Specifications Layer
    subgraph "Tests & Specifications"
        TestSuite["Tests"]:::test
        Specs["Specifications"]:::spec
    end

    %% Relationships
    %% Server Implementations generate App Definition
    TS -->|"generates"| Artifact
    GO -->|"generates"| Artifact

    %% App Definition is passed to CLI
    Artifact -->|"passed_to"| CLI

    %% CLI triggers Client Generators
    CLI -->|"triggers"| TSClient
    CLI -->|"triggers"| DartClient
    CLI -->|"triggers"| KotlinClient
    CLI -->|"triggers"| RustClient
    CLI -->|"triggers"| SwiftClient

    %% Feedback loop from Servers to Tests
    TS ---|"feedback"| TestSuite
    GO ---|"feedback"| TestSuite

    %% Feedback loop from Client Generators to Tests
    TSClient ---|"feedback"| TestSuite
    DartClient ---|"feedback"| TestSuite
    KotlinClient ---|"feedback"| TestSuite
    RustClient ---|"feedback"| TestSuite
    SwiftClient ---|"feedback"| TestSuite

    %% Interaction with Code Generation Utilities
    TS ---|"uses"| CodeGen
    GO ---|"uses"| CodeGen
    TSClient ---|"uses"| CodeGen
    DartClient ---|"uses"| CodeGen
    KotlinClient ---|"uses"| CodeGen
    RustClient ---|"uses"| CodeGen
    SwiftClient ---|"uses"| CodeGen

    %% Interaction with JSON Schema Tools
    TS ---|"validates_with"| JsonSchema
    GO ---|"validates_with"| JsonSchema
    TSClient ---|"validates_with"| JsonSchema
    DartClient ---|"validates_with"| JsonSchema
    KotlinClient ---|"validates_with"| JsonSchema
    RustClient ---|"validates_with"| JsonSchema
    SwiftClient ---|"validates_with"| JsonSchema

    %% Build Scripts support CLI operations
    BuildScripts -->|"supports"| CLI

    %% Documenting the App Definition with Specifications
    Artifact -->|"documented_in"| Specs

    %% Optional integration testing from Utilities
    CodeGen ---|"integration_test"| TestSuite
    JsonSchema ---|"integration_test"| TestSuite

    %% Hot-reload mechanism from CLI back to Servers (asynchronous)
    CLI -.->|"hot-reload"| TS
    CLI -.->|"hot-reload"| GO

    %% Click Events
    click CLI "https://github.com/modiimedia/arri/tree/master/tooling/cli"
    click TS "https://github.com/modiimedia/arri/tree/master/languages/ts/ts-server"
    click GO "https://github.com/modiimedia/arri/tree/master/languages/go/go-server"
    click TSClient "https://github.com/modiimedia/arri/tree/master/languages/ts/ts-codegen"
    click DartClient "https://github.com/modiimedia/arri/tree/master/languages/dart/dart-codegen"
    click KotlinClient "https://github.com/modiimedia/arri/tree/master/languages/kotlin/kotlin-codegen"
    click RustClient "https://github.com/modiimedia/arri/tree/master/languages/rust/rust-codegen"
    click SwiftClient "https://github.com/modiimedia/arri/tree/master/languages/swift/swift-codegen"
    click CodeGen "https://github.com/modiimedia/arri/tree/master/tooling/codegen-utils"
    click JsonSchema "https://github.com/modiimedia/arri/tree/master/tooling/json-schema-to-atd"
    click Artifact "https://github.com/modiimedia/arri/blob/master/tests/test-files/AppDefinition.json"
    click TestSuite "https://github.com/modiimedia/arri/tree/master/tests"
    click Specs "https://github.com/modiimedia/arri/blob/master/specifications/arri_app_definition.md"
    click BuildScripts "https://github.com/modiimedia/arri/tree/master/internal/scripts"

    %% Styles
    classDef cli fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef server fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef artifact fill:#f94144,stroke:#333,stroke-width:2px;
    classDef client fill:#577590,stroke:#333,stroke-width:2px;
    classDef utility fill:#277da1,stroke:#333,stroke-width:2px;
    classDef test fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef spec fill:#6a4c93,stroke:#333,stroke-width:2px;
```
