# ieomn/rallymate architecture

> Architecture diagram of the GitHub repository ieomn/rallymate, 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/ieomn/rallymate
- Repository: https://github.com/ieomn/rallymate

## Overview

RallyMate is a tennis-video analysis product: a player uploads a video, receives vision-based motion analysis and evidence-aware reference scoring, then reviews measurements, ball trajectories, and annotated playback. The browser uses a same-origin service gateway; the Python service queues work for a persistent inference worker. The README documents upload, resumable processing, trajectory retrieval, reports, and guarded MiMo explanations. Several service and scoring implementations were not excerpted, so those internal connections are omitted rather than inferred.

Main entry points: [`scoring-demo-web/app/ScoreLab.tsx`](https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/ScoreLab.tsx) (Analysis UI), [`src/rallymate_vision/pipeline.py`](https://github.com/ieomn/rallymate/blob/main/src/rallymate_vision/pipeline.py) (Video pipeline), [`scoring-demo-web/app/lib/api-client.ts`](https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/lib/api-client.ts) (Upload client), [`src/rallymate_service/worker.py`](https://github.com/ieomn/rallymate/blob/main/src/rallymate_service/worker.py) (Inference worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Analysis UI<br/>[ScoreLab.tsx]"]
  node_webclient["Upload client<br/>[api-client.ts]"]
  node_webgateway["Web gateway<br/>[gateway.ts]"]
  node_trajectory["Trajectory viewer"]
  node_advice["Advice endpoint<br/>[route.ts]"]
  node_reports["Report export<br/>[report-export.ts]"]
end

subgraph group_service["Service runtime"]
  node_api["Analysis API<br/>[api.py]"]
  node_uploads["Upload handling<br/>[uploads.py]"]
  node_jobdb[("Job database<br/>[database.py]")]
  node_worker["Inference worker<br/>[worker.py]"]
end

subgraph group_vision["Vision analysis"]
  node_pipeline["Video pipeline<br/>[pipeline.py]"]
  node_inference["Frame inference<br/>[inference.py]"]
  node_posemeta["Pose schemas<br/>[metadata.py]"]
end

subgraph group_domain["Analysis and scoring"]
  node_events["Event detection<br/>[rules.py]"]
  node_features["Motion features<br/>[event_features.py]"]
  node_scoring["Evidence scoring<br/>[scoring_context.py]"]
  node_validation["Result validation<br/>[validation.py]"]
end

subgraph group_evidence["Evidence workflows"]
  node_truth["Truth annotation"]
  node_evaluation["Pose evaluation"]
end

node_player(("Player"))
node_mimo["MiMo provider"]

node_player -->|"uploads video"| node_webapp
node_webapp -.->|"starts analysis"| node_webclient
node_webclient -->|"sends upload"| node_webgateway
node_webgateway -->|"proxies requests"| node_api
node_api -.->|"handles uploads"| node_uploads
node_worker -->|"claims jobs"| node_jobdb
node_worker -->|"runs analysis"| node_pipeline
node_pipeline -->|"runs inference"| node_inference
node_inference -->|"uses schemas"| node_posemeta
node_pipeline -.->|"detects events"| node_events
node_events -->|"measures motion"| node_features
node_pipeline -->|"builds scores"| node_scoring
node_pipeline -->|"validates output"| node_validation
node_webapp -->|"shows trajectory"| node_trajectory
node_trajectory -->|"fetches trajectory"| node_webclient
node_webapp -->|"exports reports"| node_reports
node_webapp -->|"requests explanation"| node_advice
node_advice -->|"requests guarded advice"| node_mimo
node_truth -.->|"supports review"| node_evaluation

click node_webapp "https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/ScoreLab.tsx"
click node_webclient "https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/lib/api-client.ts"
click node_webgateway "https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/worker/gateway.ts"
click node_trajectory "https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/lib/trajectory-viewer.ts"
click node_advice "https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/api/advice/route.ts"
click node_reports "https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/lib/report-export.ts"
click node_api "https://github.com/ieomn/rallymate/blob/main/src/rallymate_service/api.py"
click node_uploads "https://github.com/ieomn/rallymate/blob/main/src/rallymate_service/uploads.py"
click node_jobdb "https://github.com/ieomn/rallymate/blob/main/src/rallymate_service/database.py"
click node_worker "https://github.com/ieomn/rallymate/blob/main/src/rallymate_service/worker.py"
click node_pipeline "https://github.com/ieomn/rallymate/blob/main/src/rallymate_vision/pipeline.py"
click node_inference "https://github.com/ieomn/rallymate/blob/main/src/rallymate_vision/inference.py"
click node_posemeta "https://github.com/ieomn/rallymate/blob/main/src/rallymate_vision/pose/metadata.py"
click node_events "https://github.com/ieomn/rallymate/blob/main/src/rallymate_events/rules.py"
click node_features "https://github.com/ieomn/rallymate/blob/main/src/rallymate_features/event_features.py"
click node_scoring "https://github.com/ieomn/rallymate/blob/main/src/rallymate_scoring/scoring_context.py"
click node_validation "https://github.com/ieomn/rallymate/blob/main/src/rallymate_vision/validation.py"
click node_truth "https://github.com/ieomn/rallymate/blob/main/src/rallymate_annotation/scoring_truth_event_execution.py"
click node_evaluation "https://github.com/ieomn/rallymate/blob/main/src/rallymate_evaluation/pose_diagnostic_review.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_webapp,node_webclient,node_webgateway,node_trajectory,node_advice,node_reports toneBlue
class node_api,node_uploads,node_jobdb,node_worker toneAmber
class node_pipeline,node_inference,node_posemeta toneMint
class node_events,node_features,node_scoring,node_validation toneRose
class node_truth,node_evaluation,node_player,node_mimo toneIndigo
```

## Components

### Web experience

- [Analysis UI](https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/ScoreLab.tsx): `scoring-demo-web/app/ScoreLab.tsx`
- [Upload client](https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/lib/api-client.ts): `scoring-demo-web/app/lib/api-client.ts`
- [Web gateway](https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/worker/gateway.ts): `scoring-demo-web/worker/gateway.ts`
- [Trajectory viewer](https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/lib/trajectory-viewer.ts): `scoring-demo-web/app/lib/trajectory-viewer.ts`
- [Advice endpoint](https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/api/advice/route.ts): `scoring-demo-web/app/api/advice/route.ts`
- [Report export](https://github.com/ieomn/rallymate/blob/main/scoring-demo-web/app/lib/report-export.ts): `scoring-demo-web/app/lib/report-export.ts`

### Service runtime

- [Analysis API](https://github.com/ieomn/rallymate/blob/main/src/rallymate_service/api.py): `src/rallymate_service/api.py`
- [Upload handling](https://github.com/ieomn/rallymate/blob/main/src/rallymate_service/uploads.py): `src/rallymate_service/uploads.py`
- [Job database](https://github.com/ieomn/rallymate/blob/main/src/rallymate_service/database.py): `src/rallymate_service/database.py`
- [Inference worker](https://github.com/ieomn/rallymate/blob/main/src/rallymate_service/worker.py): `src/rallymate_service/worker.py`

### Vision analysis

- [Video pipeline](https://github.com/ieomn/rallymate/blob/main/src/rallymate_vision/pipeline.py): `src/rallymate_vision/pipeline.py`
- [Frame inference](https://github.com/ieomn/rallymate/blob/main/src/rallymate_vision/inference.py): `src/rallymate_vision/inference.py`
- [Pose schemas](https://github.com/ieomn/rallymate/blob/main/src/rallymate_vision/pose/metadata.py): `src/rallymate_vision/pose/metadata.py`

### Analysis and scoring

- [Event detection](https://github.com/ieomn/rallymate/blob/main/src/rallymate_events/rules.py): `src/rallymate_events/rules.py`
- [Motion features](https://github.com/ieomn/rallymate/blob/main/src/rallymate_features/event_features.py): `src/rallymate_features/event_features.py`
- [Evidence scoring](https://github.com/ieomn/rallymate/blob/main/src/rallymate_scoring/scoring_context.py): `src/rallymate_scoring/scoring_context.py`
- [Result validation](https://github.com/ieomn/rallymate/blob/main/src/rallymate_vision/validation.py): `src/rallymate_vision/validation.py`

### Evidence workflows

- [Truth annotation](https://github.com/ieomn/rallymate/blob/main/src/rallymate_annotation/scoring_truth_event_execution.py): `src/rallymate_annotation/scoring_truth_event_execution.py`
- [Pose evaluation](https://github.com/ieomn/rallymate/blob/main/src/rallymate_evaluation/pose_diagnostic_review.py): `src/rallymate_evaluation/pose_diagnostic_review.py`

### Other components

- **Player**
- **MiMo provider**

## Connections

- Player → Analysis UI: uploads video (evidence: `README.md`)
- Analysis UI → Upload client: starts analysis
- Upload client → Web gateway: sends upload (evidence: `README.md`)
- Web gateway → Analysis API: proxies requests (evidence: `README.md`)
- Analysis API → Upload handling: handles uploads
- Inference worker → Job database: claims jobs (evidence: `src/rallymate_service/worker.py`)
- Inference worker → Video pipeline: runs analysis (evidence: `src/rallymate_service/worker.py`)
- Video pipeline → Frame inference: runs inference (evidence: `src/rallymate_vision/pipeline.py`)
- Frame inference → Pose schemas: uses schemas (evidence: `src/rallymate_vision/inference.py`)
- Video pipeline → Event detection: detects events
- Event detection → Motion features: measures motion (evidence: `src/rallymate_events/rules.py`)
- Video pipeline → Evidence scoring: builds scores (evidence: `src/rallymate_vision/pipeline.py`)
- Video pipeline → Result validation: validates output (evidence: `src/rallymate_vision/pipeline.py`)
- Analysis UI → Trajectory viewer: shows trajectory (evidence: `README.md`)
- Trajectory viewer → Upload client: fetches trajectory (evidence: `README.md`)
- Analysis UI → Report export: exports reports (evidence: `README.md`)
- Analysis UI → Advice endpoint: requests explanation (evidence: `README.md`)
- Advice endpoint → MiMo provider: requests guarded advice (evidence: `scoring-demo-web/app/api/advice/route.ts`)
- Truth annotation → Pose evaluation: supports review