# Codebase Source Map

This document outlines the file layout and architecture of the **PiRats** (Rats with Gats Remote Play) application.

## Directory Tree

```
pirats/
├── pyproject.toml              # Python package configuration (PEP 621)
├── flake.nix                   # Nix configuration for development and deployment
├── RULEBOOK.md                 # Core Rats with Gats rules
├── OBSTACLES.md                # Obstacle cards list and definitions
├── EXAMPLESCENE.md             # Example gameplay scene walk-through
├── SOURCEMAP.md                # This file
├── src/
│   └── pirats/
│       ├── __init__.py
│       ├── cards.py            # Cards, deck shuffling, and score logic
│       ├── database.py         # DB connection setup and tables creation
│       ├── models.py           # SQLModel schemas (Game, Player, Obstacle, Vote)
│       ├── templates.py        # Shared Jinja2 templates setup
│       ├── phase_view.py       # Core templates phase-view routing engine
│       ├── crud.py             # Facade hub importing all sub-CRUD modules
│       ├── crud_base.py        # Base player, game, hand, deck database logic
│       ├── crud_character.py   # Character setup, question delegation, techniques swapping CRUD
│       ├── crud_scene.py       # Scene start, cards playing, Joker replacement CRUD
│       ├── crud_upkeep.py      # Upkeep transitions, rank-up voting, deep rest hand refresh CRUD
│       ├── main.py             # Main FastAPI initialization and core routes
│       ├── routes_lobby.py     # Lobby status and starting character creation routes
│       ├── routes_character.py # Character basic details saving, delegation, and technique submit routes
│       ├── routes_scene.py     # Role choosing, playing cards, Joker replace, objective toggles routes
│       ├── routes_upkeep.py    # Voting rank-up, readying, deep upkeep hand refresh routes
│       ├── routes_admin.py     # Creator admin dashboard panel routes
│       ├── static/
│       │   ├── js/
│       │   │   └── suggestions.js  # Suggestions dictionary for character creation
│       │   └── css/
│       │       ├── style.css       # Central stylesheet hub (imports other files)
│       │       ├── core.css        # Tokens, base resets, layout, utilities, global animations
│       │       ├── components.css  # Panels, cards, buttons, input fields
│       │       ├── card.css        # Mini, medium, large card styles, dragging styles
│       │       ├── welcome.css     # Home/welcome screen styles
│       │       ├── lobby.css       # Game lobby & waiting room player chip styles
│       │       ├── character.css   # Character sheet grid & tactile technique drag-and-drop slots
│       │       ├── scene-setup.css # Role selection screen button & badge styles
│       │       ├── scene-play.css  # Gameplay board, obstacles, challenges, deep controls
│       │       ├── upkeep.css      # Upkeep rest cards, voting roster, upkeep drag/drop
│       │       └── admin.css       # Admin dashboard list row layouts
│       └── templates/              # Jinja2 HTML templates
│           ├── admin.html          # Session creator admin control panel
│           ├── base.html           # Main base layout structure
│           ├── between_scenes_partial.html # Upkeep voting & rank ledgers view
│           ├── character_creation_partial.html # Character sheet & techniques builder view
│           ├── crew_status_snippet.html    # Lobby status polling snippet
│           ├── dashboard.html      # Dashboard hub containing HTMX phase swap targets
│           ├── deep_upkeep_partial.html # Deep rest upkeep card swap view
│           ├── delegation_snippet.html # Task list/inbox items for character creation
│           ├── header_status_snippet.html # Header pills showing role/phase
│           ├── inbox_snippet.html  # Inboxes for likes/hates task answers
│           ├── index.html          # Welcome home screen
│           ├── join_form.html      # Join game form
│           ├── lobby_partial.html  # Lobby view
│           ├── lobby_players_snippet.html  # Lobby active players list snippet
│           ├── scene_obstacles_snippet.html # Playboard obstacles snippet
│           ├── scene_partial.html  # Playboard gameplay view
│           ├── scene_roster_snippet.html # Scene roster snippet
│           ├── scene_setup_partial.html # Scene setup role chooser view
│           ├── techniques_snippet.html # Technique assignments display snippet
│           └── voting_roster_snippet.html # Voting roster display snippet
└── tests/
    └── test_game.py            # pytest backend logic and game loop tests
```

---

## Component Details

### 1. Backend Python Modules (`src/pirats/`)

#### Core Configuration & Setup
- **[database.py](file:///Users/ttm/Projects/pirats/src/pirats/database.py)**: Configures the SQLite database engine, sets up the session dependency `get_session`, and executes migrations for adding new table columns dynamically.
- **[models.py](file:///Users/ttm/Projects/pirats/src/pirats/models.py)**: Defines database models using SQLModel for `Game` (phase, current scene, extra obstacles), `Player` (rank, role, objectives, cards), `Obstacle` (active scene hazards, successes, played cards), and `Vote` (rank-up nominations).
- **[cards.py](file:///Users/ttm/Projects/pirats/src/pirats/cards.py)**: Holds metadata for all 54 deck cards (suits, values, Joker representations), parses individual card codes, and loads static descriptions for Obstacles.
- **[templates.py](file:///Users/ttm/Projects/pirats/src/pirats/templates.py)**: Shared Jinja2 template initialization and path configurations to avoid circular module imports.

#### Modular Business Logic (CRUD)
- **[crud.py](file:///Users/ttm/Projects/pirats/src/pirats/crud.py)**: A facade module that imports all sub-CRUD helper functions, preserving existing API endpoints for routes and tests.
- **[crud_base.py](file:///Users/ttm/Projects/pirats/src/pirats/crud_base.py)**: Base utility functions for accessing hands, drawing cards, reshuffling, checking captain privileges, and fetching core game and player entities.
- **[crud_character.py](file:///Users/ttm/Projects/pirats/src/pirats/crud_character.py)**: Handles delegating and answering character questions, submitting techniques, and distributing technique swaps.
- **[crud_scene.py](file:///Users/ttm/Projects/pirats/src/pirats/crud_scene.py)**: Scene starts checks, playing normal/Joker cards onto obstacles, and checking objective checkbox completion.
- **[crud_upkeep.py](file:///Users/ttm/Projects/pirats/src/pirats/crud_upkeep.py)**: Handles rank votes submissions/resolution, upkeep state transitions, and Deep upkeep hand discards/refreshes.

#### Modular Router Endpoints (Routes)
- **[main.py](file:///Users/ttm/Projects/pirats/src/pirats/main.py)**: Launches the FastAPI application, mounts static assets, serves home landing, game joins, dashboard layout renders, phase polling checks, and mounts all phase APIRouters.
- **[phase_view.py](file:///Users/ttm/Projects/pirats/src/pirats/phase_view.py)**: Houses `/game/{game_id}/player/{player_id}/view` which determines the template responses to return for each phase layout.
- **[routes_lobby.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_lobby.py)**: Endpoints for lobby listings and starting game creation.
- **[routes_character.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_character.py)**: Endpoints for character sheets details saving, question delegations, revocations, and technique configurations.
- **[routes_scene.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_scene.py)**: Endpoints for role assignments, scene starts, card playing, objective changes, and scene endings.
- **[routes_upkeep.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_upkeep.py)**: Endpoints for between-scene rank votes, player readiness triggers, and deep card confirmations.
- **[routes_admin.py](file:///Users/ttm/Projects/pirats/src/pirats/routes_admin.py)**: Endpoints for host administrator console panels.

---

### 2. Frontend Stylesheets (`src/pirats/static/css/`)
- **[style.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/style.css)**: Central hub referencing all other modular files using `@import`.
- **[core.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/core.css)**: Variable definitions, colors, font styling, animations, structural body, headers/footers, loading indicators, and alerts.
- **[components.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/components.css)**: Forms input designs, buttons variants, and glassmorphic panels.
- **[card.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/card.css)**: Custom-rendered CSS playing card widgets (mini list cards, hand cards, large face cards) and dragging animation states.
- **[welcome.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/welcome.css)** / **[lobby.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/lobby.css)**: Screen styles for the landing page and multiplayer join lobbies.
- **[character.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/character.css)** / **[scene-setup.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/scene-setup.css)**: Style configurations for the character sheet setup and scene role choose slots.
- **[scene-play.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/scene-play.css)** / **[upkeep.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/upkeep.css)**: Styles for active obstacles, card tables, and voting rank ledgers.
- **[admin.css](file:///Users/ttm/Projects/pirats/src/pirats/static/css/admin.css)**: Styles for session game hosts admin controls.