Refactor for smaller context

2026-06-10 15:29:03 -07:00
parent 2d57973cd8
commit 2ddcb86cc0
26 changed files with 3373 additions and 3188 deletions
--- a/SOURCEMAP.md
+++ b/SOURCEMAP.md
@@ -0,0 +1,112 @@
+# 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.