# Phase 9.0 — Sports Center Platform Foundation

| Field | Value |
| --- | --- |
| Status | Complete |
| Module | sports-center |
| Version | 0.9.0.0 |
| Database | `sports_center_db` |
| API Port | 8006 |
| ADR | ADR-001, ADR-003, ADR-006, ADR-014 |

## Goal

Establish the **Sports Center Platform** as a completely independent enterprise microservice foundation.

This is **not** a Gym Management system. It is a generic sports platform capable of supporting Gym, CrossFit, Yoga, Pilates, Swimming, Football Academy, Basketball/Volleyball clubs, Martial Arts, Dance, Cycling, Climbing, Tennis, Skating, and future sports — without hardcoding sport-specific business rules.

## Sports Center Responsibilities (Phase 9.0)

Owns foundation aggregates only:

- sports_centers, branches, sports
- membership_types, memberships
- coaches, sports_roles, sports_permissions
- facilities, courts, rooms, locker_rooms, lockers
- devices, device_providers, attendance_gateways
- sports_configuration, sports_events, sports_settings, sports_audit

Plus adapter-based connector interfaces (QR, RFID, Barcode, Fingerprint, Face Recognition, Turnstile, Door Controllers, Payment Terminals, Attendance Devices).

**Does not** implement business workflows yet (booking, attendance engine, billing, class scheduling).

## Service Boundaries

| Sports Center owns | Sports Center does not own |
| --- | --- |
| Aggregates above | Accounting / Posting Engine |
| Sports HTTP APIs under `/api/v1/*` | CRM sales entities |
| `sports_center.*` permissions | Loyalty ledger / points |
| Publish-only sports events | Communication / SMS providers |
| Connector **interfaces** | Notification delivery |
| Tenant sports configuration | Identity / Storage blobs / AI inference |

Communication with platform services is **API + Events only**. No cross-DB access.

## Owned Modules (aggregates)

Independent aggregates in `backend/services/sports_center/app/models/foundation.py` (UUID refs only, no ORM relationship graphs).

## External Platform Dependencies (contracts only)

Defined in `app/providers/contracts.py` — **no implementations**:

- AccountingProvider, CRMProvider, LoyaltyProvider
- CommunicationProvider, NotificationProvider, StorageProvider
- AIProvider, IdentityProvider, Customer360Provider

## Connector Framework

`app/connectors/` provides Protocol interfaces + `ConnectorRegistry`. Vendor adapters register by `adapter_key`. Business services never embed vendor SDKs.

## Published Events

| Event | Aggregate |
| --- | --- |
| `sports_center.member.created` | membership (member identity) |
| `sports_center.membership.created` | membership |
| `sports_center.coach.created` | coach |
| `sports_center.facility.created` | facility |
| `sports_center.device.connected` / `disconnected` | device |
| `sports_center.attendance.provider.changed` | attendance_gateway |
| `sports_center.locker.assigned` / `released` | locker |

Additional supporting foundation events for centers, branches, sports, configuration, settings.

## Configuration Support

`sports_configurations` stores tenant/branch configuration shells for:

Working Hours · Membership Policies · Attendance Policies · Booking Policies · Waiting List · Custom Fields · Time Zone · Language · Currency

## API Contracts (foundation)

| Resource | Prefix |
| --- | --- |
| Sports centers | `/api/v1/sports-centers` |
| Branches | `/api/v1/branches` |
| Sports catalog | `/api/v1/sports` |
| Membership types / memberships | `/api/v1/membership-types`, `/api/v1/memberships` |
| Coaches / roles / permissions | `/api/v1/coaches`, `/roles`, `/permissions` |
| Facilities / courts / rooms / lockers | `/api/v1/facilities`, `/courts`, `/rooms`, `/locker-rooms`, `/lockers` |
| Devices / providers / gateways | `/api/v1/devices`, `/device-providers`, `/attendance-gateways` |
| Configuration / events / settings | `/api/v1/configurations`, `/events`, `/settings` |
| Health | `/health` |

Special actions: `POST /devices/{id}/connect|disconnect`, `POST /lockers/{id}/assign|release`.

## Permissions

`sports_center.*` trees covering centers, branches, sports, memberships, coaches, facilities, devices, configuration, audit, etc.

## Architecture Decisions

1. Database-per-service (`sports_center_db`) — ADR-001 / ADR-014
2. Row-level `tenant_id` — ADR-003
3. Event publish contracts via `EventEnvelope` — ADR-006
4. Sport-agnostic catalog model — no hardcoded sport engines
5. Adapter-based connectors — vendor logic outside business services
6. Soft delete + actor audit + sports audit log
7. Optimistic locking on centers, memberships, lockers, devices, configurations

## Folder Structure

```
backend/services/sports_center/
  app/
    api/v1/
    core/
    middlewares/
    models/
    repositories/
    services/
    validators/
    schemas/
    events/
    permissions/
    providers/
    connectors/
    policies/
    specifications/
    commands/
    queries/
    tests/
  alembic/versions/0001_initial.py
  scripts/ensure_db.py
  README.md
```

## Tests Executed

Architecture · API foundation flow · permissions · migration · dependency · connectors · docs

## Related Documents

- [Phase Handover 9.0](phase-handover/phase-9-0.md)
- [ADR-014](architecture/adr/ADR-014.md)
- [Module Registry](module-registry.md)
- [Progress](progress.md)