# salvo-rs/salvo architecture

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

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

## Overview

Based on our analysis of the complete file tree and the README, this project is an open‐source web backend framework written in Rust (called “Salvo”) that is extremely modular and extensible. It is designed as a full‐featured server framework with support for HTTP1/2/3, middleware chaining, ACME-based automatic TLS, routing, and even integration with OpenAPI and more. The project is partitioned into many separate crates, each encapsulating a specific functionality or service (for example, “core”, “cache”, “compression”, “cors”, “csrf”, “flash”, “jwt-auth”, “oapi”, etc.) while also providing a consistent API for the end developer.

##### Main Components
- Client Interface: Illustrate external HTTP/HTTPS/HTTP3 clients that connect via TCP.
- Listener/Server: Represent the TCP listeners that bind to various ports (80, 443, etc.) and include support for multiple transport protocols (using underlying libraries like native_tls, rustls, quinn, openssl).
- Core Engine: Identify the “core” crate, which contains modules for connection management, HTTP request/response handling, routing, middleware processing, error handling, and extraction.
- Middleware Layer: Show how middleware functions (which are essentially handlers themselves) are applied before or after the main business logic. This includes middleware for adding headers, authentication checks, logging, error handling, etc.
- Utilities and Extensions: Illustrate supporting crates such as “cache”, “compression”, “cors”, “csrf”, “flash”, “jwt-auth”, “rate-limiter”, “serve-static”, “session” and “extra”. These add specialized functionality and plug into the overall request handling and response pipeline.
- Interface/DSL Macros: Include the “craft-macros”, “oapi-macros”, and “macros” crates that provide custom derive traits, attribute macros, and OpenAPI documentation integration.
- OpenAPI and Documentation: Represent the components (found inside “oapi” and associated macros) that automatically generate and serve OpenAPI documentation.
- External Dependencies: Note the reliance on the Tokio asynchronous runtime and Hyper as well as integration with other services (e.g., external proxies, OpenTelemetry for tracing, etc.).

##### Relationships and Interactions
- From the TCP listener, show the data flow into the “core” module where connection handling and protocol negotiation happens (sometimes via separate modules based on the TLS/HTTP version).
- Inside the core, branch off to the routing module responsible for mapping the inbound request to the correct handler or middleware chain.
- Middleware components (possibly as overlays on the routing paths) indicating that these can be attached to any route to modify requests/responses.
- Link utilities (cache, compression, CSRF, etc.) to the core flow to illustrate the extension points.
- Provide a separate block for OpenAPI generation and documentation, showing its connection to the router and the endpoint handlers.
- Support for various TLS libraries within the connection handling part (native_tls, openssl, rustls, quinn).

##### Architectural Patterns/Design Principles
- Layered Architecture: Separate concerns by isolating the transport (TCP/HTTP) from application-level routing and middleware.
- Modular Design: Illustrate how the project is divided into many crates, each encapsulating unique functionality.
- Middleware as a First-class Citizen: Indicate the chainable and composable nature of middleware (no distinction between middleware and handler).
- Protocol Abstraction: Demonstrate support for multiple protocols (HTTP1, HTTP2, HTTP3) by abstracting over the underlying protocol-specific modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client("HTTP/HTTPS/HTTP3 Clients"):::external

    %% Async Runtime as underlying dependency
    Runtime("Async Runtime & Hyper"):::runtime

    %% Listener/Server
    Listener("TCP Listener/Server"):::listener

    %% Core Engine
    Core("Core Engine"):::core

    %% Routing Subsystem
    subgraph "Routing Subsystem"
        direction TB
        Router("Router Module"):::router
        Filters("Routing Filters"):::router
    end

    %% Middleware Layer
    Middleware("Middleware Layer"):::middleware

    %% Utilities and Extensions (chained vertically)
    subgraph "Utilities & Extensions"
        direction TB
        Cache("Cache"):::utility
        Compression("Compression"):::utility
        CORS("CORS"):::utility
        CSRF("CSRF"):::utility
        Flash("Flash"):::utility
        JWT("JWT Authentication"):::utility
        RateLimiter("Rate-limiter"):::utility
        ServeStatic("Serve Static"):::utility
        Session("Session"):::utility
        Extra("Extra"):::utility
    end

    %% Interface/DSL Macros
    subgraph "Interface/DSL Macros"
        direction TB
        Craft("Craft Macros"):::macro
        OAPIM("OAPI Macros"):::macro
        General("General Macros"):::macro
    end

    %% OpenAPI Documentation
    OpenAPI("OpenAPI Documentation"):::openapi

    %% ACME & TLS Automation
    subgraph "ACME & TLS Automation"
        direction TB
        ACME("ACME Integration"):::tls
        Native("Native TLS Support"):::tls
        OpenSSL("OpenSSL TLS Support"):::tls
        Rustls("Rustls TLS Support"):::tls
        QUIC("QUIC Support"):::tls
    end

    %% Flow connections
    Client -->|"connects via TCP"| Listener
    Runtime -->|"supports"| Listener
    Listener -->|"passes connection to"| Core
    Core -->|"handles routing via"| Router
    Core -->|"applies middleware"| Middleware
    Core -->|"delegates to"| Filters
    Core -->|"integrates utilities"| Cache
    Core -->|"integrates utilities"| Compression
    Core -->|"integrates utilities"| CORS
    Core -->|"integrates utilities"| CSRF
    Core -->|"integrates utilities"| Flash
    Core -->|"integrates utilities"| JWT
    Core -->|"integrates utilities"| RateLimiter
    Core -->|"integrates utilities"| ServeStatic
    Core -->|"integrates utilities"| Session
    Core -->|"integrates utilities"| Extra
    Core -->|"uses macros"| Craft
    Core -->|"uses macros"| OAPIM
    Core -->|"uses macros"| General
    OAPIM -->|"generates docs"| OpenAPI
    Core -->|"manages TLS"| ACME
    Core -->|"manages TLS"| Native
    Core -->|"manages TLS"| OpenSSL
    Core -->|"manages TLS"| Rustls
    Core -->|"manages TLS"| QUIC

    %% Class Definitions with Colors
    classDef external fill:#ffe6e6,stroke:#ff0000,stroke-width:2px,font-weight:bold;
    classDef runtime fill:#e6e6ff,stroke:#0000ff,stroke-width:2px,font-weight:bold;
    classDef listener fill:#e6ffe6,stroke:#008000,stroke-width:2px,font-weight:bold;
    classDef core fill:#fff0b3,stroke:#e68a00,stroke-width:2px,font-weight:bold;
    classDef router fill:#f0e6ff,stroke:#8000ff,stroke-width:2px,font-weight:bold;
    classDef middleware fill:#e6fff0,stroke:#00cc66,stroke-width:2px,font-weight:bold;
    classDef utility fill:#f2f2f2,stroke:#666666,stroke-width:2px;
    classDef macro fill:#ffe6ff,stroke:#ff66ff,stroke-width:2px;
    classDef openapi fill:#e6f7ff,stroke:#3399ff,stroke-width:2px,font-weight:bold;
    classDef tls fill:#fff2e6,stroke:#ff9900,stroke-width:2px,font-weight:bold;

    %% Click Events for Component Mapping
    click Listener "https://github.com/salvo-rs/salvo/blob/main/crates/core/src/server.rs"
    click Core "https://github.com/salvo-rs/salvo/blob/main/crates/core/src/lib.rs"
    click Router "https://github.com/salvo-rs/salvo/blob/main/crates/core/src/routing/router.rs"
    click Filters "https://github.com/salvo-rs/salvo/tree/main/crates/core/src/routing/filters"
    click Middleware "https://github.com/salvo-rs/salvo/blob/main/crates/core/src/handler.rs"
    click Cache "https://github.com/salvo-rs/salvo/blob/main/crates/cache/src/lib.rs"
    click Compression "https://github.com/salvo-rs/salvo/blob/main/crates/compression/src/lib.rs"
    click CORS "https://github.com/salvo-rs/salvo/blob/main/crates/cors/src/lib.rs"
    click CSRF "https://github.com/salvo-rs/salvo/blob/main/crates/csrf/src/lib.rs"
    click Flash "https://github.com/salvo-rs/salvo/blob/main/crates/flash/src/lib.rs"
    click JWT "https://github.com/salvo-rs/salvo/blob/main/crates/jwt-auth/src/lib.rs"
    click RateLimiter "https://github.com/salvo-rs/salvo/blob/main/crates/rate-limiter/src/lib.rs"
    click ServeStatic "https://github.com/salvo-rs/salvo/blob/main/crates/serve-static/src/lib.rs"
    click Session "https://github.com/salvo-rs/salvo/blob/main/crates/session/src/lib.rs"
    click Extra "https://github.com/salvo-rs/salvo/blob/main/crates/extra/src/lib.rs"
    click Craft "https://github.com/salvo-rs/salvo/blob/main/crates/craft-macros/src/lib.rs"
    click OAPIM "https://github.com/salvo-rs/salvo/blob/main/crates/oapi-macros/src/lib.rs"
    click General "https://github.com/salvo-rs/salvo/blob/main/crates/macros/src/lib.rs"
    click OpenAPI "https://github.com/salvo-rs/salvo/blob/main/crates/oapi/src/lib.rs"
    click ACME "https://github.com/salvo-rs/salvo/tree/main/crates/core/src/conn/acme"
    click Native "https://github.com/salvo-rs/salvo/tree/main/crates/core/src/conn/native_tls"
    click OpenSSL "https://github.com/salvo-rs/salvo/tree/main/crates/core/src/conn/openssl"
    click Rustls "https://github.com/salvo-rs/salvo/tree/main/crates/core/src/conn/rustls"
    click QUIC "https://github.com/salvo-rs/salvo/tree/main/crates/core/src/conn/quinn"
```
