# iambmd/ttskill architecture

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

- Interactive diagram: https://gitdiagram.com/iambmd/ttskill
- Repository: https://github.com/iambmd/ttskill

## Overview

TTSkill is a table-tennis video coaching product. Players submit a clip or YouTube link through one of four tracks: auto-cut rallies, get a technique breakdown, find comparable pros, or ask TT Coach to coordinate several tools. The frontend job APIs reach FastAPI, which validates input, creates background jobs, and runs the relevant pipeline; results and generated videos are shown on job pages. The graph preserves equipment recommendations and coaching-style analysis as separate capabilities. Some internal wiring is unsampled, so uncertain links are omitted; documented workflow links cite the README.

Main entry points: [`backend/app/pipelines.py`](https://github.com/iambmd/ttskill/blob/main/backend/app/pipelines.py) (Pipeline orchestration), [`backend/app/main.py`](https://github.com/iambmd/ttskill/blob/main/backend/app/main.py) (FastAPI routes), [`backend/technique/pipeline.py`](https://github.com/iambmd/ttskill/blob/main/backend/technique/pipeline.py) (Technique pipeline), [`backend/app/jobs.py`](https://github.com/iambmd/ttskill/blob/main/backend/app/jobs.py) (Job records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Player experience"]
  node_track_pages["Track pages<br/>[page.tsx]"]
  node_submit["Job API routes<br/>[route.ts]"]
  node_job_view["Job results<br/>[page.tsx]"]
end

subgraph group_service["Jobs and orchestration"]
  node_backend_api["FastAPI routes<br/>[main.py]"]
  node_validation["Input validation<br/>[validate.py]"]
  node_job_store[("Job records<br/>[jobs.py]")]
  node_pipelines["Pipeline orchestration<br/>[pipelines.py]"]
  node_download["Video download<br/>[download.py]"]
end

subgraph group_video["Video analysis"]
  node_autocut["Rally detection<br/>[rally.py]"]
  node_bounce_filter["Rally filtering<br/>[floor_bounce.py]"]
  node_clip_edit["Clip editing<br/>[cut.py]"]
  node_tech_pipeline["Technique pipeline<br/>[pipeline.py]"]
  node_pose["Pose analysis<br/>[pose.py]"]
  node_stroke["Stroke analysis<br/>[strokes.py]"]
  node_media["Media processing<br/>[media.py]"]
  node_renderer["Breakdown renderer<br/>[render.py]"]
end

subgraph group_coaching["Coaching and matching"]
  node_coach["TT Coach agent<br/>[coach.py]"]
  node_agent_tools["Coach tools<br/>[tools.py]"]
  node_matching["Pro matching<br/>[match.py]"]
  node_body_profile["Body profiles<br/>[body.py]"]
end

subgraph group_catalog["Equipment and style"]
  node_equipment["Rubber recommendations<br/>[recommend.py]"]
  node_style["Coaching style<br/>[style.py]"]
end

node_player(("Player"))

node_player -->|"chooses track"| node_track_pages
node_track_pages -->|"submits job"| node_submit
node_submit -->|"forwards request"| node_backend_api
node_backend_api -->|"validates input"| node_validation
node_backend_api -->|"creates job"| node_job_store
node_backend_api -->|"starts pipeline"| node_pipelines
node_pipelines -->|"updates status"| node_job_store
node_backend_api -->|"fetches video"| node_download
node_pipelines -->|"detects rallies"| node_autocut
node_pipelines -->|"filters rallies"| node_bounce_filter
node_pipelines -->|"cuts clips"| node_clip_edit
node_bounce_filter -->|"uses candidates"| node_autocut
node_pipelines -->|"runs breakdown"| node_tech_pipeline
node_tech_pipeline -->|"makes proxy"| node_media
node_tech_pipeline -->|"extracts pose"| node_pose
node_tech_pipeline -->|"plans stroke"| node_stroke
node_tech_pipeline -->|"renders video"| node_renderer
node_backend_api -->|"starts coach"| node_coach
node_coach -->|"dispatches tools"| node_agent_tools
node_agent_tools -->|"calls shared work"| node_pipelines
node_pipelines -->|"ranks pros"| node_matching
node_matching -->|"compares profiles"| node_body_profile
node_backend_api -->|"recommends rubbers"| node_equipment
node_renderer -->|"uses layout style"| node_style
node_job_store -->|"serves results"| node_job_view

click node_track_pages "https://github.com/iambmd/ttskill/blob/main/frontend/app/autocut/page.tsx"
click node_submit "https://github.com/iambmd/ttskill/blob/main/frontend/app/api/jobs/autocut/route.ts"
click node_job_view "https://github.com/iambmd/ttskill/blob/main/frontend/app/jobs/%5Bid%5D/page.tsx"
click node_backend_api "https://github.com/iambmd/ttskill/blob/main/backend/app/main.py"
click node_validation "https://github.com/iambmd/ttskill/blob/main/backend/app/validate.py"
click node_job_store "https://github.com/iambmd/ttskill/blob/main/backend/app/jobs.py"
click node_pipelines "https://github.com/iambmd/ttskill/blob/main/backend/app/pipelines.py"
click node_download "https://github.com/iambmd/ttskill/blob/main/backend/app/download.py"
click node_autocut "https://github.com/iambmd/ttskill/blob/main/backend/app/rally.py"
click node_bounce_filter "https://github.com/iambmd/ttskill/blob/main/backend/app/floor_bounce.py"
click node_clip_edit "https://github.com/iambmd/ttskill/blob/main/backend/app/cut.py"
click node_tech_pipeline "https://github.com/iambmd/ttskill/blob/main/backend/technique/pipeline.py"
click node_pose "https://github.com/iambmd/ttskill/blob/main/backend/technique/pose.py"
click node_stroke "https://github.com/iambmd/ttskill/blob/main/backend/technique/strokes.py"
click node_media "https://github.com/iambmd/ttskill/blob/main/backend/technique/media.py"
click node_renderer "https://github.com/iambmd/ttskill/blob/main/backend/technique/render.py"
click node_coach "https://github.com/iambmd/ttskill/blob/main/backend/agent/coach.py"
click node_agent_tools "https://github.com/iambmd/ttskill/blob/main/backend/agent/tools.py"
click node_matching "https://github.com/iambmd/ttskill/blob/main/backend/players/match.py"
click node_body_profile "https://github.com/iambmd/ttskill/blob/main/backend/players/body.py"
click node_equipment "https://github.com/iambmd/ttskill/blob/main/backend/equipment/recommend.py"
click node_style "https://github.com/iambmd/ttskill/blob/main/backend/technique/style.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_track_pages,node_submit,node_job_view toneBlue
class node_backend_api,node_validation,node_job_store,node_pipelines,node_download toneAmber
class node_autocut,node_bounce_filter,node_clip_edit,node_tech_pipeline,node_pose,node_stroke,node_media,node_renderer toneMint
class node_coach,node_agent_tools,node_matching,node_body_profile toneRose
class node_equipment,node_style,node_player toneIndigo
```

## Components

### Player experience

- [Track pages](https://github.com/iambmd/ttskill/blob/main/frontend/app/autocut/page.tsx): `frontend/app/autocut/page.tsx`
- [Job API routes](https://github.com/iambmd/ttskill/blob/main/frontend/app/api/jobs/autocut/route.ts): `frontend/app/api/jobs/autocut/route.ts`
- [Job results](https://github.com/iambmd/ttskill/blob/main/frontend/app/jobs/%5Bid%5D/page.tsx): `frontend/app/jobs/[id]/page.tsx`

### Jobs and orchestration

- [FastAPI routes](https://github.com/iambmd/ttskill/blob/main/backend/app/main.py): `backend/app/main.py`
- [Input validation](https://github.com/iambmd/ttskill/blob/main/backend/app/validate.py): `backend/app/validate.py`
- [Job records](https://github.com/iambmd/ttskill/blob/main/backend/app/jobs.py): `backend/app/jobs.py`
- [Pipeline orchestration](https://github.com/iambmd/ttskill/blob/main/backend/app/pipelines.py): `backend/app/pipelines.py`
- [Video download](https://github.com/iambmd/ttskill/blob/main/backend/app/download.py): `backend/app/download.py`

### Video analysis

- [Rally detection](https://github.com/iambmd/ttskill/blob/main/backend/app/rally.py): `backend/app/rally.py`
- [Rally filtering](https://github.com/iambmd/ttskill/blob/main/backend/app/floor_bounce.py): `backend/app/floor_bounce.py`
- [Clip editing](https://github.com/iambmd/ttskill/blob/main/backend/app/cut.py): `backend/app/cut.py`
- [Technique pipeline](https://github.com/iambmd/ttskill/blob/main/backend/technique/pipeline.py): `backend/technique/pipeline.py`
- [Pose analysis](https://github.com/iambmd/ttskill/blob/main/backend/technique/pose.py): `backend/technique/pose.py`
- [Stroke analysis](https://github.com/iambmd/ttskill/blob/main/backend/technique/strokes.py): `backend/technique/strokes.py`
- [Media processing](https://github.com/iambmd/ttskill/blob/main/backend/technique/media.py): `backend/technique/media.py`
- [Breakdown renderer](https://github.com/iambmd/ttskill/blob/main/backend/technique/render.py): `backend/technique/render.py`

### Coaching and matching

- [TT Coach agent](https://github.com/iambmd/ttskill/blob/main/backend/agent/coach.py): `backend/agent/coach.py`
- [Coach tools](https://github.com/iambmd/ttskill/blob/main/backend/agent/tools.py): `backend/agent/tools.py`
- [Pro matching](https://github.com/iambmd/ttskill/blob/main/backend/players/match.py): `backend/players/match.py`
- [Body profiles](https://github.com/iambmd/ttskill/blob/main/backend/players/body.py): `backend/players/body.py`

### Equipment and style

- [Rubber recommendations](https://github.com/iambmd/ttskill/blob/main/backend/equipment/recommend.py): `backend/equipment/recommend.py`
- [Coaching style](https://github.com/iambmd/ttskill/blob/main/backend/technique/style.py): `backend/technique/style.py`

### Other components

- **Player**

## Connections

- Player → Track pages: chooses track
- Track pages → Job API routes: submits job
- Job API routes → FastAPI routes: forwards request
- FastAPI routes → Input validation: validates input (evidence: `backend/app/main.py`)
- FastAPI routes → Job records: creates job (evidence: `backend/app/main.py`)
- FastAPI routes → Pipeline orchestration: starts pipeline (evidence: `backend/app/main.py`)
- Pipeline orchestration → Job records: updates status (evidence: `backend/app/pipelines.py`)
- FastAPI routes → Video download: fetches video (evidence: `backend/app/main.py`)
- Pipeline orchestration → Rally detection: detects rallies (evidence: `backend/app/pipelines.py`)
- Pipeline orchestration → Rally filtering: filters rallies (evidence: `backend/app/pipelines.py`)
- Pipeline orchestration → Clip editing: cuts clips (evidence: `backend/app/pipelines.py`)
- Rally filtering → Rally detection: uses candidates (evidence: `backend/app/floor_bounce.py`)
- Pipeline orchestration → Technique pipeline: runs breakdown (evidence: `backend/app/pipelines.py`)
- Technique pipeline → Media processing: makes proxy (evidence: `backend/technique/pipeline.py`)
- Technique pipeline → Pose analysis: extracts pose (evidence: `backend/technique/pipeline.py`)
- Technique pipeline → Stroke analysis: plans stroke (evidence: `backend/technique/pipeline.py`)
- Technique pipeline → Breakdown renderer: renders video (evidence: `backend/technique/pipeline.py`)
- FastAPI routes → TT Coach agent: starts coach (evidence: `backend/app/main.py`)
- TT Coach agent → Coach tools: dispatches tools (evidence: `backend/agent/coach.py`)
- Coach tools → Pipeline orchestration: calls shared work (evidence: `backend/agent/tools.py`)
- Pipeline orchestration → Pro matching: ranks pros (evidence: `backend/app/pipelines.py`)
- Pro matching → Body profiles: compares profiles (evidence: `backend/players/match.py`)
- FastAPI routes → Rubber recommendations: recommends rubbers (evidence: `backend/app/main.py`)
- Breakdown renderer → Coaching style: uses layout style (evidence: `backend/technique/render.py`)
- Job records → Job results: serves results
