113 lines
10 KiB
Markdown
113 lines
10 KiB
Markdown
# 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.
|