# nlp-tf/server architecture

> Architecture diagram of the GitHub repository nlp-tf/server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nlp-tf/server
- Repository: https://github.com/nlp-tf/server

## Overview

##### Project Type and Purpose
- This is a backend API service built with FastAPI that powers an interactive MBTI-based “T vs. F” comfort-style game.
- It exposes RESTful JSON endpoints for game session management, round retrieval, user-response scoring, summary/ranking, and direct ML model predictions.

##### High-Level Architectural Components
- Clients (Web or Mobile): HTTP/JSON consumers (e.g., a React frontend or curl commands).
- API Layer (FastAPI + Uvicorn):
- Entry point: app/main.py (FastAPI instance)
- Routing: app/routers/game.py, predict.py, ranking.py
- Request/Response schemas: app/schemas.py
- Service Layer (Business Logic):
- GameService (app/services/game_service.py)
- RankingService (app/services/ranking_service.py)
- DB utilities (app/services/db_utils.py)
- Data Layer:
- PostgreSQL database (SQLAlchemy models in app/db/models.py)
- Alembic for migrations (alembic/ + app/db/alembic/)
- Static JSON scenario and ranking files (data/*.json)
- ML Model Component:
- KoBERT classification model loaded via Hugging Face transformers (app/models/load_model.py)
- Prediction logic (app/models/predict.py)
- Local model cache directory
- External Services:
- Hugging Face model hub (for initial model download, optional)

##### Component Interactions and Data Flow
- Client → FastAPI Router
- Client sends POST/GET requests to `/api/v1/game/...` or `/api/v1/predict`.
- FastAPI Router → Service Layer
- Router handlers call GameService / RankingService / Predict function.
- Service Layer → Database
- CRUD operations via SQLAlchemy session (app/db/database.py)
- Alembic ensures schema versioning/migrations.
- Service Layer → ML Model Component
- Predict endpoint invokes the loaded KoBERT model to compute T/F similarity scores.
- Service Layer → Static Data Files
- Round retrieval loads one of five random scenarios from data/scenarios.json.
- Service Layer → Response
- Compose JSON response with scores, feedback, session info, ranking data.

##### Architectural Patterns & Design Principles
- Layered Architecture: clear separation between routers (API layer), services (business logic), models (data/ML), and database.
- Dependency Injection: FastAPI’s dependency system for DB sessions, settings.
- Single Responsibility: each service class handles only one domain (game flow, ranking).
- Migrations-as-Code: Alembic directory maintains evolution of database schema.
- Modularity & Extensibility: ML model logic is encapsulated, so swapping to another transformer model involves minimal changes.

- SQLAlchemy session dependency flowing into services.
- Model loading step at startup and in-memory model usage for prediction calls.
- Five-round scenario-selection logic as “Scenario Data Store → GameService”.
- If desired, annotate critical environment variables (e.g., DATABASE_URL, MODEL_CACHE_PATH).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Web/Mobile Client"]:::external

    %% API Layer
    subgraph "API Layer"
        Main["FastAPI Entry\napp/main.py"]:::api
        GameRouter["Game Router\napp/routers/game.py"]:::api
        PredictRouter["Predict Router\napp/routers/predict.py"]:::api
        RankingRouter["Ranking Router\napp/routers/ranking.py"]:::api
        Schemas["Request/Response Schemas\napp/schemas.py"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        GameService["GameService\napp/services/game_service.py"]:::service
        RankingService["RankingService\napp/services/ranking_service.py"]:::service
        DBUtils["DB Utilities\napp/services/db_utils.py"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        DatabaseConfig["DB Config & Session\napp/db/database.py"]:::data
        Models["SQLAlchemy Models\napp/db/models.py"]:::data
        AlembicRoot["Alembic Migrations\nalembic/"]:::data
        AlembicApp["App Migrations\napp/db/alembic/versions/"]:::data
        Scenarios["Scenario Data\ndata/scenarios.json"]:::data
        RankingsStatic["Ranking Data\ndata/rankings.json"]:::data
        StatsStatic["Stats Data\ndata/stats.json"]:::data
    end

    %% ML Component
    subgraph "ML Component"
        ModelLoader["Model Loader\napp/models/load_model.py"]:::ml
        Predictor["Prediction Logic\napp/models/predict.py"]:::ml
        Cache["Local Model Cache"]:::ml
    end

    %% External Services
    HFHub["HuggingFace Hub"]:::external

    %% Connections
    Client -->|"HTTP/JSON"| Main
    Main -->|"includes routers"| GameRouter
    Main --> PredictRouter
    Main --> RankingRouter
    GameRouter -->|"uses schemas"| Schemas
    PredictRouter --> Schemas
    RankingRouter --> Schemas

    GameRouter -->|"calls"| GameService
    RankingRouter -->|"calls"| RankingService
    PredictRouter -->|"calls"| Predictor

    GameService --> DBUtils
    RankingService --> DBUtils
    DBUtils --> DatabaseConfig
    DatabaseConfig -->|"SQL queries"| Models
    AlembicRoot -.-> Models
    AlembicApp -.-> Models

    GameService -->|"loads"| Scenarios
    GameService -->|"reads"| RankingsStatic
    GameService -->|"reads"| StatsStatic

    Predictor --> ModelLoader
    Predictor --> Cache
    ModelLoader --> HFHub

    %% Click Events
    click Main "https://github.com/nlp-tf/server/blob/main/app/main.py"
    click GameRouter "https://github.com/nlp-tf/server/blob/main/app/routers/game.py"
    click PredictRouter "https://github.com/nlp-tf/server/blob/main/app/routers/predict.py"
    click RankingRouter "https://github.com/nlp-tf/server/blob/main/app/routers/ranking.py"
    click Schemas "https://github.com/nlp-tf/server/blob/main/app/schemas.py"
    click GameService "https://github.com/nlp-tf/server/blob/main/app/services/game_service.py"
    click RankingService "https://github.com/nlp-tf/server/blob/main/app/services/ranking_service.py"
    click DBUtils "https://github.com/nlp-tf/server/blob/main/app/services/db_utils.py"
    click DatabaseConfig "https://github.com/nlp-tf/server/blob/main/app/db/database.py"
    click Models "https://github.com/nlp-tf/server/blob/main/app/db/models.py"
    click AlembicRoot "https://github.com/nlp-tf/server/tree/main/alembic/"
    click AlembicApp "https://github.com/nlp-tf/server/tree/main/app/db/alembic/versions/"
    click Scenarios "https://github.com/nlp-tf/server/blob/main/data/scenarios.json"
    click RankingsStatic "https://github.com/nlp-tf/server/blob/main/data/rankings.json"
    click StatsStatic "https://github.com/nlp-tf/server/blob/main/data/stats.json"
    click ModelLoader "https://github.com/nlp-tf/server/blob/main/app/models/load_model.py"
    click Predictor "https://github.com/nlp-tf/server/blob/main/app/models/predict.py"

    %% Styles
    classDef api fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef service fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef data fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef ml fill:#e2ccf0,stroke:#6f42c1,color:#6f42c1,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px;
```
