# dzuy/picklerpg architecture

> Architecture diagram of the GitHub repository dzuy/picklerpg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dzuy/picklerpg
- Repository: https://github.com/dzuy/picklerpg

## Overview

Pickle RPG is a strategy-focused pickleball game with procedural 3D presentation, a shared rally/match model, player and court customization, and substantial multiplayer, analytics, and premium-access code. The principal play loop is to enter through the game UI, choose a shot at a decision point, advance the rally, and view the resulting play. The README describes some capabilities as future or deliberately limited; the tree and sampled server code also contain multiplayer implementation. Links between unsampled client modules are omitted where their callers are not evidenced.

Main entry points: [`server/multiplayer/service.ts`](https://github.com/dzuy/picklerpg/blob/main/server/multiplayer/service.ts) (Match service), [`src/engine/rally-engine.ts`](https://github.com/dzuy/picklerpg/blob/main/src/engine/rally-engine.ts) (Rally lifecycle), [`src/main.ts`](https://github.com/dzuy/picklerpg/blob/main/src/main.ts) (Game UI), [`src/match.ts`](https://github.com/dzuy/picklerpg/blob/main/src/match.ts) (Match state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gameplay["Gameplay"]
  node_game_ui["Game UI<br/>[main.ts]"]
  node_match["Match state<br/>[match.ts]"]
  node_scene["3D scene<br/>[scene.ts]"]
end

subgraph group_engine["Rally engine"]
  node_rally["Rally lifecycle<br/>[rally-engine.ts]"]
  node_shot_intent["Shot intent<br/>[shot-intent.ts]"]
  node_game_model["Game model<br/>[model.ts]"]
  node_scoring["Scoring rules<br/>[scoring.ts]"]
  node_checkpoint["Match checkpoints<br/>[checkpoint.ts]"]
end

subgraph group_customization["Players and courts"]
  node_player_design["Player design<br/>[player-design.ts]"]
  node_court_locations["Court locations<br/>[locations.ts]"]
  node_pack_catalog["Content packs<br/>[pack-catalog.ts]"]
end

subgraph group_multiplayer["Multiplayer"]
  node_remote_ui["Remote match UI<br/>[remote-main.ts]"]
  node_remote_api["Multiplayer API<br/>[api.ts]"]
  node_routes["API routes<br/>[routes.ts]"]
  node_match_service["Match service<br/>[service.ts]"]
  node_match_repository[("Match repository<br/>[repository.ts]")]
end

subgraph group_platform["Platform services"]
  node_analytics["Analytics<br/>[index.ts]"]
  node_browser_storage["Browser storage<br/>[browser-storage.ts]"]
  node_premium["Premium access<br/>[premium.ts]"]
end

node_player(("Player"))
node_supabase[("Supabase")]

node_player -->|"uses"| node_game_ui
node_game_ui -.->|"plays through"| node_match
node_rally -->|"parses"| node_shot_intent
node_rally -->|"uses contracts"| node_game_model
node_match_service -->|"creates and resolves"| node_match
node_match_service -->|"validates checkpoint"| node_checkpoint
node_routes -->|"dispatches"| node_match_service
node_match_repository -->|"calls RPCs"| node_supabase
node_analytics -->|"uses"| node_browser_storage
node_premium -->|"checks packs"| node_pack_catalog

click node_game_ui "https://github.com/dzuy/picklerpg/blob/main/src/main.ts"
click node_match "https://github.com/dzuy/picklerpg/blob/main/src/match.ts"
click node_scene "https://github.com/dzuy/picklerpg/blob/main/src/scene.ts"
click node_rally "https://github.com/dzuy/picklerpg/blob/main/src/engine/rally-engine.ts"
click node_shot_intent "https://github.com/dzuy/picklerpg/blob/main/src/engine/shot-intent.ts"
click node_game_model "https://github.com/dzuy/picklerpg/blob/main/src/engine/model.ts"
click node_scoring "https://github.com/dzuy/picklerpg/blob/main/src/engine/scoring.ts"
click node_checkpoint "https://github.com/dzuy/picklerpg/blob/main/src/engine/checkpoint.ts"
click node_player_design "https://github.com/dzuy/picklerpg/blob/main/src/player-design.ts"
click node_court_locations "https://github.com/dzuy/picklerpg/blob/main/src/locations.ts"
click node_pack_catalog "https://github.com/dzuy/picklerpg/blob/main/src/pack-catalog.ts"
click node_remote_ui "https://github.com/dzuy/picklerpg/blob/main/src/multiplayer/remote-main.ts"
click node_remote_api "https://github.com/dzuy/picklerpg/blob/main/src/multiplayer/api.ts"
click node_routes "https://github.com/dzuy/picklerpg/blob/main/server/multiplayer/routes.ts"
click node_match_service "https://github.com/dzuy/picklerpg/blob/main/server/multiplayer/service.ts"
click node_match_repository "https://github.com/dzuy/picklerpg/blob/main/server/multiplayer/repository.ts"
click node_analytics "https://github.com/dzuy/picklerpg/blob/main/src/analytics/index.ts"
click node_browser_storage "https://github.com/dzuy/picklerpg/blob/main/src/browser-storage.ts"
click node_premium "https://github.com/dzuy/picklerpg/blob/main/server/multiplayer/premium.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_game_ui,node_match,node_scene toneBlue
class node_rally,node_shot_intent,node_game_model,node_scoring,node_checkpoint,node_supabase toneAmber
class node_player_design,node_court_locations,node_pack_catalog toneMint
class node_remote_ui,node_remote_api,node_routes,node_match_service,node_match_repository toneRose
class node_analytics,node_browser_storage,node_premium,node_player toneIndigo
```

## Components

### Gameplay

- [Game UI](https://github.com/dzuy/picklerpg/blob/main/src/main.ts): `src/main.ts`
- [Match state](https://github.com/dzuy/picklerpg/blob/main/src/match.ts): `src/match.ts`
- [3D scene](https://github.com/dzuy/picklerpg/blob/main/src/scene.ts): `src/scene.ts`

### Rally engine

- [Rally lifecycle](https://github.com/dzuy/picklerpg/blob/main/src/engine/rally-engine.ts): `src/engine/rally-engine.ts`
- [Shot intent](https://github.com/dzuy/picklerpg/blob/main/src/engine/shot-intent.ts): `src/engine/shot-intent.ts`
- [Game model](https://github.com/dzuy/picklerpg/blob/main/src/engine/model.ts): `src/engine/model.ts`
- [Scoring rules](https://github.com/dzuy/picklerpg/blob/main/src/engine/scoring.ts): `src/engine/scoring.ts`
- [Match checkpoints](https://github.com/dzuy/picklerpg/blob/main/src/engine/checkpoint.ts): `src/engine/checkpoint.ts`

### Players and courts

- [Player design](https://github.com/dzuy/picklerpg/blob/main/src/player-design.ts): `src/player-design.ts`
- [Court locations](https://github.com/dzuy/picklerpg/blob/main/src/locations.ts): `src/locations.ts`
- [Content packs](https://github.com/dzuy/picklerpg/blob/main/src/pack-catalog.ts): `src/pack-catalog.ts`

### Multiplayer

- [Remote match UI](https://github.com/dzuy/picklerpg/blob/main/src/multiplayer/remote-main.ts): `src/multiplayer/remote-main.ts`
- [Multiplayer API](https://github.com/dzuy/picklerpg/blob/main/src/multiplayer/api.ts): `src/multiplayer/api.ts`
- [API routes](https://github.com/dzuy/picklerpg/blob/main/server/multiplayer/routes.ts): `server/multiplayer/routes.ts`
- [Match service](https://github.com/dzuy/picklerpg/blob/main/server/multiplayer/service.ts): `server/multiplayer/service.ts`
- [Match repository](https://github.com/dzuy/picklerpg/blob/main/server/multiplayer/repository.ts): `server/multiplayer/repository.ts`

### Platform services

- [Analytics](https://github.com/dzuy/picklerpg/blob/main/src/analytics/index.ts): `src/analytics/index.ts`
- [Browser storage](https://github.com/dzuy/picklerpg/blob/main/src/browser-storage.ts): `src/browser-storage.ts`
- [Premium access](https://github.com/dzuy/picklerpg/blob/main/server/multiplayer/premium.ts): `server/multiplayer/premium.ts`

### Other components

- **Player**
- **Supabase**

## Connections

- Player → Game UI: uses
- Game UI → Match state: plays through
- Rally lifecycle → Shot intent: parses (evidence: `src/engine/rally-engine.ts`)
- Rally lifecycle → Game model: uses contracts (evidence: `src/engine/rally-engine.ts`)
- Match service → Match state: creates and resolves (evidence: `server/multiplayer/service.ts`)
- Match service → Match checkpoints: validates checkpoint (evidence: `server/multiplayer/service.ts`)
- API routes → Match service: dispatches (evidence: `server/multiplayer/routes.ts`)
- Match repository → Supabase: calls RPCs (evidence: `server/multiplayer/repository.ts`)
- Analytics → Browser storage: uses (evidence: `src/analytics/index.ts`)
- Premium access → Content packs: checks packs (evidence: `server/multiplayer/premium.ts`)
