# kingtmata/btl-ai-camera-cd8 architecture

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

- Interactive diagram: https://gitdiagram.com/kingtmata/btl-ai-camera-cd8
- Repository: https://github.com/kingtmata/btl-ai-camera-cd8

## Overview

Classroom AI is a local classroom-image and video detection/tracking application with separate video, terminal, and Streamlit interfaces, plus a dataset and model-training workflow. The main video path accepts a user-selected video, runs detection (optionally tracking), and produces annotated playback or an exported MP4. A separate research branch evaluates inference variants and validation campaigns. Edges are limited to README-documented behavior and relationships visible in the supplied source excerpts or SOURCE INDEX; unsampled details are not asserted.

Main entry points: [`src/classroom_ai/video/pipeline.py`](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/pipeline.py) (Video pipeline), [`src/classroom_ai/interfaces/web/app.py`](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/web/app.py) (Web interface), [`src/classroom_ai/training/worker.py`](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/training/worker.py) (Training worker), [`src/classroom_ai/inference/detector.py`](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/inference/detector.py) (Object detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_video_cli["Video entry point<br/>[__main__.py]"]
  node_terminal["Terminal UI<br/>[terminal.py]"]
  node_terminal_process["Video controls"]
  node_web_app["Web interface<br/>[app.py]"]
  node_web_preview["Image preview<br/>[preview.py]"]
  node_web_training["Training interface<br/>[training.py]"]
end

subgraph group_video["Video processing"]
  node_video_pipeline["Video pipeline<br/>[pipeline.py]"]
  node_video_media["Media I/O<br/>[media.py]"]
  node_video_core["Video core<br/>[core.py]"]
  node_video_tracking["Person tracking"]
  node_video_render["Video rendering<br/>[rendering.py]"]
  node_video_playback["Video playback<br/>[playback.py]"]
  node_video_metrics["Run metrics<br/>[metrics.py]"]
end

subgraph group_inference["Detection and inference"]
  node_detector["Object detector<br/>[detector.py]"]
  node_camera["Webcam inference<br/>[camera.py]"]
  node_device["Device selection<br/>[devices.py]"]
  node_variants["Inference variants<br/>[variants.py]"]
end

subgraph group_training["Datasets and training"]
  node_datasets["Dataset validation<br/>[datasets.py]"]
  node_classes["Class definitions<br/>[classes.py]"]
  node_run_manager["Training runs<br/>[manager.py]"]
  node_worker["Training worker<br/>[worker.py]"]
  node_evaluation["Model evaluation<br/>[evaluation.py]"]
  node_kaggle_export["Kaggle export<br/>[kaggle_export.py]"]
end

subgraph group_research["Research evaluation"]
  node_campaign["Experiment campaigns"]
  node_validation_replay["Validation replay"]
  node_experiment_eval["Improvement evaluation"]
end

node_user(("Local user"))
node_video_input["Video input"]

node_user -->|"starts"| node_video_cli
node_user -->|"selects"| node_video_input
node_video_input -->|"processes"| node_video_pipeline
node_video_cli -->|"offers UI"| node_terminal
node_video_cli -->|"dispatches"| node_terminal_process
node_video_cli -->|"runs"| node_video_pipeline
node_terminal -->|"uses controls"| node_terminal_process
node_video_pipeline -->|"reads and exports"| node_video_media
node_video_pipeline -->|"uses"| node_video_core
node_video_pipeline -->|"runs detection"| node_detector
node_video_pipeline -->|"dispatches tracking"| node_video_tracking
node_video_pipeline -.->|"records metrics"| node_video_metrics
node_video_pipeline -.->|"supports playback"| node_video_playback
node_video_tracking -->|"uses"| node_detector
node_video_tracking -->|"uses"| node_video_media
node_video_tracking -->|"uses"| node_video_render
node_user -->|"opens"| node_web_app
node_web_app -->|"controls webcam"| node_camera
node_web_app -->|"uses"| node_detector
node_web_app -->|"renders preview"| node_web_preview
node_web_app -->|"opens training"| node_web_training
node_web_app -->|"checks active run"| node_run_manager
node_web_preview -->|"draws detections"| node_detector
node_web_training -->|"manages runs"| node_run_manager
node_web_training -->|"exports training data"| node_kaggle_export
node_run_manager -.->|"spawns worker"| node_worker
node_worker -->|"validates run"| node_run_manager
node_worker -->|"validates release"| node_datasets
node_worker -->|"uses protocol"| node_evaluation
node_worker -->|"checks classes"| node_classes
node_evaluation -.->|"uses data"| node_datasets
node_evaluation -.->|"uses detector"| node_detector
node_campaign -.->|"uses variants"| node_variants
node_validation_replay -->|"replays variants"| node_variants
node_experiment_eval -.->|"evaluates campaign"| node_campaign

click node_video_cli "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/__main__.py"
click node_terminal "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/terminal.py"
click node_terminal_process "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/terminal_process.py"
click node_web_app "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/web/app.py"
click node_web_preview "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/web/preview.py"
click node_web_training "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/web/training.py"
click node_video_pipeline "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/pipeline.py"
click node_video_media "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/media.py"
click node_video_core "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/core.py"
click node_video_tracking "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/tracked_processing.py"
click node_video_render "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/rendering.py"
click node_video_playback "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/playback.py"
click node_video_metrics "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/metrics.py"
click node_detector "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/inference/detector.py"
click node_camera "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/inference/camera.py"
click node_device "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/inference/devices.py"
click node_variants "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/inference/variants.py"
click node_datasets "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/datasets.py"
click node_classes "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/classes.py"
click node_run_manager "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/training/manager.py"
click node_worker "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/training/worker.py"
click node_evaluation "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/evaluation.py"
click node_kaggle_export "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/training/kaggle_export.py"
click node_campaign "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/experiments/experiment_campaign.py"
click node_validation_replay "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/experiments/validation_replay.py"
click node_experiment_eval "https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/experiments/e3_improvement_eval.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_video_cli,node_terminal,node_terminal_process,node_web_app,node_web_preview,node_web_training,node_user toneBlue
class node_video_pipeline,node_video_media,node_video_core,node_video_tracking,node_video_render,node_video_playback,node_video_metrics toneAmber
class node_detector,node_camera,node_device,node_variants toneMint
class node_datasets,node_classes,node_run_manager,node_worker,node_evaluation,node_kaggle_export toneRose
class node_campaign,node_validation_replay,node_experiment_eval,node_video_input toneIndigo
```

## Components

### User interfaces

- [Video entry point](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/__main__.py): `src/classroom_ai/video/__main__.py`
- [Terminal UI](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/terminal.py): `src/classroom_ai/interfaces/terminal.py`
- [Video controls](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/terminal_process.py): `src/classroom_ai/interfaces/terminal_process.py`
- [Web interface](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/web/app.py): `src/classroom_ai/interfaces/web/app.py`
- [Image preview](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/web/preview.py): `src/classroom_ai/interfaces/web/preview.py`
- [Training interface](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/interfaces/web/training.py): `src/classroom_ai/interfaces/web/training.py`

### Video processing

- [Video pipeline](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/pipeline.py): `src/classroom_ai/video/pipeline.py`
- [Media I/O](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/media.py): `src/classroom_ai/video/media.py`
- [Video core](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/core.py): `src/classroom_ai/video/core.py`
- [Person tracking](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/tracked_processing.py): `src/classroom_ai/video/tracked_processing.py`
- [Video rendering](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/rendering.py): `src/classroom_ai/video/rendering.py`
- [Video playback](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/playback.py): `src/classroom_ai/video/playback.py`
- [Run metrics](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/video/metrics.py): `src/classroom_ai/video/metrics.py`

### Detection and inference

- [Object detector](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/inference/detector.py): `src/classroom_ai/inference/detector.py`
- [Webcam inference](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/inference/camera.py): `src/classroom_ai/inference/camera.py`
- [Device selection](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/inference/devices.py): `src/classroom_ai/inference/devices.py`
- [Inference variants](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/inference/variants.py): `src/classroom_ai/inference/variants.py`

### Datasets and training

- [Dataset validation](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/datasets.py): `src/classroom_ai/datasets.py`
- [Class definitions](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/classes.py): `src/classroom_ai/classes.py`
- [Training runs](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/training/manager.py): `src/classroom_ai/training/manager.py`
- [Training worker](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/training/worker.py): `src/classroom_ai/training/worker.py`
- [Model evaluation](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/evaluation.py): `src/classroom_ai/evaluation.py`
- [Kaggle export](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/training/kaggle_export.py): `src/classroom_ai/training/kaggle_export.py`

### Research evaluation

- [Experiment campaigns](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/experiments/experiment_campaign.py): `src/classroom_ai/experiments/experiment_campaign.py`
- [Validation replay](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/experiments/validation_replay.py): `src/classroom_ai/experiments/validation_replay.py`
- [Improvement evaluation](https://github.com/kingtmata/btl-ai-camera-cd8/blob/main/src/classroom_ai/experiments/e3_improvement_eval.py): `src/classroom_ai/experiments/e3_improvement_eval.py`

### Other components

- **Local user**
- **Video input**

## Connections

- Local user → Video entry point: starts (evidence: `README.md`)
- Local user → Video input: selects (evidence: `README.md`)
- Video input → Video pipeline: processes (evidence: `README.md`)
- Video entry point → Terminal UI: offers UI (evidence: `src/classroom_ai/video/__main__.py`)
- Video entry point → Video controls: dispatches (evidence: `src/classroom_ai/video/__main__.py`)
- Video entry point → Video pipeline: runs (evidence: `src/classroom_ai/video/__main__.py`)
- Terminal UI → Video controls: uses controls (evidence: `src/classroom_ai/interfaces/terminal.py`)
- Video pipeline → Media I/O: reads and exports (evidence: `src/classroom_ai/video/pipeline.py`)
- Video pipeline → Video core: uses (evidence: `src/classroom_ai/video/pipeline.py`)
- Video pipeline → Object detector: runs detection (evidence: `src/classroom_ai/video/pipeline.py`)
- Video pipeline → Person tracking: dispatches tracking (evidence: `src/classroom_ai/video/pipeline.py`)
- Video pipeline → Run metrics: records metrics (evidence: `src/classroom_ai/video/pipeline.py`)
- Video pipeline → Video playback: supports playback (evidence: `src/classroom_ai/video/pipeline.py`)
- Person tracking → Object detector: uses (evidence: `src/classroom_ai/video/tracked_processing.py`)
- Person tracking → Media I/O: uses (evidence: `src/classroom_ai/video/tracked_processing.py`)
- Person tracking → Video rendering: uses (evidence: `src/classroom_ai/video/tracked_processing.py`)
- Local user → Web interface: opens (evidence: `README.md`)
- Web interface → Webcam inference: controls webcam (evidence: `src/classroom_ai/interfaces/web/app.py`)
- Web interface → Object detector: uses (evidence: `src/classroom_ai/interfaces/web/app.py`)
- Web interface → Image preview: renders preview (evidence: `src/classroom_ai/interfaces/web/app.py`)
- Web interface → Training interface: opens training (evidence: `src/classroom_ai/interfaces/web/app.py`)
- Web interface → Training runs: checks active run (evidence: `src/classroom_ai/interfaces/web/app.py`)
- Image preview → Object detector: draws detections (evidence: `src/classroom_ai/interfaces/web/preview.py`)
- Training interface → Training runs: manages runs (evidence: `src/classroom_ai/interfaces/web/training.py`)
- Training interface → Kaggle export: exports training data (evidence: `src/classroom_ai/interfaces/web/training.py`)
- Training runs → Training worker: spawns worker (evidence: `src/classroom_ai/training/worker.py`)
- Training worker → Training runs: validates run (evidence: `src/classroom_ai/training/worker.py`)
- Training worker → Dataset validation: validates release (evidence: `src/classroom_ai/training/worker.py`)
- Training worker → Model evaluation: uses protocol (evidence: `src/classroom_ai/training/worker.py`)
- Training worker → Class definitions: checks classes (evidence: `src/classroom_ai/training/worker.py`)
- Model evaluation → Dataset validation: uses data (evidence: `src/classroom_ai/evaluation.py`)
- Model evaluation → Object detector: uses detector (evidence: `src/classroom_ai/evaluation.py`)
- Experiment campaigns → Inference variants: uses variants
- Validation replay → Inference variants: replays variants (evidence: `src/classroom_ai/experiments/validation_replay.py`)
- Improvement evaluation → Experiment campaigns: evaluates campaign
