TorbatYar/docs/phase-handover/phase-9-0.md

Phase Handover — 9.0 Sports Center Platform Foundation

Mandatory starting point for Phase 9.1.

Overview

Phase 9.0 delivered the independent Sports Center Platform microservice (sports-center-service, sports_center_db, port 8006, version 0.9.0.0). Foundation aggregates, connector interfaces, permissions, publish-only events, APIs, migration, and docs are in place. No business workflows (booking, attendance engine, billing, class lifecycle) were implemented.

Completed Scope

• Independent service scaffold aligned with Loyalty/Communication patterns
• 20 foundation tables / aggregates
• Adapter-based connector framework (interfaces only)
• Platform provider contracts (Accounting, CRM, Loyalty, Communication, Notification, Storage, AI, Identity, Customer360)
• Tenant-aware CRUD APIs + connect/disconnect + locker assign/release
• Configuration shells for hours/policies/locale/custom fields
• Alembic 0001_initial, compose + .env.example wiring
• ADR-014, phase doc, module registry, progress updates

Created Modules

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

Created Models

See backend/services/sports_center/app/models/foundation.py — SportsCenter, Branch, Sport, MembershipType, Membership, Coach, SportsRole, SportsPermission, Facility, Court, Room, LockerRoom, Locker, DeviceProvider, Device, AttendanceGateway, SportsConfiguration, SportsEvent, SportsSetting, SportsAuditLog.

Repositories

Tenant-scoped repositories in app/repositories/foundation.py extending TenantBaseRepository (soft-delete aware).

Services

Application services in app/services/foundation.py + audit_service.py. Write path: validate → uniqueness → persist → audit → commit → publish.

Validators

app/validators/foundation.py — codes, email/phone, enums, date ranges, optimistic lock, forbid sport-specific hardcoding keys.

Permissions

sports_center.* definitions in app/permissions/definitions.py (registry contracts; route-level enforcement deferred like Loyalty).

Events

Publish-only contracts in app/events/types.py including:

• sports_center.member.created
• sports_center.membership.created
• sports_center.coach.created
• sports_center.facility.created
• sports_center.device.connected / disconnected
• sports_center.attendance.provider.changed
• sports_center.locker.assigned / released

In-memory publisher only (outbox bus later per ADR-006).

Public APIs

All under /api/v1/* (see phase doc). Soft delete via POST /{id}/delete.

Internal APIs

None beyond service-local health and foundation CRUD. No internal S2S endpoints yet.

Database Changes

New database sports_center_db (sole owner). No changes to Core/CRM/Loyalty/Communication schemas.

Migration History

Revision	Description
0001_initial	Create all Phase 9.0 foundation tables

Indexes

Tenant + status / deleted indexes; unique (tenant_id, code) (and center-scoped codes where applicable); locker/membership number uniques.

Constraints

Unique constraints always include tenant_id. No cross-DB FKs. Cross-aggregate links are UUID columns only.

Configuration

SportsConfiguration + SportsSetting support working hours, membership/attendance/booking policies, waiting list, custom fields, timezone, language, currency.

Connector Framework

app/connectors/ — DeviceConnector + specialized Protocols + ConnectorRegistry. Capabilities: QR, RFID, Barcode, Fingerprint, Face Recognition, Turnstile, Door Controller, Payment Terminal, Attendance Device, Custom.

Provider Interfaces

Platform providers in app/providers/contracts.py (Protocols only). Device providers stored as registry rows with adapter_key.

Extension Points

• Register vendor adapters on ConnectorRegistry by adapter_key
• Add sports catalog entries without code changes
• Policy JSON documents for later engines
• Commands / Queries / Specifications / Policies packages prepared as shells

Integration Points

REST + Events only. External refs: external_customer_ref, external_crm_contact_ref, external_user_ref, file/device refs.

Accounting Integration

Contract only (AccountingProvider). No postings in 9.0.

CRM Integration

Contract only; membership may store external_crm_contact_ref.

Loyalty Integration

Contract only; Sports does not own points/ledger.

Communication Integration

Contract only; no SMS/provider calls from Sports.

AI Integration

Contract only (AIProvider.suggest).

Storage Integration

Contract only; store file refs later.

Notification Integration

Contract only; no delivery ownership.

Known Limitations

• No booking / attendance / membership lifecycle engines
• No vendor device adapters implemented
• Permissions defined but not enforced on routes (JWT + X-Tenant-ID only)
• Events in-memory (no durable outbox yet)
• No frontend module UI

Backward Compatibility

New service — no breaking changes to existing modules.

Architectural Decisions

ADR-014 (this service). Relies on ADR-001, ADR-003, ADR-006.

Future Dependencies

Phase 9.1+ engines will depend on this foundation, Core entitlement, and later Communication/Notification/Accounting integrations.

Requirements for Phase 9.1

1. Read this handover + docs/sports-center-phase-9-0.md + ADR-014 first
2. Do not recreate foundation aggregates
3. Implement the next unfinished sports engine only (as scoped in next-steps/roadmap)
4. Keep sport-agnostic rules; keep connectors adapter-based
5. Do not own Accounting/CRM/Loyalty/Communication/Notification/Storage/Identity/AI

Open Risks

• Device vendor diversity may require careful adapter versioning
• Membership vs Loyalty “member” terminology — keep refs explicit
• Unique constraints with nullable branch_id on settings may behave differently across DBs

Performance Notes

Foundation CRUD only; indexes on tenant_id + common filters. No hot-path attendance writes yet.

Security Notes

JWT via Keycloak; tenant isolation via X-Tenant-ID + row tenant_id. Soft deletes. Audit trail append-only. Never put vendor secrets in business tables without encryption strategy (later).

Testing Summary

Pytest suites: architecture, API flow/events, permissions, migration, dependency, connectors, docs.

Documentation Summary

• docs/sports-center-phase-9-0.md
• docs/phase-handover/phase-9-0.md (this file)
• docs/architecture/adr/ADR-014.md
• docs/phases/SportsCenter/README.md
• Updates: progress, module-registry, next-steps, ADR README, module-boundaries

Next Phase Entry Point

Start Phase 9.1 from this document. Confirm scope in docs/next-steps.md before coding. Do not skip ahead to later sports phases.