paper-dynasty-gameplay-webapp/app

App Directory

This directory contains the main application code for the Paper Dynasty web app, following the Model/Service Architecture pattern.

Architecture Overview

The app follows a clean separation of concerns:

• Models (models/) - Pure data models using SQLModel
• Services (services/) - Business logic layer with dependency injection
• Controllers (routers/) - Thin FastAPI route handlers
• Engine (engine/) - Stateless game simulation functions
• Configuration (config/) - Application settings and constants

Key Files

• main.py - FastAPI application setup and configuration
• Entry point for the web application

Directory Structure

app/
├── main.py                 # FastAPI application setup
├── config/                 # Configuration and constants
├── models/                 # SQLModel data models
├── services/               # Business logic layer (⭐ Core of architecture)
├── repositories/           # Optional data access layer
├── routers/                # FastAPI route handlers
├── engine/                 # Stateless game simulation
├── static/                 # Static web assets
└── templates/              # Jinja2 HTML templates

Service-First Development

When adding new features:

1. Start with services - implement business logic in the service layer
2. Test services independently - unit test with mocked dependencies
3. Create thin routes - delegate to services via dependency injection
4. Keep engine stateless - pure functions for game calculations

Migration Context

This application is migrated from a Discord bot (../discord-app/) with the goal of extracting Discord-specific business logic into clean, testable services that can support multiple interfaces (web, API, mobile, etc.).