# loco-rs/loco architecture

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

- Interactive diagram: https://gitdiagram.com/loco-rs/loco
- Repository: https://github.com/loco-rs/loco

## Overview

##### Main Components
- Core Framework (located in the “src” directory): This includes application logic, controllers, routes, middleware, ORM/model handling, and templating (views and mailers).
- CLI and Code Generation Tools:
- loco-cli: Provides command-line interface tools.
- loco-gen: Contains scaffolding logic to generate controllers, templates, migrations, mailers, and more.
- loco-new: A template and project generator for creating new Loco apps.
- Background Processing and Scheduler:
- bgworker: For handling asynchronous tasks and background jobs.
- Scheduler: Simplified task scheduling.
- Services Integration:
- Authentication (src/auth)
- Caching (src/cache)
- Storage: Various storage drivers for local and cloud-based, plus file management.
- Mailers (src/mailer): For sending emails.
- Testing and Documentation:
- Extensive tests across controllers, migrations, templates, and even CLI.
- A dedicated “docs-site” for the project’s documentation.
- Infrastructure and Build Tools:
- xtask: Custom build/automation tasks.
- Various configuration files (Cargo.toml, .github workflows, etc.) indicate CI/CD and deployment practices.

##### Relationships and Interactions
- The CLI (loco-cli) and generator (loco-gen) feed into the “loco-new” system, allowing developers to scaffold a new full-stack web application.
- A request enters via a Router (using Axum as mentioned in the README) → passes through Middleware (authentication, CORS, logging, etc.) → is handled by a Controller (located in src/controller) → interacts with Models/ORM for data → and then a response is rendered (using templating engines integrated with views).
- Background processing architecture:
- A scheduler can trigger background jobs, which are then processed by specific workers in bgworker.
- External integrations:
- Storage drivers abstract different cloud or local file systems.
- Cache layer integrations for performance improvements.
- Mailer module that leverages background jobs for asynchronous email delivery.

##### Architectural Patterns and Design Principles
- Convention Over Configuration: Emphasize that defaults (found in configuration templates in loco-new) reduce boilerplate.
- Modular and Extensible Design: The system is built in a modular fashion. Each element (controllers, views, models, middleware, etc.) is in its own namespace/module.
- Utility/Tooling Separation: Tools like loco-cli and loco-gen are separate from the core runtime but are critical in the developer experience.

##### Relevant Technologies and Frameworks
- Rust as the main language.
- Axum for web routing and HTTP handling.
- Additional dependencies likely relate to database operations (ORM integration) and asynchronous task processing (Tokio for async background tasks).
- Templating engines and static asset management are part of view/mailer rendering.
- Deployment templates: Docker, Nginx, and configurations for services (present in loco-gen templates).

##### Detail and Precision
- Avoid oversimplification: capture as many architectural components as possible.
- Configurations and deployment aspects separately if needed (e.g., configuration templates, CI/CD workflows in .github, xtask for build automation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Tools Layer
    subgraph "Developer Tools"
        CLI["loco-cli (CLI Tools)"]:::developer
        GEN["loco-gen (Code Scaffolding)"]:::developer
        NEW["loco-new (Project Generator)"]:::developer
    end

    %% Core Runtime Layer
    subgraph "Core Runtime"
        CF["Core Framework (src)"]:::core
        subgraph "Request Flow"
            R["Router (Axum)"]:::core
            M["Middleware (Auth,CORS,Logging)"]:::core
            C["Controller"]:::core
            O["ORM/Models"]:::core
            V["Views/Templating"]:::core
        end
        CF --> R
        R -->|"process"| M
        M -->|"process"| C
        C -->|"data_access"| O
        O -->|"render"| V
    end

    %% External Services Layer
    subgraph "External Services"
        A["Authentication (src/auth)"]:::external
        CA["Caching (src/cache)"]:::external
        ST["Storage (src/storage)"]:::external
        MA["Mailers (src/mailer)"]:::external
    end

    %% Background Processing Layer
    subgraph "Background Processing"
        BW["Background Worker (src/bgworker)"]:::background
        SCH["Scheduler (src/scheduler.rs)"]:::background
    end

    %% Testing & Documentation Layer
    subgraph "Testing & Documentation"
        T["Tests (tests)"]:::testing
        DOC["Documentation Site (docs-site)"]:::testing
    end

    %% Infrastructure & Build Tools
    I["xtask (Build Tools)"]:::infra

    %% Connections between layers
    %% Developer Tools -> Core Runtime
    NEW -->|"scaffolds_new_project"| CF

    %% Core interactions with External Services
    M -->|"validates"| A
    C -->|"uses_cache"| CA
    C -->|"uploads_to"| ST
    C -->|"sends_mail"| MA

    %% Core triggering Background Processing
    C -->|"triggers_job"| SCH
    SCH -->|"dispatches"| BW

    %% Optionally, testing and infra touchpoints (illustrative)
    CF ---|"tested_by"| T
    CF ---|"documented_by"| DOC
    CF ---|"built_with"| I

    %% Click Events for Developer Tools and Core Components
    click CF "https://github.com/loco-rs/loco/tree/master/src"
    click CLI "https://github.com/loco-rs/loco/tree/master/loco-cli"
    click GEN "https://github.com/loco-rs/loco/tree/master/loco-gen"
    click NEW "https://github.com/loco-rs/loco/tree/master/loco-new"
    click BW "https://github.com/loco-rs/loco/tree/master/src/bgworker"
    click SCH "https://github.com/loco-rs/loco/blob/master/src/scheduler.rs"
    click A "https://github.com/loco-rs/loco/tree/master/src/auth"
    click CA "https://github.com/loco-rs/loco/tree/master/src/cache"
    click ST "https://github.com/loco-rs/loco/tree/master/src/storage"
    click MA "https://github.com/loco-rs/loco/tree/master/src/mailer"
    click T "https://github.com/loco-rs/loco/tree/master/tests"
    click DOC "https://github.com/loco-rs/loco/tree/master/docs-site"
    click I "https://github.com/loco-rs/loco/tree/master/xtask"

    %% Styles
    classDef developer fill:#FFDEAD,stroke:#000,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef background fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef testing fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef infra fill:#FFA07A,stroke:#000,stroke-width:2px;
```
