# Ballbox DB Plan

## Decision
- Ballbox owns the durable database after TVs migration.
- No more memory-backed or file-backed persistence work for TVs.
- End state does not keep retro-compatibility fields, names, or compatibility shims.
- The shared core migration is now live on the current schema and seed.

## Database
- PostgreSQL
- Prisma managed from `ballbox`
- `DATABASE_URL` belongs in Ballbox runtime/env
- Local development now also has a tracked Docker Postgres path via `docker-compose.yml`, with `.env.local` pointing Prisma and Next to `ballbox_local` by default.
- `pnpm db:push` and `pnpm db:seed` target `.env.local`, and the seed now provisions demo coach/club password hashes for local sign-in.

## Final Shared Core
- `Club`
- `Venue`
- `VendingMachine`
- `Screen`
- `TvDevice`

## Final Product Models
- `Product`
- `PaymentSession`
- `Advertiser`
- `Campaign`
- `Creative`
- `Assignment`
- `Impression`
- `Coach`
- `OpenMatch`
- `Class`
- `Player`
- `Membership`

## Ownership
- `Club -> Venue -> VendingMachine`
- `Club -> Venue -> Screen`
- `Screen -> TvDevice` optional one-to-one
- `Screen -> Assignment -> Campaign`
- `VendingMachine -> PaymentSession`
- `Product -> PaymentSession`
- `Club -> Membership <- Player`
- `Club? -> Coach`
- `Venue -> OpenMatch`
- `Venue -> Class`

## Migration Status
1. Final entities and foreign keys are in the Ballbox Prisma schema.
2. Shared `network` references are live for TVs and payments.
3. Legacy compatibility columns already removed from the schema:
   - `Screen.deviceId`
   - `Venue.machineCount`
4. Payments now persist canonical `vendingMachineId` and `productId` foreign keys.
5. Post-`pnpm db:push` plus `pnpm db:seed` verification against Ballbox Postgres confirms physical tables still expose canonical `Screen.vendingMachineId`, `Impression.tvDeviceId`, and `PaymentSession.vendingMachineId`.
6. No `machineId`, `deviceId`, or `PaymentSessionRef` persistence aliases exist in the current Ballbox Postgres schema.
7. Remaining work is post-migration cleanup in code/docs/API naming, not structural schema migration.

## Constraints
- Do not add temporary persistence layers in Ballbox.
- Do not keep permanent compatibility layers once migration lands.
- Shared physical/operational entities must live in `network`, not inside `payments` or `tvs`.