# kaiofelps/samambaia-api architecture

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

- Interactive diagram: https://gitdiagram.com/kaiofelps/samambaia-api
- Repository: https://github.com/kaiofelps/samambaia-api

## Overview

##### Project type and purpose
- Project type: A monolithic backend API (Rust) implementing Clean Architecture principles, plus a companion CLI code-generator.
- Purpose: Provide a content-management API (users, roles, articles, comments, tags, badges, reports) for a Habbo fan-site, with a Rust CLI to scaffold new features.

##### File structure
- Top-level crates:
- root crate (src/) – main API server
- cli/ – the Samambaia CLI tool
- entities/ – ORM-generated domain model
- migration/ – ORM-scripted database migrations
- tests/ – integration tests
- Inside src/: Clean Architecture layers (core, domain, infra, http, util, libs, etc.)
- Config/deployment: Docker Compose (compose.yaml), .env, GitHub Actions workflows.

##### README for architecture notes
- Confirms use of Clean Architecture:
– /src/core, /src/domain (pure business rules), /src/infra (external implementations), /src/infra/http (API adapters)
– Sea-ORM for persistence, JWT for auth
– CLI for code generation via templates

##### Elements
- Clear labels on each component and layer
- Blue for Domain (pure business)
- Green for Infrastructure adapters
- Orange for API/HTTP layer
- Gray for Database and migrations
- Yellow for CLI

##### Detailed callouts
- In Infra-Persistence, show Sea-ORM Connection, Mappers, Repository Impl.
- Link JWT Service in Infra to its usage in HTTP Middlewares and Domain Services
- Docker Compose spinning up Postgres, and Migration crate applying schema

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client"]:::external

    %% API Layer
    subgraph "API Layer" 
        direction TB
        HTTPServer["HTTP Server (Tokio, Axum)"]:::api
        Routing["Routing (src/infra/http/routes)"]:::api
        Middlewares["Middlewares & Extractors"]:::api
        Controllers["Controllers"]:::api
        DTOs["DTOs"]:::api
        Presenters["Presenters"]:::api
    end

    %% Domain Layer
    subgraph "Domain Layer" 
        direction TB
        Entities["Domain Entities & Value Objects"]:::domain
        UseCases["Use-Case Services"]:::domain
        ReposTraits["Repository Contracts"]:::domain
        Factories["Factories"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        Cryptography["Cryptography Impl"]:::infra
        JWTService["JWT Service"]:::infra
        subgraph "Sea-ORM Adapters"
            direction TB
            SeaService["Sea-ORM Service"]:::infra
            Mappers["Mappers"]:::infra
            ReposImpl["Repository Impls"]:::infra
        end
    end

    %% Database Layer
    subgraph "Database"
        direction TB
        Postgres["PostgreSQL (Docker)"]:::db
        EntitiesCrate["Entities Crate"]:::db
        MigrationCrate["Migration Crate"]:::db
    end

    %% CLI Tool
    subgraph "Samambaia CLI" 
        direction TB
        CLIMain["CLI Executable"]:::cli
        CLIGenerators["CLI Generators & Helpers"]:::cli
        CLITemplates["CLI Templates"]:::cli
    end

    %% Docker & CI/CD
    DockerCompose["Docker Compose"]:::external
    CI["GitHub Actions"]:::external

    %% Data Flows
    Client -->|"HTTP Request"| HTTPServer
    HTTPServer -->|routes to| Routing
    Routing -->|invokes| Middlewares
    Middlewares -->|calls| Controllers
    Controllers -->|uses DTOs| DTOs
    Controllers -->|returns via| Presenters
    Controllers -->|calls| Factories
    Factories -->|injects| UseCases
    UseCases -->|depend on| Entities
    UseCases -->|use| ReposTraits
    ReposTraits -->|fulfilled by| ReposImpl
    ReposImpl -->|uses| Mappers
    ReposImpl -->|calls| SeaService
    SeaService -->|executes SQL on| Postgres
    MigrationCrate -->|applies migrations to| Postgres
    JWTService -->|used in| Middlewares
    JWTService -->|token generation in| UseCases

    %% CLI Flows
    CLIMain -->|loads| CLIGenerators
    CLIMain -->|reads| CLITemplates
    CLIMain -->|writes scaffold to| src

    %% External flows
    DockerCompose -->|spins up| Postgres
    CI -->|runs tests| HTTPServer

    %% Click Events
    click HTTPServer "https://github.com/kaiofelps/samambaia-api/blob/main/src/main.rs"
    click Routing "https://github.com/kaiofelps/samambaia-api/blob/main/src/infra/http/routes/api.rs"
    click Controllers "https://github.com/kaiofelps/samambaia-api/tree/main/src/infra/http/controllers/"
    click DTOs "https://github.com/kaiofelps/samambaia-api/tree/main/src/infra/http/dtos/"
    click Presenters "https://github.com/kaiofelps/samambaia-api/tree/main/src/infra/http/presenters/"
    click Middlewares "https://github.com/kaiofelps/samambaia-api/blob/main/src/infra/http/middlewares/authentication.rs"
    click Entities "https://github.com/kaiofelps/samambaia-api/tree/main/src/domain/domain_entities/"
    click UseCases "https://github.com/kaiofelps/samambaia-api/tree/main/src/domain/services/"
    click ReposTraits "https://github.com/kaiofelps/samambaia-api/tree/main/src/domain/repositories/"
    click Factories "https://github.com/kaiofelps/samambaia-api/tree/main/src/domain/factories/"
    click Cryptography "https://github.com/kaiofelps/samambaia-api/blob/main/src/infra/cryptography/password_auth_hasher_and_verifier.rs"
    click JWTService "https://github.com/kaiofelps/samambaia-api/blob/main/src/infra/jwt/jwt_service.rs"
    click Mappers "https://github.com/kaiofelps/samambaia-api/tree/main/src/infra/sea/mappers/"
    click ReposImpl "https://github.com/kaiofelps/samambaia-api/tree/main/src/infra/sea/repositories/"
    click SeaService "https://github.com/kaiofelps/samambaia-api/blob/main/src/infra/sea/sea_service.rs"
    click EntitiesCrate "https://github.com/kaiofelps/samambaia-api/tree/main/entities/src/"
    click MigrationCrate "https://github.com/kaiofelps/samambaia-api/tree/main/migration/src/"
    click CLIMain "https://github.com/kaiofelps/samambaia-api/blob/main/cli/src/main.rs"
    click CLIGenerators "https://github.com/kaiofelps/samambaia-api/tree/main/cli/src/generators/"
    click CLITemplates "https://github.com/kaiofelps/samambaia-api/tree/main/cli/src/templates/"
    click DockerCompose "https://github.com/kaiofelps/samambaia-api/blob/main/compose.yaml"
    click CI "https://github.com/kaiofelps/samambaia-api/tree/main/.github/workflows/"

    %% Styles
    classDef api fill:#FFA500,stroke:#333,stroke-width:1px,color:#000
    classDef domain fill:#1E90FF,stroke:#333,stroke-width:1px,color:#fff
    classDef infra fill:#32CD32,stroke:#333,stroke-width:1px,color:#000
    classDef db fill:#A9A9A9,stroke:#333,stroke-width:1px,color:#000
    classDef cli fill:#FFD700,stroke:#333,stroke-width:1px,color:#000
    classDef external fill:#D8BFD8,stroke:#333,stroke-width:1px,color:#000
```
