# razmans/elbow-space-checker architecture

> Architecture diagram of the GitHub repository razmans/elbow-space-checker, 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/razmans/elbow-space-checker
- Repository: https://github.com/razmans/elbow-space-checker

## Overview

Elbow Room is a local train-coach occupancy demo. Its main workflow configures simulated, recorded-video, or RTSP coach sources; samples frames and estimates passenger counts; optionally verifies the same sample with a local vision model; computes occupancy and freshness; and serves live state and persisted history to a React dashboard. The graph also includes the documented offline evaluation capability. Source excerpts establish the main detector, RTSP, verification, persistence, and UI behavior; some server routing and capture orchestration details are unsampled, so those links rely on explicit README documentation or are omitted.

Main entry points: [`apps/backend/elbow_room/server.py`](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/server.py) (API and observations), [`apps/backend/elbow_room/evaluation.py`](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/evaluation.py) (Video evaluation), [`apps/backend/elbow_room/video.py`](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/video.py) (Person detector), [`apps/web/src/main.tsx`](https://github.com/razmans/elbow-space-checker/blob/main/apps/web/src/main.tsx) (Live coach dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend service"]
  node_config["Coach configuration"]
  node_server["API and observations<br/>[server.py]"]
  node_store[("Observation history<br/>[server.py]")]
end

subgraph group_vision["Capture and vision"]
  node_recording["Recorded video<br/>[video.py]"]
  node_rtsp["RTSP capture<br/>[rtsp.py]"]
  node_detector["Person detector<br/>[video.py]"]
  node_model["Detector assets<br/>[model.py]"]
  node_verification["Local verification<br/>[verification.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_web_app["Live coach dashboard<br/>[main.tsx]"]
  node_history_ui["History browser<br/>[History.tsx]"]
  node_contract["Observation types<br/>[observation.ts]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Video evaluation<br/>[evaluation.py]"]
  node_evaluation_data["Labelled samples<br/>[evaluation.py]"]
end

node_operator(("Demo operator"))
node_vision_service["Local vision service"]

node_operator -->|"configures"| node_config
node_config -->|"configures"| node_server
node_server -->|"runs replay"| node_recording
node_server -->|"starts capture"| node_rtsp
node_recording -->|"samples frames"| node_detector
node_rtsp -->|"counts frames"| node_detector
node_detector -->|"checks assets"| node_model
node_server -->|"persists observations"| node_store
node_server -->|"submits samples"| node_verification
node_verification -->|"requests counts"| node_vision_service
node_server -->|"streams state"| node_web_app
node_web_app -->|"uses types"| node_contract
node_web_app -->|"renders"| node_history_ui
node_history_ui -->|"fetches history"| node_server
node_history_ui -->|"uses types"| node_contract
node_operator -->|"evaluates"| node_evaluation
node_evaluation_data -->|"labels samples"| node_evaluation
node_evaluation -->|"counts frames"| node_detector
node_evaluation -->|"checks samples"| node_verification

click node_config "https://github.com/razmans/elbow-space-checker/tree/main/config"
click node_server "https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/server.py"
click node_store "https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/server.py"
click node_recording "https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/video.py"
click node_rtsp "https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/rtsp.py"
click node_detector "https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/video.py"
click node_model "https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/model.py"
click node_verification "https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/verification.py"
click node_web_app "https://github.com/razmans/elbow-space-checker/blob/main/apps/web/src/main.tsx"
click node_history_ui "https://github.com/razmans/elbow-space-checker/blob/main/apps/web/src/History.tsx"
click node_contract "https://github.com/razmans/elbow-space-checker/blob/main/contracts/observation.ts"
click node_evaluation "https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/evaluation.py"
click node_evaluation_data "https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/evaluation.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_config,node_server,node_store toneBlue
class node_recording,node_rtsp,node_detector,node_model,node_verification toneAmber
class node_web_app,node_history_ui,node_contract toneMint
class node_evaluation,node_evaluation_data toneRose
class node_operator,node_vision_service toneIndigo
```

## Components

### Backend service

- [Coach configuration](https://github.com/razmans/elbow-space-checker/tree/main/config): `config`
- [API and observations](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/server.py): `apps/backend/elbow_room/server.py`
- [Observation history](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/server.py): `apps/backend/elbow_room/server.py`

### Capture and vision

- [Recorded video](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/video.py): `apps/backend/elbow_room/video.py`
- [RTSP capture](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/rtsp.py): `apps/backend/elbow_room/rtsp.py`
- [Person detector](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/video.py): `apps/backend/elbow_room/video.py`
- [Detector assets](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/model.py): `apps/backend/elbow_room/model.py`
- [Local verification](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/verification.py): `apps/backend/elbow_room/verification.py`

### Dashboard

- [Live coach dashboard](https://github.com/razmans/elbow-space-checker/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [History browser](https://github.com/razmans/elbow-space-checker/blob/main/apps/web/src/History.tsx): `apps/web/src/History.tsx`
- [Observation types](https://github.com/razmans/elbow-space-checker/blob/main/contracts/observation.ts): `contracts/observation.ts`

### Evaluation

- [Video evaluation](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/evaluation.py): `apps/backend/elbow_room/evaluation.py`
- [Labelled samples](https://github.com/razmans/elbow-space-checker/blob/main/apps/backend/elbow_room/evaluation.py): `apps/backend/elbow_room/evaluation.py`

### Other components

- **Demo operator**
- **Local vision service**

## Connections

- Demo operator → Coach configuration: configures (evidence: `README.md`)
- Coach configuration → API and observations: configures (evidence: `README.md`)
- API and observations → Recorded video: runs replay (evidence: `apps/backend/elbow_room/server.py`)
- API and observations → RTSP capture: starts capture (evidence: `apps/backend/elbow_room/server.py`)
- Recorded video → Person detector: samples frames (evidence: `apps/backend/elbow_room/video.py`)
- RTSP capture → Person detector: counts frames (evidence: `apps/backend/elbow_room/rtsp.py`)
- Person detector → Detector assets: checks assets (evidence: `apps/backend/elbow_room/video.py`)
- API and observations → Observation history: persists observations (evidence: `apps/backend/elbow_room/server.py`)
- API and observations → Local verification: submits samples (evidence: `README.md`)
- Local verification → Local vision service: requests counts (evidence: `README.md`)
- API and observations → Live coach dashboard: streams state (evidence: `README.md`)
- Live coach dashboard → Observation types: uses types (evidence: `apps/web/src/main.tsx`)
- Live coach dashboard → History browser: renders (evidence: `apps/web/src/main.tsx`)
- History browser → API and observations: fetches history (evidence: `apps/web/src/History.tsx`)
- History browser → Observation types: uses types (evidence: `apps/web/src/History.tsx`)
- Demo operator → Video evaluation: evaluates (evidence: `README.md`)
- Labelled samples → Video evaluation: labels samples (evidence: `apps/backend/elbow_room/evaluation.py`)
- Video evaluation → Person detector: counts frames (evidence: `apps/backend/elbow_room/evaluation.py`)
- Video evaluation → Local verification: checks samples (evidence: `apps/backend/elbow_room/evaluation.py`)
