CALIBER

Precision shooting performance intelligence. Whoop for marksmen.

---

🎯 Overview

CALIBER is a professional real-time performance telemetry and intelligence platform designed specifically for Olympic-style precision shooting (ISSF).

Because electronic scoring targets like the industry-standard SIUS SR24 lack open APIs or local network data streams, CALIBER bridges the gap by intercepting the HDMI feed driving the athlete's lane monitor. Using computer vision (powered by Claude Vision / OCR), CALIBER extracts shot coordinates in real time, processes the telemetry through a high-precision deterministic analytics engine, and streams live biomechanical and performance insights directly to dashboards used by athletes, coaches, and shooting clubs.

🌟 Key Highlights

• Non-Invasive Data Capture: Captures and decodes HDMI video signals directly from electronic target displays. No modifications to target hardware required.
• Claude Vision OCR Pipeline: Highly accurate computer vision extraction framework to read scores and shot coordinates in real time.
• Pure Analytics Engine: 100% test-covered Python analytics engine computing target geometry, center-of-mass shifts, fatigue trends, and group consistency (Cohn's d, CEP, windage/elevation drift).
• Cinematic Live Dashboard: Next.js 15 app designed for live match view with sub-second WebSocket broadcasts, skeleton loading patterns, and tabular figure animations.
• Multi-Tenant Architecture: Built from the database level upwards, featuring a clean organization hierarchy supporting athletes, coaches, and club administrators with Row-Level Security (RLS).

---

🏗️ System Architecture

CALIBER utilizes a hybrid TypeScript/Python monorepo optimized for quick deployment, type safety, and analytical precision.

graph TD
    subgraph Edge Layer
        HDMI[SR24 HDMI Output] -->|Video Feed| Pi[apps/edge - Raspberry Pi]
        Synth[apps/edge-synthetic - Dev Simulator]
    end

    subgraph API & Ingestion Layer
        Pi -->|POST /v1/edge/frames| API[services/api - FastAPI]
        Synth -->|Stream Sim| API
        API -->|Extract Frame| Vision[services/vision - Claude Vision / OCR]
    end

    subgraph Storage & Realtime Layer
        API -->|Insert Shot/Telemetry| DB[(Supabase / Postgres)]
        DB -->|Realtime CDC| WS[WebSockets - Supabase Realtime]
    end

    subgraph Analytics & Intelligence
        DB -->|Post-Session Data| Analytics[services/analytics - pure Python]
        DB -->|Diagnostics| Coach[services/ai-coach - Rule & LLM]
    end

    subgraph Frontend Surface
        WS -->|Realtime Stream| Web[apps/web - Next.js 15 Dashboard]
        WS -->|Live Telemetry| Mobile[apps/mobile - Expo Mobile App]
    end

    style HDMI fill:#2d3748,stroke:#cbd5e0,stroke-width:2px;
    style DB fill:#1a202c,stroke:#E4572E,stroke-width:2px;
    style WS fill:#2c5282,stroke:#4299e1,stroke-width:2px;
    style Web fill:#2d3748,stroke:#ed8936,stroke-width:2px;

Loading

---

📂 Workspace Layout

A unified monorepo powered by Turborepo orchestrates building and testing across the frontend and backend services:

Path	Component	Description / Tech Stack
apps/web	Frontend Web App	Next.js 15, React 19, Tailwind CSS v4, dynamic target canvas rendering
apps/edge-synthetic	Telemetry Simulator	Python script simulating realistic ISSF matches with custom scenarios (fatigue, drift)
apps/edge	Hardware Edge Daemon	Raspberry Pi frame capture client (Python, OpenCV)
apps/mobile	Mobile Application	Expo / React Native scaffolding
services/api	Backend API Gateway	FastAPI, Pydantic, edge-device authentication
services/vision	Frame Processor	Extraction engine wrapping Claude Vision API with retry resilience
services/analytics	Analytics Engine	Pure Python (numpy, scipy) for ballistic and geometry computation
services/ai-coach	Automated Coach	Diagnosis system providing mechanical feedback (rule-based & LLM-driven)
packages/ui	Component Library	Shared React design-system primitives constructed strictly from --color-* CSS variables
packages/types	Shared Type Contracts	Shared Zod schemas + automatic TypeScript models generated from OpenAPI schemas
packages/config	Config Presets	Shared linting, formatting, and compiler settings (ESLint, TS, Prettier)
packages/analytics-core	JS Analytics	Client-side JavaScript port of core rolling statistics
infrastructure/supabase	Database Layer	SQL migrations, seed scripts, and Row-Level Security (RLS) smoke tests
infrastructure/docker	Service Orchestration	Dockerfiles and docker-compose rigs for local services
docs/	Documentation	Architectural maps, design guidelines, analytics math references, and operator runbooks

---

⚙️ Toolchain & Requirements

CALIBER requires modern runtimes that prioritize speed and developer ergonomics:

• Bun ($\ge$ 1.3): Powering JS workspaces, installation, and Turborepo execution.
• uv ($\ge$ 0.11): Lightning-fast Python package and project manager. No global virtual environments or manual pip installs required.
• Docker: For local Supabase CLI orchestration and service containers.
• Python ($\ge$ 3.11): Underlying interpreter for analytical backend services.

---

🚀 Quick Start

Get your local development environment up and running in under 5 minutes:

1. Installation

Install all JavaScript/TypeScript and Python dependencies concurrently:

# Install node_modules across monorepo workspaces
bun install

# Synchronize python virtual environments and dependencies for all services
uv sync --all-packages

2. Configure Environment

Copy the example environment configuration:

cp .env.example .env.local

Note

Fill in your Supabase connection strings, local JWT secrets, and Anthropic API keys (if testing vision/coaching services) inside .env.local.

3. Spin Up Services

Start all development servers (Next.js, FastAPI, Dev servers) in parallel using Turborepo:

bun run dev

4. Run a Synthetic Match

To populate your local dashboard with live, dynamic shot telemetry:

cd apps/edge-synthetic
uv run edge-synthetic --scenario fatigue --realtime

This will print a Session URL. Open the link (http://localhost:3000/live/<sessionId>) in your browser to view the real-time target canvas render shots as they are fired.

---

🛠️ Commands Reference

Ensure quality checks pass before pushing changes.

Task	JS / TS commands	Python commands
Development	bun run dev	—
Linting	bun run lint	uv run ruff check .
Formatting	bun run format	uv run ruff format
Type Checking	bun run typecheck	uv run mypy services apps
Unit Testing	bun run test	uv run pytest
Production Build	bun run build	—

---

🔒 Row-Level Security (RLS) & Multi-Tenancy

CALIBER isolates organization data natively in the database.

• RLS Policies: Standard users cannot view sessions or shots belonging to other organizations.
• Edge Device Authorization: Raspberry Pi edge units authenticate via custom HTTP headers mapped against hashed API keys (edge_devices.api_key_hash). RLS rules verify edge keys against the corresponding organization workspace.

To run local RLS verification tests:

bunx supabase db reset

---

🤝 Contributing

Contributions to CALIBER are highly welcome. Please adhere to the following standards:

• TypeScript: Enforce strict type checking. No any types allowed without a comment explaining the necessity (// REASON: ...).
• Python: Strictly typed with mypy. Enforce linting and formatting using ruff.
• Pure Logic: Do not mix network I/O or database queries into the pure mathematical routines in services/analytics.
• Documentation: If making architecture decisions or API contract adjustments, update CLAUDE.md and DECISIONS.md.

For more detailed guides, check out CONTRIBUTING.md and the docs/ directory.

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.