# Coaches Coordination Gap Analysis

## Purpose
- Identify what Ballbox would need to add in order to support the first wedge: group/class coordination with ATC-backed context.

## Current Ballbox Starting Point
- Ballbox already has DB-backed `Coach`, `Class`, and `OpenMatch` entities.
- Ballbox already has admin CRUD and read APIs for those entities.
- Ballbox does not yet have the actual coordination loop; it only has the roster/event foundation.

## Current Model Gaps

### Class ownership and coordination context
- `Class` does not reference a `Coach`.
- `Class` has no explicit status.
- `Class` has no coordination metadata like notes, source, or last-updated reason.

### Participants and state
- no player-to-class participation model
- no attendance or confirmation state
- no no-show / cancelled / pending state
- no waitlist or capacity fields

### Recurrence and weekly workflow
- no recurring class series or class template
- no linkage between one class instance and the broader weekly group
- no way to represent "this class moved" vs "this class is a standalone event"

### Court / booking linkage
- no local court concept in Ballbox sports
- no local link from a class to an ATC court/booking/booking instance
- no ATC source-of-truth fields yet

## Current API Gaps

### Sports admin APIs today
- current sports admin APIs only create/update/delete simple rows
- no workflow-specific endpoint exists for coordination

### What a coordination wedge likely needs
- read class with richer context
- update class state and coordination fields
- update participant/confirmation state
- attach ATC-linked court/booking context
- list upcoming classes in a coordination-friendly shape

## Current UI Gaps

### Today
- `/admin/sports` is CRUD-oriented
- no workflow screen for managing one class/group over time

### Likely needed for wedge v1
- one focused coordination view for classes
- clear display of:
  - assigned coach
  - venue
  - class status
  - participant count / state
  - court/booking context if available
  - recent changes or coordination notes
- one action path for updating the class state without editing a generic form

## ATC Data Likely Needed For This Wedge

### Read first
- sportclub metadata
- court metadata
- booking / booking-instance context tied to the class if available
- availability snapshot for class-adjacent coordination decisions

### Write likely needed soon after
- update or create booking-side state when coordination changes require operational closure
- possibly participant sync if ATC supports the relevant booking participant flow

## Proposed Minimal Ballbox Changes

### Domain
1. enrich `Class`
   - add `coachId`
   - add `status`
   - add optional `capacity`
   - add optional `notes`
   - add optional ATC linkage fields such as external ids
2. add class participants
   - likely `ClassParticipant` model
   - status per participant: invited / confirmed / cancelled / attended / no_show
3. add recurring-group support
   - likely `ClassSeries` or equivalent parent concept
   - enough to represent repeated weekly coordination, not a full scheduling engine

### API
1. keep existing CRUD routes
2. add one coordination-oriented read endpoint
   - e.g. class detail with coach, participants, and ATC-linked context
3. add one coordination-oriented update path
   - update class status / notes / participant states
4. add an internal ATC boundary instead of embedding ATC payloads directly in route handlers

### UI
1. keep `/admin/sports` as foundation
2. add one class coordination screen or drawer
3. optimize around one weekly operator workflow, not generic form editing

### Integration boundary
1. define `AtcClient` interface
2. create `mockAtcClient`
3. later add `realAtcClient`
4. map ATC objects into Ballbox-local coordination view models

## What Ballbox Does Not Need Yet
- full player-facing sports app
- full club ERP
- full recurring scheduling engine
- advanced messaging system
- generalized CRM

## Suggested Build Order
1. define minimal domain additions for `Class`, `ClassParticipant`, and recurring-group concept
2. define ATC boundary and mocks for the coordination view
3. build one coordination-oriented read model and UI
4. add the smallest write path needed for the class state update loop
5. only then expand toward reprogramming and deeper ATC write flows

## Decision Note
- This wedge keeps `group/class coordination` as the easiest entry point.
- It also preserves a clean path to the likely stronger next wedge: reprogramming with deeper ATC write integration.