# jzhen03/pokerpete architecture

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

- Interactive diagram: https://gitdiagram.com/jzhen03/pokerpete
- Repository: https://github.com/jzhen03/pokerpete

## Overview

PokerPete is a local-first heads-up poker study app. Players explore and save ranges, predict opponent ranges, calculate equity, request preflop solutions, and practice with trainer spots. The frontend selects study panels and calls a FastAPI backend; backend routes dispatch to poker engines and, where needed, SQLite-backed persistence or cached solutions. The README also names postflop analysis and hand-history review, but the supplied tree has no identifiable implementation modules for those capabilities, so they are not represented as implemented subsystems. Backend internals are partly unsampled; uncertain links are omitted.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/api/client.ts) (API client), [`backend/src/pokerpete/engine/ranges.py`](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/ranges.py) (Range operations), [`frontend/src/App.tsx`](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/App.tsx) (Study tabs), [`backend/src/pokerpete/main.py`](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Study interface"]
  node_app["Study tabs<br/>[App.tsx]"]
  node_range_ui["Range explorer<br/>[RangeExplorer.tsx]"]
  node_grid["Range grid<br/>[RangeGrid.tsx]"]
  node_predictor_ui["Range predictor<br/>[RangePredictor.tsx]"]
  node_equity_ui["Equity panel<br/>[EquityPanel.tsx]"]
  node_trainer_ui["Trainer panel<br/>[Trainer.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_api_schema["API types<br/>[schema.ts]"]
end

subgraph group_api["HTTP API"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_ranges_route["Ranges routes<br/>[routes_ranges.py]"]
  node_predict_route["Predict route"]
  node_equity_route["Equity route<br/>[routes_equity.py]"]
  node_solver_route["Solver routes<br/>[routes_solver.py]"]
  node_trainer_route["Trainer routes<br/>[routes_trainer.py]"]
end

subgraph group_engine["Poker engine"]
  node_cards["Card model<br/>[cards.py]"]
  node_range_engine["Range operations<br/>[ranges.py]"]
  node_equity_engine["Equity calculation<br/>[equity.py]"]
  node_matrix["Preflop equity matrix"]
  node_pushfold["Push-fold solver<br/>[preflop_solver.py]"]
  node_tree_solver["Preflop tree solver"]
  node_predictor_engine["Range prediction<br/>[range_predictor.py]"]
  node_trainer_engine["Trainer logic<br/>[trainer.py]"]
end

subgraph group_persistence["Local persistence"]
  node_db_session["DB sessions<br/>[session.py]"]
  node_saved_ranges["Saved ranges<br/>[saved_ranges.py]"]
  node_solver_cache["Solver cache<br/>[solver_cache.py]"]
  node_db_models[("SQLite models<br/>[models.py]")]
end

node_player(("Player"))

node_player -->|"uses"| node_app
node_app -->|"renders"| node_range_ui
node_app -->|"renders"| node_predictor_ui
node_app -->|"renders"| node_equity_ui
node_app -->|"renders"| node_trainer_ui
node_range_ui -->|"renders"| node_grid
node_predictor_ui -->|"renders"| node_grid
node_app -->|"checks health"| node_api_client
node_predictor_ui -->|"requests ranges"| node_api_client
node_range_ui -.->|"requests ranges"| node_api_client
node_equity_ui -.->|"requests equity"| node_api_client
node_trainer_ui -.->|"requests training"| node_api_client
node_api_client -->|"types calls"| node_api_schema
node_api_client -.->|"HTTP requests"| node_fastapi
node_fastapi -->|"mounts"| node_ranges_route
node_fastapi -->|"mounts"| node_predict_route
node_fastapi -->|"mounts"| node_equity_route
node_fastapi -->|"mounts"| node_solver_route
node_fastapi -->|"mounts"| node_trainer_route
node_ranges_route -->|"parses ranges"| node_range_engine
node_ranges_route -->|"reads and writes"| node_saved_ranges
node_ranges_route -->|"gets sessions"| node_db_session
node_predict_route -->|"predicts"| node_predictor_engine
node_equity_route -->|"parses ranges"| node_range_engine
node_equity_route -->|"parses board"| node_cards
node_equity_route -->|"calculates equity"| node_equity_engine
node_solver_route -->|"solves push-fold"| node_pushfold
node_solver_route -->|"gets tree solution"| node_solver_cache
node_solver_route -->|"gets sessions"| node_db_session
node_trainer_route -->|"grades and samples"| node_trainer_engine
node_trainer_route -->|"gets tree solution"| node_solver_cache
node_trainer_route -->|"gets sessions"| node_db_session
node_trainer_route -->|"gets hand classes"| node_matrix
node_range_engine -->|"uses card types"| node_cards
node_equity_engine -->|"uses ranges"| node_range_engine
node_equity_engine -->|"uses cards"| node_cards
node_matrix -->|"calculates matchups"| node_equity_engine
node_matrix -->|"parses classes"| node_range_engine
node_pushfold -->|"uses matrix"| node_matrix
node_tree_solver -->|"uses matrix"| node_matrix
node_predictor_engine -->|"builds ranges"| node_range_engine
node_predictor_engine -->|"uses cards"| node_cards
node_trainer_engine -->|"uses ranges"| node_range_engine
node_trainer_engine -->|"uses matrix"| node_matrix
node_trainer_engine -->|"uses solver"| node_pushfold
node_db_session -.->|"creates sessions"| node_db_models
node_saved_ranges -->|"stores range rows"| node_db_models
node_solver_cache -->|"stores solutions"| node_db_models

click node_app "https://github.com/jzhen03/pokerpete/blob/main/frontend/src/App.tsx"
click node_range_ui "https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/RangeExplorer/RangeExplorer.tsx"
click node_grid "https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/RangeGrid/RangeGrid.tsx"
click node_predictor_ui "https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/RangePredictor/RangePredictor.tsx"
click node_equity_ui "https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/EquityPanel/EquityPanel.tsx"
click node_trainer_ui "https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/Trainer/Trainer.tsx"
click node_api_client "https://github.com/jzhen03/pokerpete/blob/main/frontend/src/api/client.ts"
click node_api_schema "https://github.com/jzhen03/pokerpete/blob/main/frontend/src/api/schema.ts"
click node_fastapi "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/main.py"
click node_ranges_route "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_ranges.py"
click node_predict_route "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_range_predictor.py"
click node_equity_route "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_equity.py"
click node_solver_route "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_solver.py"
click node_trainer_route "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_trainer.py"
click node_cards "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/cards.py"
click node_range_engine "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/ranges.py"
click node_equity_engine "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/equity.py"
click node_matrix "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/preflop_equity_matrix.py"
click node_pushfold "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/preflop_solver.py"
click node_tree_solver "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/preflop_tree_solver.py"
click node_predictor_engine "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/range_predictor.py"
click node_trainer_engine "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/trainer.py"
click node_db_session "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/db/session.py"
click node_saved_ranges "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/db/saved_ranges.py"
click node_solver_cache "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/db/solver_cache.py"
click node_db_models "https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/db/models.py"

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_app,node_range_ui,node_grid,node_predictor_ui,node_equity_ui,node_trainer_ui,node_api_client,node_api_schema toneBlue
class node_fastapi,node_ranges_route,node_predict_route,node_equity_route,node_solver_route,node_trainer_route toneAmber
class node_cards,node_range_engine,node_equity_engine,node_matrix,node_pushfold,node_tree_solver,node_predictor_engine,node_trainer_engine toneMint
class node_db_session,node_saved_ranges,node_solver_cache,node_db_models toneRose
class node_player toneIndigo
```

## Components

### Study interface

- [Study tabs](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Range explorer](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/RangeExplorer/RangeExplorer.tsx): `frontend/src/components/RangeExplorer/RangeExplorer.tsx`
- [Range grid](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/RangeGrid/RangeGrid.tsx): `frontend/src/components/RangeGrid/RangeGrid.tsx`
- [Range predictor](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/RangePredictor/RangePredictor.tsx): `frontend/src/components/RangePredictor/RangePredictor.tsx`
- [Equity panel](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/EquityPanel/EquityPanel.tsx): `frontend/src/components/EquityPanel/EquityPanel.tsx`
- [Trainer panel](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/components/Trainer/Trainer.tsx): `frontend/src/components/Trainer/Trainer.tsx`
- [API client](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [API types](https://github.com/jzhen03/pokerpete/blob/main/frontend/src/api/schema.ts): `frontend/src/api/schema.ts`

### HTTP API

- [FastAPI app](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/main.py): `backend/src/pokerpete/main.py`
- [Ranges routes](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_ranges.py): `backend/src/pokerpete/api/routes_ranges.py`
- [Predict route](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_range_predictor.py): `backend/src/pokerpete/api/routes_range_predictor.py`
- [Equity route](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_equity.py): `backend/src/pokerpete/api/routes_equity.py`
- [Solver routes](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_solver.py): `backend/src/pokerpete/api/routes_solver.py`
- [Trainer routes](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/api/routes_trainer.py): `backend/src/pokerpete/api/routes_trainer.py`

### Poker engine

- [Card model](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/cards.py): `backend/src/pokerpete/engine/cards.py`
- [Range operations](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/ranges.py): `backend/src/pokerpete/engine/ranges.py`
- [Equity calculation](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/equity.py): `backend/src/pokerpete/engine/equity.py`
- [Preflop equity matrix](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/preflop_equity_matrix.py): `backend/src/pokerpete/engine/preflop_equity_matrix.py`
- [Push-fold solver](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/preflop_solver.py): `backend/src/pokerpete/engine/preflop_solver.py`
- [Preflop tree solver](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/preflop_tree_solver.py): `backend/src/pokerpete/engine/preflop_tree_solver.py`
- [Range prediction](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/range_predictor.py): `backend/src/pokerpete/engine/range_predictor.py`
- [Trainer logic](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/engine/trainer.py): `backend/src/pokerpete/engine/trainer.py`

### Local persistence

- [DB sessions](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/db/session.py): `backend/src/pokerpete/db/session.py`
- [Saved ranges](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/db/saved_ranges.py): `backend/src/pokerpete/db/saved_ranges.py`
- [Solver cache](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/db/solver_cache.py): `backend/src/pokerpete/db/solver_cache.py`
- [SQLite models](https://github.com/jzhen03/pokerpete/blob/main/backend/src/pokerpete/db/models.py): `backend/src/pokerpete/db/models.py`

### Other components

- **Player**

## Connections

- Player → Study tabs: uses (evidence: `frontend/src/App.tsx`)
- Study tabs → Range explorer: renders (evidence: `frontend/src/App.tsx`)
- Study tabs → Range predictor: renders (evidence: `frontend/src/App.tsx`)
- Study tabs → Equity panel: renders (evidence: `frontend/src/App.tsx`)
- Study tabs → Trainer panel: renders (evidence: `frontend/src/App.tsx`)
- Range explorer → Range grid: renders (evidence: `frontend/src/components/RangeExplorer/RangeExplorer.tsx`)
- Range predictor → Range grid: renders (evidence: `frontend/src/components/RangePredictor/RangePredictor.tsx`)
- Study tabs → API client: checks health (evidence: `frontend/src/App.tsx`)
- Range predictor → API client: requests ranges (evidence: `frontend/src/components/RangePredictor/RangePredictor.tsx`)
- Range explorer → API client: requests ranges (evidence: `frontend/src/components/RangeExplorer/RangeExplorer.tsx`)
- Equity panel → API client: requests equity (evidence: `frontend/src/components/EquityPanel/EquityPanel.tsx`)
- Trainer panel → API client: requests training (evidence: `frontend/src/components/Trainer/Trainer.tsx`)
- API client → API types: types calls (evidence: `frontend/src/api/client.ts`)
- API client → FastAPI app: HTTP requests
- FastAPI app → Ranges routes: mounts (evidence: `backend/src/pokerpete/main.py`)
- FastAPI app → Predict route: mounts (evidence: `backend/src/pokerpete/main.py`)
- FastAPI app → Equity route: mounts (evidence: `backend/src/pokerpete/main.py`)
- FastAPI app → Solver routes: mounts (evidence: `backend/src/pokerpete/main.py`)
- FastAPI app → Trainer routes: mounts (evidence: `backend/src/pokerpete/main.py`)
- Ranges routes → Range operations: parses ranges (evidence: `backend/src/pokerpete/api/routes_ranges.py`)
- Ranges routes → Saved ranges: reads and writes (evidence: `backend/src/pokerpete/api/routes_ranges.py`)
- Ranges routes → DB sessions: gets sessions (evidence: `backend/src/pokerpete/api/routes_ranges.py`)
- Predict route → Range prediction: predicts (evidence: `backend/src/pokerpete/api/routes_range_predictor.py`)
- Equity route → Range operations: parses ranges (evidence: `backend/src/pokerpete/api/routes_equity.py`)
- Equity route → Card model: parses board (evidence: `backend/src/pokerpete/api/routes_equity.py`)
- Equity route → Equity calculation: calculates equity (evidence: `backend/src/pokerpete/api/routes_equity.py`)
- Solver routes → Push-fold solver: solves push-fold (evidence: `backend/src/pokerpete/api/routes_solver.py`)
- Solver routes → Solver cache: gets tree solution (evidence: `backend/src/pokerpete/api/routes_solver.py`)
- Solver routes → DB sessions: gets sessions (evidence: `backend/src/pokerpete/api/routes_solver.py`)
- Trainer routes → Trainer logic: grades and samples (evidence: `backend/src/pokerpete/api/routes_trainer.py`)
- Trainer routes → Solver cache: gets tree solution (evidence: `backend/src/pokerpete/api/routes_trainer.py`)
- Trainer routes → DB sessions: gets sessions (evidence: `backend/src/pokerpete/api/routes_trainer.py`)
- Trainer routes → Preflop equity matrix: gets hand classes (evidence: `backend/src/pokerpete/api/routes_trainer.py`)
- Range operations → Card model: uses card types (evidence: `backend/src/pokerpete/engine/ranges.py`)
- Equity calculation → Range operations: uses ranges (evidence: `backend/src/pokerpete/engine/equity.py`)
- Equity calculation → Card model: uses cards (evidence: `backend/src/pokerpete/engine/equity.py`)
- Preflop equity matrix → Equity calculation: calculates matchups (evidence: `backend/src/pokerpete/engine/preflop_equity_matrix.py`)
- Preflop equity matrix → Range operations: parses classes (evidence: `backend/src/pokerpete/engine/preflop_equity_matrix.py`)
- Push-fold solver → Preflop equity matrix: uses matrix (evidence: `backend/src/pokerpete/engine/preflop_solver.py`)
- Preflop tree solver → Preflop equity matrix: uses matrix (evidence: `backend/src/pokerpete/engine/preflop_tree_solver.py`)
- Range prediction → Range operations: builds ranges (evidence: `backend/src/pokerpete/engine/range_predictor.py`)
- Range prediction → Card model: uses cards (evidence: `backend/src/pokerpete/engine/range_predictor.py`)
- Trainer logic → Range operations: uses ranges (evidence: `backend/src/pokerpete/engine/trainer.py`)
- Trainer logic → Preflop equity matrix: uses matrix (evidence: `backend/src/pokerpete/engine/trainer.py`)
- Trainer logic → Push-fold solver: uses solver (evidence: `backend/src/pokerpete/engine/trainer.py`)
- DB sessions → SQLite models: creates sessions
- Saved ranges → SQLite models: stores range rows (evidence: `backend/src/pokerpete/db/saved_ranges.py`)
- Solver cache → SQLite models: stores solutions (evidence: `backend/src/pokerpete/db/solver_cache.py`)