# pitchayuttp/ai-snooker architecture

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

- Interactive diagram: https://gitdiagram.com/pitchayuttp/ai-snooker
- Repository: https://github.com/pitchayuttp/ai-snooker

## Overview

This is a modular snooker-training product: learners choose an exercise, check camera readiness, train against computer-vision analysis, receive feedback, and review saved results. The graph combines that documented workflow with the sampled frontend and backend composition, training, and reporting code. Several domain modules are indexed but unsampled, so their relationships are shown only where the README or source references support them.

Main entry points: [`backend/app/main.py`](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/main.py) (API composition), [`backend/app/runtime.py`](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/runtime.py) (Live runtime), [`frontend/ai-snooker/src/Workspace.jsx`](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/Workspace.jsx) (Training workspace), [`backend/app/api/training.py`](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/api/training.py) (Training API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learner["Learner interface"]
  node_app["App and auth<br/>[App.jsx]"]
  node_workspace["Training workspace<br/>[Workspace.jsx]"]
  node_training_ui["Training display<br/>[TrainingPage.jsx]"]
  node_ui_components["UI components<br/>[ui.jsx]"]
end

subgraph group_setup["Exercise setup"]
  node_setup_page["Exercise setup<br/>[SetupPage.jsx]"]
  node_camera_setup["Camera configuration<br/>[CameraSetup.jsx]"]
  node_settings["Module settings<br/>[moduleSettings.js]"]
end

subgraph group_analysis["Training analysis"]
  node_runtime["Live runtime<br/>[runtime.py]"]
  node_vision["Vision processing<br/>[vision.py]"]
  node_m1["M1 assessment<br/>[m1_assessment.py]"]
  node_m2["M2 follow-through"]
  node_m3["M3 monitoring<br/>[m3_monitor.py]"]
  node_protocol["Assessment protocol<br/>[protocol.py]"]
  node_criteria["Criteria templates"]
  node_colour["Ball colour detection<br/>[colour.py]"]
end

subgraph group_backend["Backend services"]
  node_api_client["API client<br/>[api.js]"]
  node_api_root["API composition<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_catalog_api["Exercise catalog<br/>[catalog.py]"]
  node_camera_api["Camera API<br/>[cameras.py]"]
  node_training_api["Training API<br/>[training.py]"]
end

subgraph group_records["Results and history"]
  node_database[("Training database<br/>[database.py]")]
  node_reports_api["Reports API<br/>[reports.py]"]
  node_reporting["Report assembly<br/>[reporting.py]"]
  node_report_queries["Progress queries<br/>[report_queries.py]"]
  node_history_ui["History and progress<br/>[HistoryPage.jsx]"]
  node_lessons["Lesson feedback<br/>[lessons.py]"]
  node_recordings["Evidence recordings<br/>[recordings.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"opens"| node_workspace
node_workspace -->|"presents setup"| node_setup_page
node_workspace -->|"presents training"| node_training_ui
node_workspace -->|"requests data"| node_api_client
node_setup_page -->|"renders"| node_camera_setup
node_setup_page -->|"configures"| node_settings
node_camera_setup -->|"sends settings"| node_api_client
node_api_client -->|"calls API"| node_api_root
node_api_root -->|"registers router"| node_auth
node_api_root -->|"registers router"| node_catalog_api
node_api_root -->|"registers router"| node_camera_api
node_api_root -->|"registers router"| node_training_api
node_api_root -->|"registers router"| node_reports_api
node_catalog_api -->|"reads catalog"| node_database
node_training_api -->|"controls session"| node_runtime
node_camera_api -->|"controls camera"| node_runtime
node_runtime -->|"processes frames"| node_vision
node_runtime -->|"uses assessment"| node_m1
node_runtime -->|"uses monitor"| node_m2
node_runtime -->|"uses monitor"| node_m3
node_training_api -->|"stores results"| node_database
node_training_api -->|"evaluates attempts"| node_protocol
node_reports_api -->|"assembles detail"| node_reporting
node_reporting -->|"reads measurements"| node_database
node_reporting -->|"gets feedback"| node_lessons
node_report_queries -->|"queries progress"| node_database
node_reports_api -->|"uses queries"| node_report_queries
node_history_ui -->|"loads history"| node_api_client
node_reports_api -->|"serves evidence"| node_recordings
node_protocol -->|"uses templates"| node_criteria
node_vision -.->|"detects balls"| node_colour
node_training_ui -.->|"renders controls"| node_ui_components

click node_app "https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/App.jsx"
click node_workspace "https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/Workspace.jsx"
click node_training_ui "https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/pages/TrainingPage.jsx"
click node_ui_components "https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/components/ui.jsx"
click node_setup_page "https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/pages/SetupPage.jsx"
click node_camera_setup "https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/components/CameraSetup.jsx"
click node_settings "https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/lib/moduleSettings.js"
click node_api_client "https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/lib/api.js"
click node_api_root "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/main.py"
click node_auth "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/auth.py"
click node_catalog_api "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/api/catalog.py"
click node_camera_api "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/api/cameras.py"
click node_training_api "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/api/training.py"
click node_runtime "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/runtime.py"
click node_vision "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/vision.py"
click node_m1 "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/m1_assessment.py"
click node_m2 "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/m2_follow_through.py"
click node_m3 "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/m3_monitor.py"
click node_protocol "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/protocol.py"
click node_database "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/database.py"
click node_reports_api "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/api/reports.py"
click node_reporting "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/services/reporting.py"
click node_report_queries "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/repositories/report_queries.py"
click node_history_ui "https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/pages/HistoryPage.jsx"
click node_lessons "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/lessons.py"
click node_criteria "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/criteria_templates.py"
click node_colour "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/colour.py"
click node_recordings "https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/recordings.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_workspace,node_training_ui,node_ui_components toneBlue
class node_setup_page,node_camera_setup,node_settings toneAmber
class node_runtime,node_vision,node_m1,node_m2,node_m3,node_protocol,node_criteria,node_colour toneMint
class node_api_client,node_api_root,node_auth,node_catalog_api,node_camera_api,node_training_api toneRose
class node_database,node_reports_api,node_reporting,node_report_queries,node_history_ui,node_lessons,node_recordings,node_learner toneIndigo
```

## Components

### Learner interface

- [App and auth](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/App.jsx): `frontend/ai-snooker/src/App.jsx`
- [Training workspace](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/Workspace.jsx): `frontend/ai-snooker/src/Workspace.jsx`
- [Training display](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/pages/TrainingPage.jsx): `frontend/ai-snooker/src/pages/TrainingPage.jsx`
- [UI components](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/components/ui.jsx): `frontend/ai-snooker/src/components/ui.jsx`

### Exercise setup

- [Exercise setup](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/pages/SetupPage.jsx): `frontend/ai-snooker/src/pages/SetupPage.jsx`
- [Camera configuration](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/components/CameraSetup.jsx): `frontend/ai-snooker/src/components/CameraSetup.jsx`
- [Module settings](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/lib/moduleSettings.js): `frontend/ai-snooker/src/lib/moduleSettings.js`

### Training analysis

- [Live runtime](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/runtime.py): `backend/app/runtime.py`
- [Vision processing](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/vision.py): `backend/app/vision.py`
- [M1 assessment](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/m1_assessment.py): `backend/app/m1_assessment.py`
- [M2 follow-through](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/m2_follow_through.py): `backend/app/m2_follow_through.py`
- [M3 monitoring](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/m3_monitor.py): `backend/app/m3_monitor.py`
- [Assessment protocol](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/protocol.py): `backend/app/protocol.py`
- [Criteria templates](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/criteria_templates.py): `backend/app/criteria_templates.py`
- [Ball colour detection](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/colour.py): `backend/app/colour.py`

### Backend services

- [API client](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/lib/api.js): `frontend/ai-snooker/src/lib/api.js`
- [API composition](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Exercise catalog](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/api/catalog.py): `backend/app/api/catalog.py`
- [Camera API](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/api/cameras.py): `backend/app/api/cameras.py`
- [Training API](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/api/training.py): `backend/app/api/training.py`

### Results and history

- [Training database](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/database.py): `backend/app/database.py`
- [Reports API](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/api/reports.py): `backend/app/api/reports.py`
- [Report assembly](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/services/reporting.py): `backend/app/services/reporting.py`
- [Progress queries](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/repositories/report_queries.py): `backend/app/repositories/report_queries.py`
- [History and progress](https://github.com/pitchayuttp/ai-snooker/blob/main/frontend/ai-snooker/src/pages/HistoryPage.jsx): `frontend/ai-snooker/src/pages/HistoryPage.jsx`
- [Lesson feedback](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/lessons.py): `backend/app/lessons.py`
- [Evidence recordings](https://github.com/pitchayuttp/ai-snooker/blob/main/backend/app/recordings.py): `backend/app/recordings.py`

### Other components

- **Learner**

## Connections

- Learner → App and auth: uses
- App and auth → Training workspace: opens (evidence: `frontend/ai-snooker/src/App.jsx`)
- Training workspace → Exercise setup: presents setup (evidence: `frontend/ai-snooker/src/Workspace.jsx`)
- Training workspace → Training display: presents training (evidence: `frontend/ai-snooker/src/Workspace.jsx`)
- Training workspace → API client: requests data (evidence: `frontend/ai-snooker/src/Workspace.jsx`)
- Exercise setup → Camera configuration: renders (evidence: `frontend/ai-snooker/src/pages/SetupPage.jsx`)
- Exercise setup → Module settings: configures (evidence: `frontend/ai-snooker/src/pages/SetupPage.jsx`)
- Camera configuration → API client: sends settings (evidence: `frontend/ai-snooker/src/components/CameraSetup.jsx`)
- API client → API composition: calls API
- API composition → Authentication: registers router (evidence: `backend/app/main.py`)
- API composition → Exercise catalog: registers router (evidence: `backend/app/main.py`)
- API composition → Camera API: registers router (evidence: `backend/app/main.py`)
- API composition → Training API: registers router (evidence: `backend/app/main.py`)
- API composition → Reports API: registers router (evidence: `backend/app/main.py`)
- Exercise catalog → Training database: reads catalog (evidence: `backend/app/api/catalog.py`)
- Training API → Live runtime: controls session (evidence: `backend/app/api/training.py`)
- Camera API → Live runtime: controls camera (evidence: `backend/app/api/cameras.py`)
- Live runtime → Vision processing: processes frames (evidence: `backend/app/runtime.py`)
- Live runtime → M1 assessment: uses assessment (evidence: `backend/app/runtime.py`)
- Live runtime → M2 follow-through: uses monitor (evidence: `backend/app/runtime.py`)
- Live runtime → M3 monitoring: uses monitor (evidence: `backend/app/runtime.py`)
- Training API → Training database: stores results (evidence: `backend/app/api/training.py`)
- Training API → Assessment protocol: evaluates attempts (evidence: `backend/app/api/training.py`)
- Reports API → Report assembly: assembles detail (evidence: `backend/app/api/reports.py`)
- Report assembly → Training database: reads measurements (evidence: `backend/app/services/reporting.py`)
- Report assembly → Lesson feedback: gets feedback (evidence: `backend/app/services/reporting.py`)
- Progress queries → Training database: queries progress (evidence: `backend/app/repositories/report_queries.py`)
- Reports API → Progress queries: uses queries (evidence: `backend/app/repositories/report_queries.py`)
- History and progress → API client: loads history
- Reports API → Evidence recordings: serves evidence (evidence: `backend/app/api/reports.py`)
- Assessment protocol → Criteria templates: uses templates (evidence: `backend/app/protocol.py`)
- Vision processing → Ball colour detection: detects balls
- Training display → UI components: renders controls