How nlp-tf/server works
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).