# kodaimura/scaf-fast architecture

> Architecture diagram of the GitHub repository kodaimura/scaf-fast, 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/kodaimura/scaf-fast
- Repository: https://github.com/kodaimura/scaf-fast

## Overview

##### Project Type and Purpose
- It implements clean-architecture principles: HTTP handlers → use cases → modules/repositories → database/Redis.
- Core services include account management (signup, login, logout, token refresh) and token blacklist support.

##### File-Structure Analysis
- Top-level: Dockerfile, docker-compose for local/prod, Makefile, alembic.ini, requirements.txt
- app/main.py and app/router.py boot up the FastAPI application and route definitions.
- app/handler: HTTP layer (DTOs, handlers).
- app/usecase: business logic (account operations).
- app/module: data models (_model.py), repository implementations (_repository.py), and module wiring (module.py).
- app/core: cross-cutting concerns (config, DB, Redis, JWT, crypto, logging, common response structures, base repository).
- alembic scripts under app/alembic for database migrations.

a. API Layer
- FastAPI Application (app/main.py)
- Router (app/router.py)
- HTTP Handlers (app/handler/*)
b. Business-Logic Layer
- Use Cases (app/usecase/account/*)
c. Data-Access Layer
- Module Definitions & Repositories (app/module/account, app/module/blacklist)
- Core Repository Base (app/core/repository.py)
d. Infrastructure
- Relational Database (PostgreSQL inferred)
- Redis (for token blacklist/cache)
- Alembic Migration Service
- Docker & Docker-Compose for containerization
e. Cross-Cutting Services
- Configuration (app/core/config.py)
- JWT Service (app/core/jwt.py)
- Crypto Utilities (app/core/crypto.py)
- Logging (app/core/logger.py)

##### Relationships and Data Flow
- Client → HTTP Router → Handler DTO → Handler logic calls → Use Case
- Use Case invokes → Module Repository → Database (CRUD) or → Redis (cache/blacklist)
- Database migration flow: Developer runs Alembic scripts → Database schema evolves
- Docker-Compose orchestrates containers: app, database, redis

##### Architectural Patterns
- Clean (Onion) Architecture: clear separation between HTTP, business logic, and data access.
- Repository Pattern abstracts persistence.
- Dependency Injection of modules and core services (config, DB, JWT, Redis).
- Containerized deployment via Docker images and Compose files.

##### Final Recommendations
- Be exhaustive in listing all account and blacklist endpoints.
- Token flow: issuance (JWT) and revocation (blacklist in Redis).
- Docker-Compose relationships: network links between app, db, redis.
- Migration pipeline: source code → alembic → schema.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers top-down
    subgraph "API Layer"
        direction TB
        Client["Client"]:::external
        FastAPI["FastAPI App\n(app/main.py)"]:::api
        Router["Router\n(app/router.py)"]:::api

        subgraph "Account Handlers"
            direction TB
            AccountHandler["AccountHandler\n(app/handler/account/handler.py)"]:::api
            AccountDTO["AccountDTO\n(app/handler/account/dto.py)"]:::api
        end
    end

    subgraph "Use-Case Layer"
        direction TB
        Signup["SignupUseCase\n(app/usecase/account/signup.py)"]:::usecase
        Login["LoginUseCase\n(app/usecase/account/login.py)"]:::usecase
        Logout["LogoutUseCase\n(app/usecase/account/logout.py)"]:::usecase
        Refresh["RefreshUseCase\n(app/usecase/account/refresh.py)"]:::usecase
        GetMe["GetMeUseCase\n(app/usecase/account/get_me.py)"]:::usecase
    end

    subgraph "Module/Repository Layer"
        direction TB
        AccountModel["AccountModel\n(app/module/account/_model.py)"]:::data
        AccountRepo["AccountRepository\n(app/module/account/_repository.py)"]:::data
        AccountModule["AccountModule\n(app/module/account/module.py)"]:::data

        BlacklistDTO["BlacklistDTO\n(app/module/blacklist/_dto.py)"]:::data
        BlacklistModule["BlacklistModule\n(app/module/blacklist/module.py)"]:::data

        BaseRepo["BaseRepository\n(app/core/repository.py)"]:::crosscut
    end

    subgraph "Infrastructure Layer"
        direction TB
        subgraph "Docker Compose"
            direction TB
            AppContainer["App Container"]:::infra
            DBContainer["Relational DB\n(PostgreSQL)"]:::infra
            RedisContainer["Redis Cache\n(Blacklist Store)"]:::infra
        end
        Alembic["Alebic Migration\n(alembic.ini,\napp/alembic)"]:::infra
    end

    subgraph "Cross-Cutting Services"
        direction TB
        Config["Config Service\n(app/core/config.py)"]:::crosscut
        JWT["JWT Service\n(app/core/jwt.py)"]:::crosscut
        Crypto["Crypto Utilities\n(app/core/crypto.py)"]:::crosscut
        Logger["Logging Service\n(app/core/logger.py)"]:::crosscut
        Response["Common Responses\n(app/core/response.py)"]:::crosscut
        DBConnector["DB Connector\n(app/core/database.py)"]:::crosscut
        RedisConnector["Redis Connector\n(app/core/redis.py)"]:::crosscut
    end

    %% Connections
    Client -->|calls HTTP| FastAPI
    FastAPI -->|routes| Router
    Router -->|calls| AccountHandler
    AccountHandler -->|uses DTO| AccountDTO
    AccountHandler -->|invokes| Signup
    AccountHandler -->|invokes| Login
    AccountHandler -->|invokes| Logout
    AccountHandler -->|invokes| Refresh
    AccountHandler -->|invokes| GetMe

    Signup -->|uses| AccountModule
    Login -->|uses| AccountModule
    Logout -->|uses| BlacklistModule
    Refresh -->|uses| BlacklistModule
    GetMe -->|uses| AccountModule

    AccountModule -->|models| AccountModel
    AccountModule -->|repository| AccountRepo
    BlacklistModule -->|dto| BlacklistDTO
    AccountRepo -->|extends| BaseRepo
    BlacklistModule -->|extends| BaseRepo

    AccountRepo -->|CRUD| DBContainer
    AccountModel -->|schema| DBContainer
    BlacklistModule -->|cache| RedisContainer

    AppContainer -->|connects| DBContainer
    AppContainer -->|connects| RedisContainer
    Alembic -->|migrates| DBContainer

    %% Dependency injection
    FastAPI -->|loads| Config
    FastAPI -->|loads| Logger
    FastAPI -->|loads| DBConnector
    FastAPI -->|loads| RedisConnector
    FastAPI -->|loads| JWT
    FastAPI -->|loads| Crypto
    FastAPI -->|uses| Response

    %% Click events
    click FastAPI "https://github.com/kodaimura/scaf-fast/blob/main/app/main.py"
    click Router "https://github.com/kodaimura/scaf-fast/blob/main/app/router.py"
    click AccountHandler "https://github.com/kodaimura/scaf-fast/blob/main/app/handler/account/handler.py"
    click AccountDTO "https://github.com/kodaimura/scaf-fast/blob/main/app/handler/account/dto.py"
    click Signup "https://github.com/kodaimura/scaf-fast/blob/main/app/usecase/account/signup.py"
    click Login "https://github.com/kodaimura/scaf-fast/blob/main/app/usecase/account/login.py"
    click Logout "https://github.com/kodaimura/scaf-fast/blob/main/app/usecase/account/logout.py"
    click Refresh "https://github.com/kodaimura/scaf-fast/blob/main/app/usecase/account/refresh.py"
    click GetMe "https://github.com/kodaimura/scaf-fast/blob/main/app/usecase/account/get_me.py"
    click AccountModel "https://github.com/kodaimura/scaf-fast/blob/main/app/module/account/_model.py"
    click AccountRepo "https://github.com/kodaimura/scaf-fast/blob/main/app/module/account/_repository.py"
    click AccountModule "https://github.com/kodaimura/scaf-fast/blob/main/app/module/account/module.py"
    click BlacklistDTO "https://github.com/kodaimura/scaf-fast/blob/main/app/module/blacklist/_dto.py"
    click BlacklistModule "https://github.com/kodaimura/scaf-fast/blob/main/app/module/blacklist/module.py"
    click BaseRepo "https://github.com/kodaimura/scaf-fast/blob/main/app/core/repository.py"
    click DBConnector "https://github.com/kodaimura/scaf-fast/blob/main/app/core/database.py"
    click RedisConnector "https://github.com/kodaimura/scaf-fast/blob/main/app/core/redis.py"
    click Config "https://github.com/kodaimura/scaf-fast/blob/main/app/core/config.py"
    click JWT "https://github.com/kodaimura/scaf-fast/blob/main/app/core/jwt.py"
    click Crypto "https://github.com/kodaimura/scaf-fast/blob/main/app/core/crypto.py"
    click Logger "https://github.com/kodaimura/scaf-fast/blob/main/app/core/logger.py"
    click Response "https://github.com/kodaimura/scaf-fast/blob/main/app/core/response.py"

    %% Styles
    classDef api fill:#cce5ff,stroke:#000
    classDef usecase fill:#d4edda,stroke:#000
    classDef data fill:#fff3cd,stroke:#000
    classDef infra fill:#e2e3e5,stroke:#000
    classDef crosscut fill:#f5c6cb,stroke:#000
    classDef external fill:#f8f9fa,stroke:#000,stroke-dasharray: 2 2
```
