# kaiofelps/rust-e2e-test-poc architecture

> Architecture diagram of the GitHub repository kaiofelps/rust-e2e-test-poc, 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/rust-e2e-test-poc
- Repository: https://github.com/kaiofelps/rust-e2e-test-poc

## Overview

##### Project Type and Purpose
- This is a full-stack “todo list” proof-of-concept application, built to demonstrate asynchronous end-to-end tests of HTTP endpoints (views and actions).
- The front end is a React/Inertia/Vite application written in TypeScript; the back end is a Rust web server using SQLx (or SeaORM patterns) for persistence and Inertia for view rendering. Docker Compose orchestrates the Postgres database and any other services.

##### High-Level Architecture
- The system splits cleanly into four main layers:
a. Client (React/Inertia front end)
b. HTTP/API Layer (Rust controllers & DTOs via Inertia)
c. Domain & Service Layer (Rust domain entities, repositories, services)
d. Infrastructure & Data Layer (SQLx repos, Postgres, session store)

##### File-Structure Indicators
- Top-level:
- www/ – front-end source (React components, pages, layouts, types)
- src/ – Rust back-end source (common, config, domain, infra, main.rs)
- migrations/ – SQL migrations for Postgres schema
- compose.yaml – Docker Compose specification (Postgres container)
- GitHub workflows – CI pipelines (unit tests, integration/E2E tests)
- Clean Architecture pattern: domain/entities → domain/services → infra/repositories → infra/http/controllers.

##### Components
A. Front-End Client
- Vite Dev Server (www/app.tsx → pages & components)
- Inertia Client Adapter (JavaScript communicates via X-Inertia headers)
B. Back-End Server
- HTTP Entry Point (src/main.rs)
- Controllers & Presenters (src/infra/http/controllers & presenters)
- DTOs (src/infra/http/dtos)
- Session Middleware (file-based sessions under src/infra/sessions)
C. Domain & Business Logic
- Entities (src/domain/entities)
- Services (create, fetch paginated) under src/domain/services
- Repositories Interfaces (src/domain/repositories)
D. Persistence
- SQLx Repository Implementations (src/infra/sqlx/repositories)
- Migrations and Postgres DB (Docker container)
E. Testing & CI
- Cargo Tests (unit & integration under tests/)
- E2E Tests (GitHub workflow, uses Docker Compose test DB)

##### Interactions and Data Flow
1. User Action in Browser → HTTP Request (Inertia X-Inertia header)
2. Routing in Rust (actix-web or similar) → Controller
3. Controller extracts DTO, calls Domain Service
4. Domain Service invokes Repository Interface → SQLx adapter → Postgres
5. Query result → Domain Entity → Presenter → Inertia Response (JSON + page props)
6. Front end hydrates React components with returned props

##### Architectural Patterns & Principles
- Clean Architecture / Hexagonal: separation of concerns (domain vs. infra)
- Dependency inversion: domain defines interfaces, infra provides implementations
- Inertia “single-page” server-driven UI, eliminating a standalone REST layer
- Session management via middleware chain

##### Technologies & Frameworks
- Front end: React, TypeScript, Vite, Inertia.js
- Back end: Rust (actix-web or Rocket), SQLx, rstest (for fixtures), dotenv, file-based sessions
- Database: Postgres (Docker Compose)
- CI: GitHub Actions (unit + integration + e2e workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Browser
    Browser["User Browser"]:::external

    %% Front-End Layer
    subgraph "Front-End (www/)" 
        style FrontEnd fill:#E3F2FD,stroke:#42A5F5
        Vite["Vite Dev Server"]:::frontend
        InertiaClient["Inertia Client Adapter"]:::frontend
        Pages["Pages & Components"]:::frontend
    end

    %% Back-End HTTP/API Layer
    subgraph "Back-End HTTP/API (src/infra/http & src)" 
        style API fill:#C8E6C9,stroke:#66BB6A
        Main["HTTP Entry Point\n(src/main.rs)"]:::api
        ControllerTrait["BaseController Trait"]:::api
        Controller["TodosController"]:::api
        DTO["Todo DTO"]:::api
        PresenterTodo["Todo Presenter"]:::api
        PresenterPagination["Pagination Presenter"]:::api
        PresenterPaginatedEntity["Paginated Entity Presenter"]:::api
        SessionStore["File-Based Session Store"]:::api
        SessionHelpers["Session Helpers"]:::api
        MiddlewareGC["Garbage-Collector Middleware"]:::api
        MiddlewareReflash["Reflash Temp Session Middleware"]:::api
    end

    %% Domain & Business Logic Layer
    subgraph "Domain & Business Logic (src/domain)" 
        style Domain fill:#FFE0B2,stroke:#FB8C00
        EntityTodo["Todo Entity"]:::domain
        ServiceCreate["CreateTodoService"]:::domain
        ServiceFetch["FetchPaginatedTodos"]:::domain
        RepoInterface["TodosRepository Interface"]:::domain
    end

    %% Infrastructure & Data Layer
    subgraph "Infrastructure & Data (src/infra & migrations & compose.yaml)" 
        style Infra fill:#CFD8DC,stroke:#78909C
        SQLxRepo["Todos SQLx Repository"]:::infra
        Factories["Factory Bindings"]:::infra
        DB["Postgres DB"]:::infra
        Migrations["DB Migrations"]:::infra
    end

    %% Testing & CI
    subgraph "Testing & CI" 
        style Test fill:#FFF9C4,stroke-dasharray: 5 5
        UnitTests["Unit Tests (Cargo)"]:::test
        IntegrationWorkflow["Integration & Pipeline Workflow"]:::test
        E2EWorkflow["E2E & Integration Tests Workflow"]:::test
        DockerComposeTest["Docker Compose Test Env"]:::test
        Fixtures["Test Harness & Fixtures"]:::test
    end

    %% Data Flows
    Browser -->|"HTTP Inertia"| Vite
    Vite -->|"X-Inertia Headers"| InertiaClient
    InertiaClient -->|"HTTP Request"| Main
    Main -->|"middleware"| SessionGC{Session Middleware Chain}
    SessionGC --> SessionStore
    SessionGC --> SessionHelpers
    SessionStore --> MiddlewareReflash
    SessionHelpers --> Controller
    MiddlewareReflash --> Controller
    Main --> ControllerTrait
    ControllerTrait --> Controller
    Controller -->|"parse DTO"| DTO
    Controller -->|"CreateTodo / FetchPaginated"| ServiceCreate
    Controller -->|"CreateTodo / FetchPaginated"| ServiceFetch
    ServiceCreate --> RepoInterface
    ServiceFetch --> RepoInterface
    RepoInterface --> SQLxRepo
    SQLxRepo -->|"SQLx Queries"| DB
    DB -->|"Result Rows"| SQLxRepo
    SQLxRepo --> RepoInterface
    RepoInterface --> ServiceFetch
    ServiceFetch --> PresenterPaginatedEntity
    ServiceCreate --> PresenterTodo
    PresenterTodo --> InertiaClient
    PresenterPagination --> InertiaClient
    PresenterPaginatedEntity --> InertiaClient
    InertiaClient -->|"JSON + Props"| Browser

    %% Testing flows
    E2EWorkflow --> DockerComposeTest
    DockerComposeTest --> Browser
    DockerComposeTest --> Main
    DockerComposeTest --> DB
    UnitTests --> ServiceCreate
    UnitTests --> ServiceFetch
    IntegrationWorkflow --> Main
    IntegrationWorkflow --> DB
    IntegrationWorkflow --> SQLxRepo
    Fixtures --> UnitTests
    Fixtures --> IntegrationWorkflow

    %% Click Events
    click Vite "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/www/app.tsx"
    click InertiaClient "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/www/libs/hooks/use-typed-page.tsx"
    click Pages "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/www/pages/index.tsx"
    click Main "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/main.rs"
    click Controller "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/http/controllers/todos_controller.rs"
    click ControllerTrait "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/http/controllers/controller.rs"
    click DTO "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/http/dtos/todo_dto.rs"
    click PresenterTodo "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/http/presenters/todo_presenter.rs"
    click PresenterPagination "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/http/presenters/pagination_presenter.rs"
    click PresenterPaginatedEntity "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/http/presenters/paginated_entity_presenter.rs"
    click SessionStore "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/sessions/file_session.rs"
    click SessionHelpers "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/sessions/helpers.rs"
    click MiddlewareGC "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/sessions/middlewares/garbage_collector.rs"
    click MiddlewareReflash "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/sessions/middlewares/reflash_temporary_session.rs"
    click EntityTodo "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/domain/entities/todo.rs"
    click ServiceCreate "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/domain/services/todo/create_todo_service.rs"
    click ServiceFetch "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/domain/services/todo/fetch_paginated_todos.rs"
    click RepoInterface "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/domain/repositories/todos_repository.rs"
    click SQLxRepo "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/sqlx/repositories/todos_repository.rs"
    click Factories "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/src/infra/factories/services/todo.rs"
    click Migrations "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/migrations/20250419004604_create_todos_table.up.sql"
    click UnitTests "https://github.com/kaiofelps/rust-e2e-test-poc/tree/main/tests/"
    click IntegrationWorkflow "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/.github/workflows/pipeline.yaml"
    click E2EWorkflow "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/.github/workflows/e2e-and-integration-tests.yaml"
    click DockerComposeTest "https://github.com/kaiofelps/rust-e2e-test-poc/blob/main/compose.yaml"
    click Fixtures "https://github.com/kaiofelps/rust-e2e-test-poc/tree/main/tests/common/fixtures/"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#42A5F5
    classDef api fill:#C8E6C9,stroke:#66BB6A
    classDef domain fill:#FFE0B2,stroke:#FB8C00
    classDef infra fill:#CFD8DC,stroke:#78909C
    classDef test fill:#FFF9C4,stroke:#FDD835,stroke-dasharray: 5 5
    classDef external fill:#FFFFFF,stroke:#000000,stroke-width:1px,stroke-dasharray: 2 2
```
