pirats/SOURCEMAP.md

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: Configures the SQLite database engine, sets up the session dependency get_session, and executes migrations for adding new table columns dynamically.
• 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: Holds metadata for all 54 deck cards (suits, values, Joker representations), parses individual card codes, and loads static descriptions for Obstacles.
• templates.py: Shared Jinja2 template initialization and path configurations to avoid circular module imports.

Modular Business Logic (CRUD)

• crud.py: A facade module that imports all sub-CRUD helper functions, preserving existing API endpoints for routes and tests.
• 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: Handles delegating and answering character questions, submitting techniques, and distributing technique swaps.
• crud_scene.py: Scene starts checks, playing normal/Joker cards onto obstacles, and checking objective checkbox completion.
• crud_upkeep.py: Handles rank votes submissions/resolution, upkeep state transitions, and Deep upkeep hand discards/refreshes.

Modular Router Endpoints (Routes)

• 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: Houses /game/{game_id}/player/{player_id}/view which determines the template responses to return for each phase layout.
• routes_lobby.py: Endpoints for lobby listings and starting game creation.
• routes_character.py: Endpoints for character sheets details saving, question delegations, revocations, and technique configurations.
• routes_scene.py: Endpoints for role assignments, scene starts, card playing, objective changes, and scene endings.
• routes_upkeep.py: Endpoints for between-scene rank votes, player readiness triggers, and deep card confirmations.
• routes_admin.py: Endpoints for host administrator console panels.

---

2. Frontend Stylesheets (src/pirats/static/css/)

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