# sjc042/courtvision_public architecture

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

## Overview

CourtVision is an Android Phase 0 spike for on-device basketball tracking. The user starts the camera workflow, selects an inference mode, and sees detections, a tracked ball, pose overlays, and runtime statistics. The documented processing stages are frame analysis, YOLO detection, Kalman tracking, and gated pose inference; CSV instrumentation records performance and tracking data. The excerpts and source index establish key module references, while some internal wiring and the shot-state-machine implementation were not sampled, so those relationships are omitted or identified as documented only.

Main entry points: [`app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt) (Camera view model), [`app/src/main/java/com/courtvision/spike/pipeline/FrameProcessor.kt`](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/FrameProcessor.kt) (Frame processor), [`app/src/main/java/com/courtvision/spike/MainActivity.kt`](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/MainActivity.kt) (Main activity), [`app/src/main/java/com/courtvision/spike/camera/CameraScreen.kt`](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/camera/CameraScreen.kt) (Camera screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and Camera"]
  node_activity["Main activity<br/>[MainActivity.kt]"]
  node_screen["Camera screen<br/>[CameraScreen.kt]"]
  node_viewmodel["Camera view model<br/>[CameraViewModel.kt]"]
  node_uistate["Camera UI state<br/>[CameraUiState.kt]"]
end

subgraph group_vision["Vision Pipeline"]
  node_analyzer["Image analyzer"]
  node_processor["Frame processor<br/>[FrameProcessor.kt]"]
  node_contracts["Frame contracts<br/>[FrameContracts.kt]"]
  node_bitmap["Bitmap operations<br/>[BitmapOps.kt]"]
  node_tracker["Kalman tracker"]
  node_shotstate["Shot state machine"]
end

subgraph group_runtime["Inference Runtime"]
  node_pose["Pose inference"]
  node_poseapi["Pose engine contract"]
  node_gpuprobe["GPU delegate probe"]
  node_qnnprobe["QNN delegate probe"]
  node_nnapiprobe["NNAPI delegate probe"]
end

subgraph group_telemetry["Tracking and Metrics"]
  node_perf["Performance CSV"]
  node_perfrow["Per-frame metrics<br/>[PerFramePerfRow.kt]"]
  node_perflogger["Performance logger"]
  node_trackinglog["Tracking CSV"]
end

node_user(("App user"))
node_camera["CameraX frames"]

node_user -->|"opens app"| node_activity
node_activity -->|"sets content"| node_screen
node_screen -->|"uses state"| node_viewmodel
node_viewmodel -->|"updates"| node_uistate
node_camera -.->|"provides frames"| node_analyzer
node_analyzer -->|"delegates frames"| node_processor
node_viewmodel -->|"configures pipeline"| node_processor
node_processor -->|"updates track"| node_tracker
node_processor -->|"runs pose"| node_pose
node_pose -->|"implements"| node_poseapi
node_processor -.->|"preprocesses frames"| node_bitmap
node_processor -.->|"uses contracts"| node_contracts
node_viewmodel -->|"probes GPU"| node_gpuprobe
node_viewmodel -->|"probes QNN"| node_qnnprobe
node_viewmodel -->|"probes NNAPI"| node_nnapiprobe
node_viewmodel -->|"logs frames"| node_perf
node_perf -->|"serializes rows"| node_perfrow
node_viewmodel -->|"exports metrics"| node_perflogger
node_viewmodel -->|"exports tracks"| node_trackinglog
node_processor -.->|"may derive shot state"| node_shotstate

click node_activity "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/MainActivity.kt"
click node_screen "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/camera/CameraScreen.kt"
click node_viewmodel "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt"
click node_uistate "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/camera/CameraUiState.kt"
click node_analyzer "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/SpikeImageAnalyzer.kt"
click node_processor "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/FrameProcessor.kt"
click node_contracts "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/FrameContracts.kt"
click node_bitmap "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/BitmapOps.kt"
click node_tracker "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/KalmanBallTracker.kt"
click node_pose "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PoseLandmarkInterpreter.kt"
click node_poseapi "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PoseInferenceEngine.kt"
click node_gpuprobe "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/GpuDelegateProbe.kt"
click node_qnnprobe "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/QnnDelegateProbe.kt"
click node_nnapiprobe "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/NnApiDelegateProbe.kt"
click node_perf "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PerFramePerfCsvLogger.kt"
click node_perfrow "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PerFramePerfRow.kt"
click node_perflogger "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PerformanceCsvLogger.kt"
click node_trackinglog "https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/TrackingCsvLogger.kt"
click node_shotstate "https://github.com/sjc042/courtvision_public/tree/main/app/src/main/java/com/courtvision/spike/pipeline"

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_activity,node_screen,node_viewmodel,node_uistate,node_user toneBlue
class node_analyzer,node_processor,node_contracts,node_bitmap,node_tracker,node_shotstate toneAmber
class node_pose,node_poseapi,node_gpuprobe,node_qnnprobe,node_nnapiprobe toneMint
class node_perf,node_perfrow,node_perflogger,node_trackinglog toneRose
class node_camera toneIndigo
```

## Components

### App and Camera

- [Main activity](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/MainActivity.kt): `app/src/main/java/com/courtvision/spike/MainActivity.kt`
- [Camera screen](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/camera/CameraScreen.kt): `app/src/main/java/com/courtvision/spike/camera/CameraScreen.kt`
- [Camera view model](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt): `app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`
- [Camera UI state](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/camera/CameraUiState.kt): `app/src/main/java/com/courtvision/spike/camera/CameraUiState.kt`

### Vision Pipeline

- [Image analyzer](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/SpikeImageAnalyzer.kt): `app/src/main/java/com/courtvision/spike/pipeline/SpikeImageAnalyzer.kt`
- [Frame processor](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/FrameProcessor.kt): `app/src/main/java/com/courtvision/spike/pipeline/FrameProcessor.kt`
- [Frame contracts](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/FrameContracts.kt): `app/src/main/java/com/courtvision/spike/pipeline/FrameContracts.kt`
- [Bitmap operations](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/BitmapOps.kt): `app/src/main/java/com/courtvision/spike/pipeline/BitmapOps.kt`
- [Kalman tracker](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/KalmanBallTracker.kt): `app/src/main/java/com/courtvision/spike/pipeline/KalmanBallTracker.kt`
- [Shot state machine](https://github.com/sjc042/courtvision_public/tree/main/app/src/main/java/com/courtvision/spike/pipeline): `app/src/main/java/com/courtvision/spike/pipeline`

### Inference Runtime

- [Pose inference](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PoseLandmarkInterpreter.kt): `app/src/main/java/com/courtvision/spike/pipeline/PoseLandmarkInterpreter.kt`
- [Pose engine contract](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PoseInferenceEngine.kt): `app/src/main/java/com/courtvision/spike/pipeline/PoseInferenceEngine.kt`
- [GPU delegate probe](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/GpuDelegateProbe.kt): `app/src/main/java/com/courtvision/spike/pipeline/GpuDelegateProbe.kt`
- [QNN delegate probe](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/QnnDelegateProbe.kt): `app/src/main/java/com/courtvision/spike/pipeline/QnnDelegateProbe.kt`
- [NNAPI delegate probe](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/NnApiDelegateProbe.kt): `app/src/main/java/com/courtvision/spike/pipeline/NnApiDelegateProbe.kt`

### Tracking and Metrics

- [Performance CSV](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PerFramePerfCsvLogger.kt): `app/src/main/java/com/courtvision/spike/pipeline/PerFramePerfCsvLogger.kt`
- [Per-frame metrics](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PerFramePerfRow.kt): `app/src/main/java/com/courtvision/spike/pipeline/PerFramePerfRow.kt`
- [Performance logger](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/PerformanceCsvLogger.kt): `app/src/main/java/com/courtvision/spike/pipeline/PerformanceCsvLogger.kt`
- [Tracking CSV](https://github.com/sjc042/courtvision_public/blob/main/app/src/main/java/com/courtvision/spike/pipeline/TrackingCsvLogger.kt): `app/src/main/java/com/courtvision/spike/pipeline/TrackingCsvLogger.kt`

### Other components

- **App user**
- **CameraX frames**

## Connections

- App user → Main activity: opens app (evidence: `app/src/main/java/com/courtvision/spike/MainActivity.kt`)
- Main activity → Camera screen: sets content (evidence: `app/src/main/java/com/courtvision/spike/MainActivity.kt`)
- Camera screen → Camera view model: uses state (evidence: `app/src/main/java/com/courtvision/spike/MainActivity.kt`)
- Camera view model → Camera UI state: updates (evidence: `app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`)
- CameraX frames → Image analyzer: provides frames (evidence: `README.md`)
- Image analyzer → Frame processor: delegates frames (evidence: `app/src/main/java/com/courtvision/spike/pipeline/SpikeImageAnalyzer.kt`)
- Camera view model → Frame processor: configures pipeline (evidence: `app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`)
- Frame processor → Kalman tracker: updates track (evidence: `app/src/main/java/com/courtvision/spike/pipeline/FrameProcessor.kt`)
- Frame processor → Pose inference: runs pose (evidence: `app/src/main/java/com/courtvision/spike/pipeline/FrameProcessor.kt`)
- Pose inference → Pose engine contract: implements (evidence: `app/src/main/java/com/courtvision/spike/pipeline/PoseLandmarkInterpreter.kt`)
- Frame processor → Bitmap operations: preprocesses frames
- Frame processor → Frame contracts: uses contracts
- Camera view model → GPU delegate probe: probes GPU (evidence: `app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`)
- Camera view model → QNN delegate probe: probes QNN (evidence: `app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`)
- Camera view model → NNAPI delegate probe: probes NNAPI (evidence: `app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`)
- Camera view model → Performance CSV: logs frames (evidence: `app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`)
- Performance CSV → Per-frame metrics: serializes rows (evidence: `app/src/main/java/com/courtvision/spike/pipeline/PerFramePerfCsvLogger.kt`)
- Camera view model → Performance logger: exports metrics (evidence: `app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`)
- Camera view model → Tracking CSV: exports tracks (evidence: `app/src/main/java/com/courtvision/spike/camera/CameraViewModel.kt`)
- Frame processor → Shot state machine: may derive shot state (evidence: `README.md`)