TorbatYar/docs/beauty-business-roadmap.md

# Beauty Business Roadmap

> Future only. Completed work → [progress.md](progress.md). Immediate milestone → [next-steps.md](next-steps.md).

Commercial product: **Torbat Beauty** — independent business management software for salons, barbershops, beauty clinics, laser centers, skin-care centers, hair-treatment centers, and spa & wellness centers.

**Important:** Beauty Business and Healthcare are completely independent business modules. They share Core platform services (Tenant, Identity, Authorization, CRM, Accounting, Loyalty, Communication, Delivery, Experience/Page Builder) via API and events only — never shared documentation, phases, frontend, dashboards, permissions, navigation, or branding.

---

## Business Goals

1. Enable beauty and wellness businesses to operate appointments, staff, services, and customer relationships in a single tenant-scoped workspace.
2. Provide industry-specific booking, salon/branch management, service catalog, packages, commissions, and marketing workflows without owning platform capabilities.
3. Integrate with Torbat Loyalty, Communication, Accounting, CRM, Delivery, and Experience without duplicating their domain data.
4. Ship a dedicated frontend shell, permission tree (`beauty_business.*`), navigation, and branding separate from Healthcare and other verticals.

---

## Boundaries

### Owns

- Salons / branches / treatment rooms / stations
- Beauty service catalog (services, categories, durations, pricing shells)
- Appointment and booking lifecycle (beauty-specific rules)
- Staff profiles, schedules, skills, commission rules (beauty domain)
- Customer profiles in beauty context (refs to CRM/Loyalty where applicable)
- Packages, memberships, and session bundles (beauty commercial model)
- Beauty marketing campaigns hooks (Loyalty/Communication client-side)
- `beauty_business.*` permissions, events, audit, configuration

### Must Not Own

- Healthcare clinics, doctors, patients, medical records, prescriptions ([healthcare](module-registry.md#healthcare))
- Accounting journals / Posting Engine ([accounting](module-registry.md#accounting))
- Sales CRM aggregates ([crm](module-registry.md#crm))
- Loyalty ledger, point accounts, campaigns ([loyalty](module-registry.md#loyalty))
- Communication providers and message delivery ([communication](module-registry.md#communication))
- Delivery drivers, fleet, dispatch ([delivery](module-registry.md#delivery))
- Experience sites, pages, themes ([experience](module-registry.md#experience))
- Core tenant membership, Identity user admin ([core-platform](module-registry.md#core-platform))

See [module-boundaries.md](architecture/module-boundaries.md).

---

## Dependencies

| Dependency | Usage |
| --- | --- |
| Core Platform | Tenant, entitlement, membership context |
| Identity & Access | User refs for staff and customer portal |
| Authorization | Workspace roles + module permission catalog |
| CRM | Contact/organization refs; optional lead capture |
| Accounting | Revenue/settlement intents via Posting Engine contracts |
| Loyalty | Points, memberships, campaigns (client) |
| Communication | Appointment reminders, marketing messages (client) |
| Delivery | Product/home-service delivery intents (optional, later) |
| Experience (Torbat Pages) | Public booking pages, salon sites, widgets |
| File Storage | Media refs for portfolio, staff, service images |

Database-per-service: sole owner of `beauty_business_db`. No cross-DB FKs ([ADR-001](architecture/adr/ADR-001.md)).

---

## Roles (High-Level)

| Role | Responsibility |
| --- | --- |
| Salon Owner | Tenant beauty business admin; branches, billing settings, staff policies |
| Branch Manager | Day-to-day branch operations, schedules, inventory of stations |
| Receptionist | Booking, check-in, customer intake |
| Stylist / Therapist / Technician | Own calendar, service delivery, commission view |
| Sales / Front Desk | Packages, upsell, payment collection (refs Accounting) |
| Customer | Self-service booking, history, loyalty (portal APIs; UI in frontend) |
| Platform Admin | Cross-tenant ops (platform scope only) |

Module-specific permissions under `beauty_business.*` (detailed per phase).

---

## High-Level Entities (Planned)

| Aggregate | Purpose |
| --- | --- |
| BeautyOrganization | Top-level beauty business entity (salon group / clinic chain) |
| BeautyBranch | Physical location (salon, barbershop, clinic branch, spa) |
| TreatmentRoom / Station | Bookable physical resources |
| BeautyRole / BeautyPermission | Module RBAC shells |
| ServiceCategory / BeautyService | Catalog: cuts, color, laser, facial, spa packages |
| ServiceVariant | Duration, price tier, staff skill requirements |
| StaffProfile | Beauty staff linked to Identity user ref |
| StaffSchedule / StaffAvailability | Working hours and exceptions |
| CustomerProfile | Beauty customer context (CRM contact ref) |
| Appointment | Booking lifecycle (requested → confirmed → checked-in → completed / cancelled / no-show) |
| AppointmentType | Consultation, service, package session, follow-up |
| WaitingListEntry | Queue when slots full |
| PackageDefinition / CustomerPackage | Prepaid multi-session bundles |
| MembershipPlan / CustomerMembership | Recurring beauty memberships |
| CommissionRule / CommissionEntry | Staff compensation shells |
| MarketingCampaignRef | Hooks to Loyalty/Communication (refs only) |
| BeautyConfiguration / BeautySetting | Tenant/module settings |
| BeautyAuditLog | Immutable audit trail |
| OutboxEvent | Publish-only domain events |

Exact entity names and tables are defined at implementation time per [phase-template.md](ai-framework/phase-template.md).

---

## Integration Points

| Platform | Integration pattern |
| --- | --- |
| CRM | `contact_ref` / `organization_ref` on CustomerProfile; optional opportunity on high-value packages |
| Loyalty | Earn/redeem on completed appointments; membership tier sync via API |
| Communication | Template-based reminders (confirm, reschedule, no-show, birthday) |
| Accounting | Invoice/payment intents on completed services; commission accrual intents |
| Experience | Embeddable booking widget; public service menu pages |
| Delivery | Optional product shipment for retail beauty products (job intents to Delivery) |
| Identity | Staff and customer user refs only |

All integrations: REST + async events + outbox; provider contracts in owning service; no foreign model imports.

---

## Phase Plan

| Phase | Identifier | Title | Summary |
| --- | --- | --- | --- |
| 14.0 | `beauty-business-14-0` | Beauty Foundation | Service scaffold, org/branch/roles, configuration, audit, health/capabilities |
| 14.1 | `beauty-business-14-1` | Booking Engine | Schedules, availability, appointments, waiting list |
| 14.2 | `beauty-business-14-2` | Salon Management | Branches, rooms/stations, branch policies, operational settings |
| 14.3 | `beauty-business-14-3` | Service Catalog | Categories, services, variants, pricing shells, media refs |
| 14.4 | `beauty-business-14-4` | Customer Management | Customer profiles, preferences, visit history shells, CRM refs |
| 14.5 | `beauty-business-14-5` | Package & Membership | Prepaid packages, session balances, recurring memberships |
| 14.6 | `beauty-business-14-6` | Staff & Commission | Staff profiles, skills, schedules, commission rules and entries |
| 14.7 | `beauty-business-14-7` | Marketing & Loyalty | Campaign refs, referral hooks, Loyalty/Communication connectors |

Phase documents: [phases/BeautyBusiness/](phases/BeautyBusiness/README.md).

Implementation of every phase must follow the [Enterprise / AI Development Framework](ai-framework/README.md) ([ADR-013](architecture/adr/ADR-013.md), [ADR-018](architecture/adr/ADR-018.md), [ADR-019](architecture/adr/ADR-019.md)).

---

## Future Roadmap (Post 14.7)

Not registered as phases yet; track here only:

- Retail product inventory and POS-lite for beauty retail
- Advanced analytics and revenue dashboards
- Multi-branch franchise reporting
- AI-assisted scheduling and demand forecasting
- Mobile stylist app and customer app deep links
- Integration marketplace (payment gateways, review platforms)
- Enterprise validation and compliance slice (14.8+ when scoped)

---

## Technical Registration (Planned)

| Field | Value |
| --- | --- |
| Service folder | `backend/services/beauty_business` (at 14.0) |
| Database | `beauty_business_db` |
| API port | **8011** (reserved) |
| API prefix | `/api/v1` |
| Permission prefix | `beauty_business.*` |
| Event prefix | `beauty_business.*` |
| Frontend route prefix | `/beauty` (dedicated shell; separate from `/healthcare`) |

---

## Documentation References

- [Phase area README](phases/BeautyBusiness/README.md)
- [Module registry — beauty_business](module-registry.md#beauty_business)
- [Module boundaries](architecture/module-boundaries.md)
- [Multi-tenant architecture](architecture/multi-tenant-architecture.md)
- [Service architecture](architecture/service-architecture.md)
- [AI Development Framework](ai-framework/README.md)
- [Healthcare roadmap](healthcare-roadmap.md) (sibling module — do not merge)

---

## Related Documents

- [Progress](progress.md)
- [Next Steps](next-steps.md)
- [Roadmap](roadmap.md)
- [Module Registry](module-registry.md)