# sohosai/sos24-server architecture

> Architecture diagram of the GitHub repository sohosai/sos24-server, 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/sohosai/sos24-server
- Repository: https://github.com/sohosai/sos24-server

## Overview

##### Project Type and Overall Purpose
- The README clearly states that this is the “sos24-server” providing the backend for the online system.
- Its responsibilities include serving HTTP APIs, handling domain logic, executing use cases, managing database migrations (with sqlx), and interacting with external services (like Firebase, SendGrid, and others).
- The system uses Docker (with devcontainer and several docker-compose files) to manage environment runtimes and CI/CD pipelines are automated in GitHub Actions.

##### File Structure for Architectural Components
- The project is organized as a multi-crate Cargo workspace within the “crates” directory. The main crates are:
- sos24-domain – Contains domain entities and repository interfaces.
- sos24-infrastructure – Implements external dependencies and adapters (e.g., email, S3, MongoDB, PostgreSQL, Firebase).
- sos24-presentation – Acts as the API layer (HTTP server, routing, middleware, error handling, etc.).
- sos24-use-case – Encapsulates business logic and application use cases.
- Additional configuration and support directories:
- Migrations – Database migration scripts.
- .devcontainer and docker-compose files – Containerization and deployment configurations.
- .github/workflows – CI/CD pipelines.
- sqlx query cache files – Precompiled queries for sqlx indicating an emphasis on performance and type safety.

##### Mapping Components and Their Interactions
- Front Door / API Layer: The sos24-presentation crate handles HTTP routing with clearly defined subdirectories for routes, middleware, and configuration.
- Domain Model: The sos24-domain crate outlines the core entities like User, Form, Project, Invitation, etc. It also defines the repository layer interfaces.
- Business Logic / Use Cases: The sos24-use-case crate contains interactors that implement the specific application logic (e.g., for creating or deleting forms, handling notifications, uploading files).
- Infrastructure/Adapters: The sos24-infrastructure crate implements adapters for external services such as email (SendGrid), file storage (S3), and possibly Firebase authentication.
- Data Persistence: The presence of migration scripts and sqlx cache files indicates the use of a relational database (likely PostgreSQL) for persistence.
- CI/CD and Deployment: Config files (Dockerfile, docker-compose, devcontainer files, GitHub workflows) show that the system is containerized and can be automatically deployed in different environments (prod, beta, staging).

##### Highlighting Architectural Patterns and Principles
- Layered/Clean Architecture: Each crate is responsible for a specific layer (domain, use-case, presentation, infrastructure).
- Separation of Concerns: The clear separation into domain, infrastructure, use case, and presentation ensures modularity.
- Dependency Inversion: Domain logic is isolated from infrastructure concerns.
- Containerization: Deployment is managed via Docker and Devcontainer setups; CI/CD pipelines are present to maintain code integration quality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Architecture Subgraph
    subgraph "Core Architecture"
        Client["Client Request"]:::external
        APIPresentation["sos24-presentation: API & Routing"]:::presentation
        UseCase["sos24-use-case: Business Logic"]:::usecase
        Domain["sos24-domain: Domain Models & Interfaces"]:::domain
        Infras["sos24-infrastructure: External Adapters"]:::infrastructure
        subgraph "Data Persistence"
            Database["Database (PostgreSQL)"]:::pers
            Migrations["Migrations Scripts"]:::pers
            SQLxCache["SQLx Query Cache"]:::pers
        end
        ExternalServices["External Systems (Firebase,SendGrid,S3,MongoDB)"]:::external
    end

    %% Deployment & Operations Subgraph
    subgraph "Deployment & Operations"
        CICD["CI/CD Pipelines"]:::deployment
        Container["Containerization & Dev Config"]:::deployment
    end

    %% Connections for Core Architecture
    Client -->|"sends request"| APIPresentation
    APIPresentation -->|"forwards"| UseCase
    UseCase -->|"invokes"| Domain
    Domain -->|"calls"| Infras
    Infras -->|"persists data"| Database
    Infras -->|"uses"| ExternalServices
    Database -->|"maintained by"| Migrations
    Database -->|"optimized by"| SQLxCache

    %% Connections for Deployment & Operations (side integration)
    CICD ---|"automates build & deploy"| APIPresentation
    CICD ---|"automates build & deploy"| UseCase
    CICD ---|"automates build & deploy"| Domain
    CICD ---|"automates build & deploy"| Infras
    Container ---|"hosts"| APIPresentation
    Container ---|"hosts"| Infras

    %% Click Events for Component Mapping
    click APIPresentation "https://github.com/sohosai/sos24-server/tree/main/crates/sos24-presentation"
    click UseCase "https://github.com/sohosai/sos24-server/tree/main/crates/sos24-use-case"
    click Domain "https://github.com/sohosai/sos24-server/tree/main/crates/sos24-domain"
    click Infras "https://github.com/sohosai/sos24-server/tree/main/crates/sos24-infrastructure"
    click Migrations "https://github.com/sohosai/sos24-server/tree/main/migrations"
    click SQLxCache "https://github.com/sohosai/sos24-server/blob/main/.sqlx"
    click CICD "https://github.com/sohosai/sos24-server/tree/main/.github/workflows"
    click Container "https://github.com/sohosai/sos24-server/blob/main/.devcontainer"

    %% Styles
    classDef presentation fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef usecase fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef domain fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef infrastructure fill:#cce6ff,stroke:#0033cc,stroke-width:2px;
    classDef pers fill:#f0e68c,stroke:#b8860b,stroke-width:2px;
    classDef external fill:#e6ccff,stroke:#800080,stroke-width:2px;
    classDef deployment fill:#d3d3d3,stroke:#696969,stroke-width:2px;
```
