# Phase: Beauty Business Foundation

| Field | Value |
| --- | --- |
| Identifier | `beauty-business-14-0` |
| Status | Planned |
| Owner | Platform |
| Module(s) | `beauty_business.*` foundation |
| Service(s) | `beauty_business` (new independent service) |
| Depends On | Core Platform, Identity (JWT), shared-lib patterns |
| ADR(s) | TBD at implementation (Independent Beauty Business Platform) |
| Manifest | [phase-manifest.yaml](../../ai-framework/phase-manifest.yaml) |
| Framework | [ADR-013](../../architecture/adr/ADR-013.md) · [ADR-018](../../architecture/adr/ADR-018.md) · [ADR-019](../../architecture/adr/ADR-019.md) |

## Objective

Establish the independent Beauty Business platform (`Torbat Beauty`): service scaffold, database ownership, tenant-scoped foundation aggregates, permission catalog shells, configuration/settings, audit, health/capabilities/metrics, and publish-only event infrastructure — without booking, catalog, customer, package, commission, or marketing engines.

## Enterprise Phase Discovery

> **Required before Implementation.** Full Discovery Record per [enterprise-phase-discovery.md](../../ai-framework/enterprise-phase-discovery.md).

| Field | Value |
| --- | --- |
| Discovery date | Pending (at implementation) |
| Inputs reviewed | [beauty-business-roadmap.md](../../beauty-business-roadmap.md) · [module-boundaries.md](../../architecture/module-boundaries.md) · [module-registry.md](../../module-registry.md) · Prior platform service patterns |

### Baseline Inventory (exists today)

- BB-Reg documentation and architecture registration complete
- No `backend/services/beauty_business` code
- Port **8011** and `beauty_business_db` reserved in registry

### Target Responsibility (this phase when Complete)

- Independent FastAPI service with Alembic, tenant middleware, outbox publisher
- Foundation aggregates: organization, branch shells, roles/permissions, external provider config shells, configuration, settings, audit
- `/health`, `/capabilities`, `/metrics`; permission prefix `beauty_business.*`
- Provider **contracts only** (CRM, Loyalty, Communication, Accounting, Experience, Delivery, Storage, AI)

### Gap Analysis

| Capability | Status | Action |
| --- | --- | --- |
| Service scaffold | Missing | Implement at 14.0 |
| Foundation aggregates | Missing | Implement at 14.0 |
| Booking / catalog / customer engines | Out of scope | Phase 14.1+ |
| Healthcare overlap | N/A | Separate module — no shared tables |

### Promoted to Implementation Scope

- Service + DB + migrations + foundation CRUD shells
- Architecture, tenant, permission, migration, docs tests

### Explicitly Excluded (future phase or other service)

- Appointments, services catalog, customers, packages, commissions, marketing
- Healthcare clinical entities
- Frontend UI (separate frontend phase/track)
- Real provider SDK calls

### Boundary Confirmations

- [x] No future-phase pull-forward (documentation scope)
- [x] No service-boundary violation vs Healthcare
- [x] No duplication of CRM/Loyalty/Communication ownership
- [x] CRUD-only delivery rejected at implementation (must include audit, events, capabilities)

## Business Analysis

| Item | Detail |
| --- | --- |
| Actors | Salon owner, platform admin |
| Business capabilities (in phase) | Register beauty business org structure; configure module; RBAC shells |
| Success metrics | Service boots; tenant isolation proven; capabilities discoverable |
| Non-goals | End-user booking; clinical workflows |

## Scope

### In Scope

- `backend/services/beauty_business` scaffold mirroring platform conventions
- Database `beauty_business_db`; compose port **8011**
- Foundation models and APIs for organizations, branches, roles, permissions catalog, configuration, settings, external provider registrations, audit
- Transactional outbox; publish-only events `beauty_business.organization.*`, `beauty_business.branch.*`, etc.
- Permissions `beauty_business.*` trees

### Modules

| Module | Change type | Notes |
| --- | --- | --- |
| `beauty_business.organizations` | new | Salon group / clinic chain |
| `beauty_business.branches` | new | Location shells |
| `beauty_business.roles` | new | Module RBAC |
| `beauty_business.permissions_catalog` | new | Permission discovery |
| `beauty_business.configuration` | new | Tenant config |
| `beauty_business.settings` | new | Key-value settings |
| `beauty_business.external_providers` | new | Adapter registration shells |
| `beauty_business.audit` | new | Audit log |

### Domain Model

| Aggregate | Entities | Invariants |
| --- | --- | --- |
| BeautyOrganization | Organization | Tenant-scoped; soft delete |
| BeautyBranch | Branch | Belongs to organization; tenant-scoped |
| BeautyRole | Role, Permission | Module-local RBAC shells |

### High-Level Entities (Planned at Implementation)

| Entity | Soft delete | Audit | Tenant | Notes |
| --- | --- | --- | --- | --- |
| BeautyOrganization | Yes | Yes | Yes | Top-level beauty business |
| BeautyBranch | Yes | Yes | Yes | Salon / clinic location |
| BeautyRole | Yes | Yes | Yes | Staff role definitions |
| BeautyPermission | No | Yes | Yes | Permission catalog entries |
| ExternalProviderConfig | Yes | Yes | Yes | Adapter refs |
| BeautyConfiguration | Yes | Yes | Yes | Module configuration |
| BeautySetting | Yes | Yes | Yes | Settings |
| BeautyAuditLog | No | N/A | Yes | Append-only |
| OutboxEvent | No | N/A | Yes | Event publishing |

## Out of Scope

- Booking engine (14.1)
- Rooms/stations operational management (14.2)
- Service catalog (14.3)
- Customer profiles (14.4)
- Packages and memberships (14.5)
- Staff commission (14.6)
- Marketing and Loyalty integration (14.7)
- Healthcare module entities or APIs
- Frontend dashboards and navigation

## Completion Criteria

- [ ] Objective met
- [ ] Enterprise Phase Discovery Record complete at implementation
- [ ] Definition of Done satisfied
- [ ] Tests green (architecture, API, tenant, permissions, migration, docs)
- [ ] Module registry, progress, handover updated
- [ ] No booking/catalog/customer engines in 14.0

## Architecture Impact

- New independent service and database per [service-architecture.md](../../architecture/service-architecture.md)
- Module boundary entry for Beauty Business Platform in [module-boundaries.md](../../architecture/module-boundaries.md) (at implementation)
- Reserved port 8011; no impact on Healthcare (8010)

## Database Impact

- New database `beauty_business_db`
- Migration `0001_initial` (at implementation)

## Risks

- Confusion with Healthcare scheduling — mitigated by separate module keys, permissions, and documentation
- Pull-forward of booking into foundation — mitigated by explicit Out of Scope

## Related Documents

- [Beauty Business Roadmap](../../beauty-business-roadmap.md)
- [Phase area README](README.md)
- [Module registry — beauty_business](../../module-registry.md#beauty_business)
- [Healthcare roadmap](../../healthcare-roadmap.md) (sibling — do not merge)
- [AI Framework](../../ai-framework/README.md)