Fitness & Gym Management Domain Design

Modern fitness centers, boutique group class studios, and multi-branch gym chains operate in an environment where recurring membership economics, scarce class capacity, physical access governance, and personal training services converge. Unlike a simple retail business, a gym sells ongoing access rights rather than discrete products: every active membership is a living contract with a billing cycle, a freeze allowance, an access tier, and a renewal date that must be enforced at the front door, in the booking app, and in the finance ledger at the same time.

When a member walks up to a turnstile, the business cannot tolerate ambiguity: Is the membership active? Is it frozen? Has it expired yesterday? Does the plan include access to the pool zone? When a popular evening cycling class has thirty bikes and two hundred interested members, the booking engine must guarantee fairness, capacity integrity, and a predictable waitlist. And when a member stops paying but keeps training, revenue leakage becomes a direct threat to the business model.

The Fitness (GYM) domain operates as the sovereign bounded context governing all membership, scheduling, booking, access, and training workflows within the Obelaw open-core enterprise ecosystem. It establishes definitive domain boundaries for Membership Agreements, freeze and suspension lifecycles, class capacity and waitlist orchestration, turnstile check-in validation, personal training credit packages, and member progress engagement.

---

1. Business Drivers & Frontline Operational Vulnerabilities

In fitness facilities, relying on paper sign-in sheets, disconnected booking spreadsheets, or generic invoicing tools creates critical revenue, safety, and member-experience risks:

flowchart TD
    subgraph Antipattern["Without Fitness Domain: Fragmented Club Management"]
        RevenueLeakage["Membership Revenue Leakage<br/>Expired, frozen, or non-paying members still training because access is never validated against contract state"]
        OverbookingChaos["Class Overbooking & Empty Bikes<br/>Confirmed attendees exceeding studio capacity, or popular time slots running half-empty due to unchecked no-shows"]
        FreezeAbuse["Freeze Policy Abuse<br/>Members suspending billing while continuing to train, with no expiry extension tracking"]
        CreditDisputes["Personal Training Credit Disputes<br/>Trainers and members disagreeing over consumed, refunded, or expired session credits"]
        FrontDeskAmbiguity["Front Desk Ambiguity<br/>Staff manually deciding who may enter, with inconsistent day pass and guest pass handling"]
    end

    subgraph Solution["With Fitness Domain: Sovereign Membership Architecture"]
        AccessGate["Deterministic Access Gate<br/>Every check-in validated against live membership state, freeze windows, and zone entitlements"]
        CapacityEngine["Capacity & Waitlist Engine<br/>Hard capacity ceilings, ordered waitlists, and time-boxed promotion offers"]
        FreezeMachine["Contract-Compliant Freeze Machine<br/>Access suspension with automatic day-for-day expiry extension and annual quota enforcement"]
        CreditLedger["Personal Training Credit Ledger<br/>Append-only credit consumption, refund, and forfeiture trail per package"]
        StrikePolicy["No-Show & Late-Cancel Strike Policy<br/>Automated strike accrual and booking privilege suspension protecting scarce class seats"]
    end

    Antipattern -.->|Resolved By Domain-Driven Design| Solution

The Cost of Membership System Fragmentation

• Revenue Leakage at the Door: Without a hard link between contract state and the turnstile, members whose memberships expired, were cancelled, or are currently frozen continue to consume club capacity they are not paying for.
• Destroyed Class Economics: Group classes are perishable inventory — an unsold bike at 18:00 is lost forever. Unchecked no-shows block paying members from attending, while overbooking beyond studio capacity creates safety hazards and member churn.
• Unenforceable Freeze Policies: Freezing a membership is a contractual right with strict limits. Without formal state tracking, clubs cannot prove when a freeze started, whether access was truly suspended, or how the expiry date moved.
• Trainer Credit Conflicts: Personal training is sold in pre-paid credit packages. Without an append-only credit ledger, disputes over consumed, refunded, and expired sessions erode trust between members, trainers, and the club.
• Inconsistent Front Desk Decisions: Day passes, guest passes, and peak-hour restrictions handled ad hoc produce inconsistent member treatment and untraceable revenue.

---

2. Core Strategic Pillars of the Fitness Domain

The Fitness bounded context is anchored by seven foundational architectural pillars:

flowchart TD
    FITNESS["Fitness (GYM) Domain Core"]

    P1["1. Membership & Subscription Lifecycle<br/>Plans, tiers, activation, renewal, upgrade, cancellation, and expiry"]
    P2["2. Freeze & Suspension State Machine<br/>Contract-compliant suspension, access blocking, and expiry extension"]
    P3["3. Class Scheduling & Booking Orchestration<br/>Capacity ceilings, ordered waitlists, booking windows, and cancellation cutoffs"]
    P4["4. Access Control & Check-in Governance<br/>Turnstile validation, zone entitlements, day passes, and denial reasons"]
    P5["5. Personal Training Credit Operations<br/>Pre-paid credit packages, session appointments, and forfeiture rules"]
    P6["6. Strike & Penalty Enforcement<br/>Late cancellation and no-show strikes with booking privilege suspension"]
    P7["7. Member Engagement & Progress<br/>Workout program assignments, attendance streaks, and body assessments"]

    FITNESS --> P1
    FITNESS --> P2
    FITNESS --> P3
    FITNESS --> P4
    FITNESS --> P5
    FITNESS --> P6
    FITNESS --> P7

1. Membership & Subscription Lifecycle Engine

The domain models every membership as a formal agreement with a defined lifecycle: activation, recurring billing cycle anchoring, plan upgrades and downgrades, renewal, expiry, and cancellation. A member holds exactly one active agreement at any moment, and every transition is guarded by contract terms such as commitment periods and cancellation notice windows.

2. Freeze & Suspension State Machine

Freezing is a first-class contractual operation, not an informal note. A freeze immediately suspends access privileges, pauses the value consumption of the membership, extends the expiry date day-for-day, and consumes quota from the member’s annual freeze allowance. Involuntary suspension for failed payments follows a separate, dunning-aware path.

3. Class Scheduling & Booking Orchestration

Group classes are scheduled as capacity-bound sessions derived from recurring templates. The booking engine enforces advance booking windows per membership tier, guarantees that confirmed bookings never exceed physical capacity, and routes overflow demand into a strictly ordered waitlist with time-boxed promotion offers.

4. Access Control & Check-in Governance

Every presentation of an access credential — QR code, RFID card, or biometric token — produces a deterministic access decision: granted or denied with an explicit reason. The decision evaluates live membership state, freeze windows, zone entitlements, peak-hour restrictions, and day pass validity, and is recorded in an immutable attendance ledger.

5. Personal Training Credit Operations

Personal training sessions are sold as pre-paid credit packages with defined validity periods. Confirming a session consumes one credit; early cancellation restores it; late cancellation or no-show forfeits it. The credit ledger is append-only, giving members and trainers a dispute-proof balance history.

6. Strike & Penalty Enforcement

Late cancellations and no-shows against booked classes accrue strikes under a configurable policy. Crossing the strike threshold within a rolling window automatically suspends booking privileges for a defined period, protecting scarce class capacity for reliable members.

7. Member Engagement & Progress Tracking

Beyond access and billing, the domain tracks workout program assignments, session completion logs, attendance streaks, and periodic body composition assessments — the retention engine that keeps members progressing toward their goals.

---

3. High-Level Inter-Domain Choreography

The Fitness bounded context acts as the operational hub of the club, collaborating with enterprise domains while fiercely guarding its membership and capacity invariants:

flowchart LR
    subgraph EnterpriseEcosystem["Obelaw Enterprise Ecosystem"]
        CRM["CRM / Member Master<br/>Identity, Contact Data, Leads, Campaigns"]
        FMS["Accounting & Billing<br/>Recurring Invoices, Payments, Dunning, Refunds"]
        NOTIFY["Notification Service<br/>SMS, Email, Push Reminders"]
        HCM["Human Capital Management<br/>Trainer Contracts & Payroll"]
        GATE["Access Hardware Vendor<br/>Turnstiles, QR Scanners, Biometrics"]
    end

    subgraph FitnessDomain["Fitness (GYM) Bounded Context"]
        MEM["Membership Agreements & Freezes"]
        BOOK["Class Sessions, Bookings & Waitlists"]
        ACC["Access Decisions & Attendance Ledger"]
        PT["PT Credit Packages & Sessions"]
    end

    CRM -->|Member Identity Snapshot| MEM
    MEM -->|Billable Lifecycle Facts| FMS
    FMS -->|Payment Failure Signals| MEM
    BOOK -->|Booking & Waitlist Notifications| NOTIFY
    ACC -->|Grant / Deny Decisions| GATE
    GATE -->|Credential Presentations| ACC
    BOOK -->|Check-in Verification| ACC
    PT -->|Trainer Utilization Facts| HCM
    MEM -->|Churn & Renewal Signals| CRM

Strategic Interaction Highlights

• With CRM / Member Master: The Fitness context consumes baseline member identity and contact data via an Anti-Corruption Layer, but owns membership contract state, attendance history, and engagement progress. It emits churn-risk and renewal signals back to CRM for targeted retention campaigns.
• With Accounting / Billing: When a membership activates, renews, changes plan, or cancels, the Fitness context emits verified lifecycle facts. Billing owns invoice generation, payment collection, dunning execution, and refund settlement — and reports payment failures back so the domain can suspend access.
• With Notification Service: Booking confirmations, waitlist promotion offers, class reminders, and freeze expiry warnings are published as notification requests; the notification service owns channel selection, delivery timing, and retry logic.
• With Access Hardware: Turnstiles and scanners are vendor equipment. An Anti-Corruption Layer translates raw credential scans into domain access attempts and returns grant/deny decisions, keeping hardware protocols out of the domain model.
• With HCM: Trainer session completion facts feed trainer utilization and payroll calculations, while trainer contracts and employment lifecycles remain owned by HCM.