# lit-innosence/tus_yuurikai_system architecture

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

- Interactive diagram: https://gitdiagram.com/lit-innosence/tus_yuurikai_system
- Repository: https://github.com/lit-innosence/tus_yuurikai_system

## Overview

##### Project Type & Purpose
- Full-stack, containerized locker-rental application.
- Frontend: React/TypeScript SPA for users and admins.
- Backend: Rust API using Rocket + Diesel ORM on PostgreSQL.
- Purpose: secure locker reservations via system authentication and e-mail verification.

##### Main Components
a. Frontend SPA
- React app, built via npm scripts, served as static assets.
- Key modules:
- Routes & Pages (login, locker search, registration, admin pages)
- State management (Recoil) & API calls (axios, React Query)
- Auth component (OAuth with Outlook)
b. Backend API Service
- Rust Rocket server exposing REST/OpenAPI endpoints (utoipa).
- Layered into:
- Controller (HTTP models → use-cases)
- Use-case services (business logic)
- Domain entities (student, locker, assignment, auth)
- Adapters → repository interfaces for persistence
- Infrastructure/ORM layer (Diesel models, migrations)
c. Database
- PostgreSQL container
- Tables: student, student_pair, locker, assignment_record, auth, admin, locker_auth_info, circle_auth_info, etc.
d. External Services
- SMTP server (Lettre) for sending authentication emails.
- OAuth provider (Outlook API via reqwest for login).
- (Optional) reCAPTCHA verification via Google.

##### Relationships & Data Flow
- Browser → Frontend SPA
- User interactions trigger React Router navigation, form submissions.
- Frontend issues HTTPS requests (axios) to Rocket API.
- Frontend → Backend
- Authenticated calls include JWT (jsonwebtoken).
- File uploads/downloads handled via API.
- Backend layering:
- Controller layer receives HTTP, deserializes JSON (serde), forwards to use-cases.
- Use-case layer applies business rules, calls repository interfaces.
- Repository adapters translate calls into SQL via Diesel, return domain models.
- Domain layer handles invariants and aggregates.
- Infrastructure layer manages database schemas, Diesel connection pooling, migrations.
- Backend → Database
- Diesel executes SQL migrations, queries, and commands.
- Data persisted in Postgres volumes.
- Backend → External service
- Email dispatch via lettre SMTP.
- OAuth handshake via reqwest.

##### Architectural Patterns & Design Principles
- Hexagonal (Ports & Adapters) / Clean Architecture:
- Adapters directory for controllers and repositories.
- Domain and use-case separation ensures testability (see tests/ folder).
- Layered decomposition: HTTP → Controller → Use-case → Domain → Repository → DB.
- Containerization & isolation: Dockerfile for app, separate network for DB.

##### Essential Elements
- Clear labels: “React App”, “Rust Rocket API”, “PostgreSQL”
- Sub-component labels: “Controller Layer”, “Use-case Services”, “Diesel ORM”
- Data flows:
- Client → Frontend (HTTP UI)
- Frontend → API (HTTPS JSON)
- API → DB (SQL)
- API → SMTP (SMTP)
- API → OAuth (HTTPS REST)
- Blue for frontend, orange for backend, green for database, gray for external.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        U["User Browser"]:::external
        A["Admin Browser"]:::external
    end

    %% Frontend SPA
    subgraph "Frontend SPA"
        FE["React SPA"]:::frontend
        FR["Routes & Pages"]:::frontend
        FS["State Management (Recoil)"]:::frontend
        FA["Auth Component"]:::frontend
    end

    %% Docker Network
    subgraph "Docker: tus_network"
        %% Backend Service
        subgraph "Backend Service (Rust Rocket)"
            BE["Rust Rocket API"]:::backend
            BController["Controller Layer"]:::backend
            HM["HTTP Models (serde types)"]:::backend
            BU["Use-case Services"]:::backend
            BD["Domain Entities"]:::backend
            BRepoPort["Repo Interfaces (Ports)"]:::backend
            BRepoAdap["Repo Adapters (Diesel)"]:::backend
            subgraph "Infrastructure"
                BInfraRouter["Router"]:::backend
                BInfraModels["Models"]:::backend
            end
            subgraph "Utils"
                BOAuth["OAuth Integration"]:::backend
                BJWT["JWT Handling"]:::backend
                BPass["Password Verification"]:::backend
                BRecap["reCAPTCHA Verification"]:::backend
            end
        end

        %% Database
        DB["PostgreSQL"]:::database

        %% Migrations and Dockerfile
        MIG["Diesel Migrations"]:::backend
        DOCKERNODE["Dockerfile & run.sh"]:::backend
    end

    %% External Services
    SMTP["SMTP Server"]:::external
    OAUTHEXT["OAuth Provider"]:::external
    RECAPEXT["reCAPTCHA Service"]:::external

    %% CI/CD
    CI[".github/workflows"]:::external

    %% Connections
    U -->|"HTTP UI"| FE
    A -->|"HTTP UI"| FE
    FE -->|"HTTPS/JSON"| BE

    BE --> BController
    BE --> BInfraRouter
    BE --> BInfraModels
    BE --> HM

    BController -->|"calls"| BU
    BU -->|"uses"| BD
    BD -->|"through interfaces"| BRepoPort
    BRepoPort -->|"implemented by"| BRepoAdap
    BRepoAdap -->|"SQL"| DB

    BInfraRouter -->|"migrations"| MIG
    BInfraModels -->|"schema"| DB

    BController -->|"SMTP"| SMTP
    BController -->|"OAuth handshake"| BOAuth
    BOAuth -->|"HTTPS"| OAUTHEXT

    BController -->|"JWT ops"| BJWT
    BController -->|"verify pwd"| BPass

    BController -->|"verify recaptcha"| BRecap
    BRecap -->|"HTTPS"| RECAPEXT

    CI --> FE
    CI --> BE

    DOCKERNODE --> BE
    DOCKERNODE --> DB

    %% Click Events
    click FE "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/frontend/"
    click FR "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/frontend/src/routes/"
    click FS "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/frontend/src/recoil/"
    click FA "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/frontend/src/components/AuthContext.tsx"
    click BE "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/src/main.rs"
    click BController "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/src/adapters/controller/"
    click HM "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/src/adapters/httpmodels.rs"
    click BRepoPort "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/src/adapters/repository.rs"
    click BRepoAdap "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/src/adapters/repository/"
    click BU "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/src/usecase/"
    click BD "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/src/domain/"
    click BInfraRouter "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/src/infrastructure/router.rs"
    click BInfraModels "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/src/infrastructure/models.rs"
    click MIG "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/migrations/"
    click BOAuth "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/src/utils/oauth_authentication.rs"
    click BJWT "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/src/utils/jwt.rs"
    click BPass "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/src/utils/verify_password.rs"
    click BRecap "https://github.com/lit-innosence/tus_yuurikai_system/blob/development/src/utils/verify_recaptcha.rs"
    click DOCKERNODE "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/Dockerfile"
    click CI "https://github.com/lit-innosence/tus_yuurikai_system/tree/development/.github/workflows/"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#009EFF;
    classDef backend fill:#FFE0B2,stroke:#FF9800;
    classDef database fill:#C8E6C9,stroke:#4CAF50;
    classDef external fill:#ECEFF1,stroke:#90A4AE;
```
