# 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.).

### Current Migration Status

**Phase 1: Foundation Data Models** - ✅ **COMPLETE**
- ✅ `ManagerAi` - AI configuration (→ AIService with 9 methods)
- ✅ `Cardset` - Card set metadata (pure data, no extraction needed)

**Phase 2: Player and Card Data** - 🚧 **NEXT**
- 📋 `Team` - Team identity data (→ UIService for embed property)
- 📋 `Player` - Player metadata (→ UIService for Discord markdown)

**Testing Infrastructure** - ✅ **COMPLETE**
- ✅ Transaction rollback pattern for test isolation
- ✅ Factory pattern for unique test data generation
- ✅ Comprehensive test coverage (23 tests passing)

See `.claude/model-migration-plan.md` for detailed migration tracking.