COORDINATOR Web - Developer Documentation¶
COORDINATOR Web is the frontend for a sports "coordinator" system—an agentic analytics platform that helps teams manage sessions, build context through embeddings, and train custom AI models.
What This Platform Does¶
- Organizations & Teams: Multi-tenant structure with granular member roles (owner, admin, member)
- AI Chat Interface: Context-aware chat powered by organization/team embeddings
- Live Sessions: Capture games/practices with structured logging, video streaming, and object detection
- Context & Embeddings: Convert files, timelines, and session data into searchable embeddings
- Training Jobs: Launch LoRA/DoRA adapter training on accumulated context
- Devices & Cameras: Manage connected hardware for live streaming
Tech Stack¶
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| UI | React 19, Tailwind CSS 4, shadcn/ui |
| State | TanStack Query 5 |
| Auth | BetterAuth (passkeys, 2FA, org/teams, Stripe) |
| Validation | Zod |
| Payments | Stripe |
| Logging | Winston + Loki |
Backend Dependencies¶
The frontend connects to external services:
| Service | Environment Variable | Purpose |
|---|---|---|
| Auth API | NEXT_PUBLIC_AUTH_API_URL |
BetterAuth authentication service |
| Core API | NEXT_PUBLIC_API_BASE_URL |
Domain-specific REST API |
| WebSocket | NEXT_PUBLIC_WS_PORT |
Camera streaming (default: 7103) |
| Loki | LOKI_URL |
Server-side log aggregation |
Documentation Structure¶
Architecture¶
Project structure, routing patterns, and architectural decisions.
Features¶
- Authentication - Auth flows, BetterAuth integration, passkeys
- Portal & Navigation - Layout, sidebars, RBAC
- Sessions - Live logging, streaming, timeline
- Context & Embeddings - File upload, search, embedding management
- Chat - AI chat with SSE streaming
- Training - Job configuration and monitoring
- Devices & Cameras - Hardware management, video streaming
- Organizations & Billing - Multi-tenancy, Stripe integration
Frontend Architecture¶
- Routing - App Router structure
- State & Data Flow - TanStack Query patterns
- Components - UI component reference
- Hooks - Custom hooks reference
- Tutorial System - Onboarding implementation
API & Integrations¶
- API Overview - Endpoints and patterns
- BetterAuth - Authentication integration
- Core Actions - Domain API endpoints
- Admin API - Admin-only endpoints
- Streaming - SSE and WebSocket patterns
- Stripe - Payment integration
- Logging - Winston/Loki setup
Operations¶
- Configuration - Environment variables and config
- Build & Deploy - Docker, CI/CD
- Security & Roles - RBAC implementation
Quick Start¶
# Install dependencies
npm install
# Set up environment
cp .env.example .env.local
# Edit .env.local with your API URLs
# Development
npm run dev
# Production build
npm run build
npm start
Key Patterns¶
API Access¶
All domain hooks use a shared pattern:
1. Get auth token via useAuth()
2. Build requests with fetchJSON() utility
3. Use TanStack Query for caching and mutations
4. Toast notifications for user feedback
Role-Based Access¶
The RoleProvider enforces permissions at the component level:
- owner - Full access
- admin - Most administrative functions
- member - Basic read/write access
State Management¶
- Server state: TanStack Query with
queryKeynamespaced by organization/team - Auth state: BetterAuth React client
- Local UI state: React useState, localStorage for persistence