# Ballbox Host App Plan

## Goal
- Keep `ballbox` as the host app for the Ballbox platform.
- Preserve `/` as marketing home.
- Run product/admin surfaces inside one repo with explicit route boundaries.
- Converge on one shared `network` core for clubs, venues, vending machines, screens, and related operations.

## Product Stage
- Ballbox is still in validation for padel centers.
- There are no customers yet.
- Near-term proof still depends on pilots with the first vending machines.

## Current State

### Host app shape
- `/` is the marketing home.
- `/admin` is the shared admin shell.
- Product-separated admin surfaces exist for `tvs`, `payments`, `network`, `sports`, and `players`.
- Public/non-admin surfaces now include `/classes`, `/classes/[offerId]`, `/classes-by-date`, `/classes/me`, `/coaches`, `/clubs`, `/coaches/settings`, `/clubs/coaches`, and `/clubs/venues/[venueId]`.

### Data and architecture
- Ballbox now runs on Ballbox-owned Postgres/Prisma for its active domains.
- `lib/ballbox-store.ts` has been reduced to a compatibility facade; domain/backend modules now own most runtime behavior directly.
- Shared route helper/envelope patterns exist under `lib/http/*`.
- Local quality gate includes `pnpm lint`, `pnpm typecheck`, `pnpm test:contracts`, `pnpm test:e2e`, and `pnpm build`.
- On `ballbox-first`, Playwright uses the stable production-style e2e server path (`pnpm build:e2e && pnpm start:e2e` on port `3020`).

### TVs
- TVs are an internal Ballbox module, not a separate app.
- `/player/[screenId]` is the lightweight TV runtime served as plain HTML + JavaScript for constrained devices.
- TV runtime/admin reads and writes now flow through Ballbox DB-backed modules.
- Runtime cache/media/impression/heartbeat/manifest-refresh logic now lives in one shared core used by both runtime shells.
- Runtime diagnostics include parity snapshot export for real-device evidence capture.
- Remaining important gap: real-device parity closure for CacheStorage/object-URL behavior.

### Payments
- Native Mercado Pago ownership now lives inside Ballbox.
- Public webhook intake exists at `/notification/mercadopago`.
- Native QR order creation exists at `/api/integrations/payments/orders`.
- `/admin/payments` acts as operator CRUD/reconciliation plus provider test/debug harness.
- Current stance: production vending UX should go through the TCN machine protocol, not the admin QR page.
- Club settlement remains manual/bookkeeping-first for now.

### Network
- Network core has DB-backed CRUD for clubs, venues, and vending machines.
- Nullable `Club.atcSportclubId` support is preserved for legacy/local rows.
- Naming direction stays: `Club`, `Venue`, `VendingMachine`, `Screen`, `TvDevice`.

### Sports / coaches / clubs
- Sports/classes now have DB-backed entities and APIs for coaches, open matches, class offers, and class requests.
- `/classes` and `/classes-by-date` are the main public booking/demo surfaces.
- Coach and club account entry starts at `/coaches`.
- Coach workspace and club workspace are both live with real operational flows.
- Coach experience discovery is still early; do not overstate product certainty beyond current research docs.

## Current Implementation Direction
- Immediate high-value closure: finish TV runtime parity evidence for `/player/[screenId]` on real devices.
- Keep maintainability work guided by `docs/maintainability-priorities-2026-03.md`.
- Keep machine-payment work guided by current TCN machine reality docs, not the old TCN/Mercado Pago adapter assumption.
- Accessibility and offline/navigation are valid follow-up themes, but durable task tracking for them lives outside this repo in the global system.

## Main Constraints
- Treat this repo as near-future client production.
- Prisma workflow is migration-first; no normal `db push` workflow.
- `docs/implemented-*.md` should describe only shipped behavior.
- Discovery claims for coaches/sports must stay aligned with `docs/coaches-discovery-stage.md`.
- ATC write/admin is still not integrated; current ATC usage is limited and must degrade cleanly.

## Key Docs
- `docs/index.md`
- `docs/repo-map.md`
- `docs/maintainability-priorities-2026-03.md`
- `docs/implemented-host-app.md`
- `docs/implemented-network.md`
- `docs/implemented-payments.md`
- `docs/implemented-players.md`
- `docs/implemented-sports.md`
- `docs/implemented-tvs.md`
- `docs/tcn-machine-reality-2026-05-26.html`
- `docs/tcn-future-action-options.html`
- `docs/coaches-discovery-stage.md`

## Executive Payment Track
1. Provider-level Mercado Pago proof is closed.
2. Machine risk is still open, but current machine payment reality is external-device based rather than Ballbox-native TCN integration.
3. Next meaningful machine milestone is clean delivery, rebranding, and better operation around the current EasyCoin/BillWallet/OurVend stack.
4. Revenue-share automation stays deferred until machine reality justifies it.