TorbatYar/docs/progress.md
Mortezakoohjani d579d0b142 feat(loyalty): add Loyalty Platform Frontend module
Add frontend/modules/loyalty with types, API client, design system, feature pages and thin App Router routes under app/loyalty/. BFF proxy at app/api/loyalty/. Include loyalty frontend docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-27 10:50:55 +03:30

59 KiB
Raw Permalink Blame History

Progress

Completed work only. Future → roadmap.md. Next milestone → next-steps.md.

Phase 1 — Core Platform

Infrastructure & structure

  • Full project structure with mandatory backend/ / frontend/ separation
  • Shared library backend/shared-lib
  • Architecture section: Frontend & Backend Separation

Core service

  • Config, database, cache, logging, base security
  • Models, APIs, Entitlement, Celery, Outbox
  • Tests and documentation

Frontend

  • Independent Next.js, API client, white-label theme baseline

Phase 2 — Identity & Access + SSO

  • shared/auth/jwt.py, shared/auth/roles.py, Identity events in shared/events.py
  • Identity service + identity_access_db
  • Keycloak realm/clients/theme import
  • Core API protection (AUTH_REQUIRED, role deps)
  • Frontend SSO flow (/login, /auth/callback, /dashboard)
  • Compose services Identity + Frontend; Postgres init for identity DB

Phase 3 — OTP Login + Tenant Management

  • Core users + OTP request/verify + Payamak
  • Local JWT (HS256) for OTP users
  • Admin tenant CRUD + owner filtering
  • Frontend admin OTP/tenant UI (later aligned to central SSO)
  • test_otp_auth.py

Phase 4 — Tenant Onboarding & Workspace Activation

Brief alias: sometimes called “Phase 3” externally — see phase-numbering decision.

  • Core tenant_memberships, tenant lifecycle, branding columns, domain primary/verification fields
  • users.current_tenant_id, FREE/STARTER plan seed, onboarding APIs
  • UserService / MembershipService / OnboardingService / TenantContextService
  • Frontend onboarding wizard, tenant dashboard, tenant switcher
  • test_onboarding.py + regression suite
  • JIT Core user from Keycloak JWT (UserService.resolve_current)
  • Automatic tenant subdomain SSL (Celery → SSH → provision_ssl.py)
  • Reverse proxy (Nginx) + base TLS + tenant SSL automation

Intentionally incomplete after Phase 4 (tracked in roadmap, not claimed done)

Payment gateway · real DNS/TXT custom-domain verify · legacy POST /admin/tenants auto membership/plan · first business module


Phase D — Documentation Architecture Consolidation

  • Target docs/ tree (architecture, adr, development, reference, deployment, templates, phases, decisions)
  • Moved canonical docs with git history where possible
  • Deprecated stubs for old paths
  • ADR system initialized (ADR-001 … ADR-010)
  • Project principles, coding standards, testing/branching/release strategies
  • Module registry + provider registry + glossary
  • Deployment runbooks (production, SSL, monitoring, backup, restore, DR)
  • Roadmap / next-steps separation from progress
  • Phase area docs for Accounting, CRM, Restaurant, Marketplace, Automation, AI, Future
  • Cross-links updated in root and package READMEs

Phase 5.15.11 — Accounting Module

  • Phases 5.15.6: Foundation through Sales Integration (see prior entry)
  • Phase 5.7: Purchase & Inventory accounting, InventoryValuationEngine
  • Phase 5.8: Fixed Assets, DepreciationEngine, asset lifecycle
  • Phase 5.9: HCM/Payroll, PayrollEngine, payroll accounting
  • Phase 5.10: Financial Reporting Engine, dashboards, export framework
  • Phase 5.11: Compliance, Audit Framework, Governance, SoD
  • Alembic migration 0002_phases_57_511
  • 21 tests passing

Accounting Enterprise Frontend (in SuperApp) baseline

  • Design system tokens (light/dark) + DS components (components/ds)
  • TanStack Query providers, Sonner toasts, ColorMode
  • Typed accounting-api client (JWT + X-Tenant-ID, no mocks)
  • Accounting shell + routes: dashboard, COA, fiscal, currencies, cost centers, projects, ledger, setup, suppliers
  • Vouchers list/create/detail with validate/post/reverse/cancel + draft edit (ADR-010)
  • Foundation masters: edit/archive drawers, fiscal year/period actions, COA template import wizard
  • Setup checklist + completion scoreboard on dashboard
  • Treasury, customers, assets, payroll, reports, audit, settings pages (real APIs)
  • Catalog tile available → /accounting
  • Frontend docs under docs/frontend/

Remaining: Phase 5.12 AI UI blocked on AI provider; optional richer PDF export file delivery.


Accounting Frontend Integration (FE ↔ BE 5.15.11)

  • Full route/menu scan vs /api/v1 routers; gap matrix executed
  • Domain rewires: payroll employees, compliance policies/risks, settlements, sales-accounting post, purchase GR + valuation, asset schedule, monitoring health
  • FE client: settlements, salesAccounting, purchaseInventory, compliance approvals/risks, ops PATCH
  • Ops documents: detail + edit; treasury receipt/payment cash/bank binding; voucher list pagination
  • BE list endpoints for settlements, risks, purchase posting-profiles (integration completeness)
  • Report: accounting-frontend-integration-report.md
  • Scoreboard honesty for partial/ops-backed modules; AI remains blocked

Accounting Frontend Completion Loop (business workflows)

  • Full sidebar/submenu audit (118 routes); generic BusinessDocs stubs replaced
  • Thin BE APIs on existing models: asset transfer/dispose/revaluation; payroll contracts/components/payrolls; compliance workflows/approvals list/SoD/controls/violations
  • Domain screens: WorkflowScreens.tsx + typed SpecializedOpsPage for budget/integration/documents/settings
  • Money thousand-separators + party/item AJAX across operational forms
  • Audit report: audits/accounting-frontend-completion-report.md
  • Menu QA tracker: frontend/accounting-menu-qa.md

Remaining (honest): Phase 5.12 AI blocked; budget/DMS/integration still typed-ops interim until dedicated engines exist.


Phase 6.0 — CRM Service Foundation

  • backend/services/crm service scaffold (API / services / repositories / models)
  • Base aggregates: Lead, Contact, Organization, Opportunity, Pipeline, PipelineStage, SalesActivity, Quote
  • Publish-only event contracts (crm.lead.*, crm.opportunity.*, …)
  • CRM APIs only (/api/v1/leads|contacts|organizations|pipelines|opportunities|activities|quotes)
  • Platform provider contracts only (Automation, Customer360, Notification, Analytics, AI, Communication, Helpdesk)
  • Permissions crm.* trees; tenant isolation via X-Tenant-ID
  • Alembic 0001_initial + crm_db wiring (compose port 8003)
  • Architecture / dependency / repository / migration / API / permission / tenant / docs tests
  • Docs: crm-phase-6-0.md, module registry, phase area README

Phase 6.1 — Enterprise CRM Core Business Entities

  • Expanded Lead / Contact / Organization (numbers, multi-contact, soft delete, audit actors)
  • Lookups: lead_sources, lead_statuses, contact_types, organization_types, organization_industries
  • Lead assignments, tag engine, reusable addresses, custom fields + values
  • Versioned notes, attachment file-storage references (no binary), CRM audit log
  • Services / repositories / validators / permissions / events for Phase 6.1
  • Alembic 0002_phase_61_entities
  • API coverage under /api/v1 for entities + lookups
  • Tests: model, repository, service, API, permission, migration, validation, audit, tenant, docs
  • Docs: crm-phase-6-1.md

Phase 6.2 — Enterprise Sales Process Engine

  • Opportunity engine (number, title, revenue, probability, priority, close dates, soft delete, actors)
  • Unlimited pipelines + pipeline stages (start/won/lost/closed flags, required fields, exit validation)
  • Stage history, opportunity products (product_ref only), contact roles, competitors
  • Sales playbooks (versioned) + steps + assignments + completion tracking
  • Win/loss categories, reasons, immutable opportunity_win_loss snapshot
  • Rule-based forecasts (pipeline / weighted / committed; monthly/quarterly/annual)
  • Sales goals + targets with achievement %
  • Sales process definitions + sales_audit trail
  • Services / validators / events / permissions (crm.pipelines|playbooks|forecasts|goals|targets.*)
  • Alembic 0003_phase_62_sales_engine; version 0.6.2.0
  • API coverage for sales engine under /api/v1
  • Tests: pipeline, stage, playbook, forecast, win/loss, business rules, migration, permission, tenant, docs
  • Docs: crm-phase-6-2.md

Phase 6.3 — Enterprise Sales Collaboration Platform

  • Expanded sales activities (types, priority, CRM entity links, participants, reminders)
  • Tasks + checklists + completion tracking
  • Meetings + attendees + finish/outcome
  • Call logs (opportunity-linked) + call outcomes
  • Email threads/messages metadata only (no delivery)
  • Immutable sales timeline + timeline event links
  • Threaded/versioned comments, mentions, bookmarks, favorites
  • Sales team roles/members/assignments + notification preferences
  • Collaboration audit; events crm.task|meeting|call|timeline|comment|mention.*
  • Permissions crm.tasks|meetings|calls|timeline|comments|mentions|team.*
  • Alembic 0004_phase_63_collaboration; version 0.6.3.0
  • Tests + docs: crm-phase-6-3.md

CRM Core Platform

  • Phases 6.06.3 complete (Foundation, Master Data, Sales Engine, Collaboration)

Phase 7.0 — Loyalty Service Foundation

  • backend/services/loyalty service scaffold (API / services / repositories / models)
  • Foundation aggregates: LoyaltyProgram, MembershipTier, Member, PointAccount, Reward, Campaign, LoyaltyAuditLog, OutboxEvent
  • No mutable balance on PointAccount — direct balance mutation forbidden (extra=forbid)
  • Optimistic locking on Program / Member / PointAccount; campaign rule_version
  • Publish-only events via transactional outbox (loyalty.program|tier|member|point_account|reward|campaign.*)
  • Loyalty APIs only (/api/v1/programs|tiers|members|point-accounts|rewards|campaigns|audit)
  • Platform provider contracts only (Notification, Analytics, Customer360, AI, ModuleIntegration, CRM, Communication, FileStorage)
  • Permissions loyalty.* trees with manage/view inheritance; tenant isolation via X-Tenant-ID
  • Alembic 0001_initial + loyalty_db wiring (compose port 8004)
  • Soft-delete unique reclaim; IntegrityError → 409; null required-field → 422; production config guards
  • Enterprise validation & self-heal (incl. removal of incomplete 7.1 residue) — 52 tests passed
  • Docs: loyalty-phase-7-0.md, loyalty-phase-7-0-audit.md, ADR-011, module registry, phase area README

Phase 7.1 — Membership Engine

  • Lifecycle state machine (activate / renew / freeze / resume / cancel / expire / transfer)
  • Member lifecycle fields + MembershipLifecycleEvent append-only history
  • Program soft-delete cascade policy: reject when blocking members exist
  • Permissions loyalty.members.{activate,renew,freeze,resume,cancel,expire,transfer,lifecycle.view}
  • Events loyalty.member.{activated,renewed,frozen,resumed,cancelled,expired,transferred}
  • Alembic 0002_phase_71_membership; version 0.7.1.0
  • Tests green (59) including test_phase71.py
  • Docs: loyalty-phase-7-1.md, phase-handover/phase-7-1.md, manifests, registry

Phase 7.2 — Point Engine

  • Immutable PointLedgerEntry append-only ledger; balance = SUM(signed amounts)
  • No mutable balance on PointAccount
  • Earn / redeem / adjust / expire APIs with idempotency + insufficient-balance checks
  • Permissions loyalty.points.{view,earn,redeem,adjust,expire,manage}
  • Events loyalty.points.{earned,redeemed,adjusted,expired}
  • Alembic 0003_phase_72_points; version 0.7.2.0
  • Tests green (61) including test_phase72.py
  • Docs: loyalty-phase-7-2.md, phase-handover/phase-7-2.md, service-snapshots/loyalty.yaml, manifests, registry

Phase 7.3 — Rewards Engine

  • Reward inventory fields + RewardRedemption lifecycle (pending/fulfilled/cancelled)
  • Redeem / fulfill / cancel; points via PointEngine only (auto_commit composition)
  • Permissions loyalty.rewards.{redeem,fulfill,cancel}, loyalty.redemptions.view
  • Events loyalty.reward.{redeemed,fulfilled,redemption_cancelled}
  • Alembic 0004_phase_73_rewards; version 0.7.3.0
  • Tests green (72) including test_phase73.py
  • Docs: loyalty-phase-7-3.md, phase-handover/phase-7-3.md, snapshot, manifests

Phase 7.4 — Campaign Engine

Phase 7.5 — Referral Engine

Phase 7.6 — Wallet

  • WalletAccount shell + immutable WalletLedgerEntry (no mutable balance)
  • Credit / debit / adjust / transfer APIs with idempotency + insufficient-funds checks
  • Permissions loyalty.wallets.{view,create,credit,debit,adjust,transfer,delete,manage}
  • Events loyalty.wallet.{opened,credited,debited,adjusted,transferred,closed}
  • Alembic 0007_phase_76_wallet; version 0.7.6.0
  • Tests green (114) including test_phase76.py
  • Docs: loyalty-phase-7-6.md, phase-handover/phase-7-6.md, snapshot, manifests

Phase 8.08.10 — Enterprise Communication Platform (Production Ready — SMS MVP)

  • Independent communication-service / communication_db (port 8005) — not owned by CRM/Loyalty/Restaurant
  • Provider framework + registry (mock, payamak; stubs for email/push/whatsapp/telegram/rubika/voice)
  • Communication router with priority, automatic failover, retry, circuit breaker
  • SMS platform: sender numbers, balance, rate limits, provider logs
  • Template engine: variables, locale, versioning, approval, preview, rendering
  • Dynamic contact sources (manual, CSV, CRM/Loyalty/Restaurant/Marketplace/Accounting/Website/External REST) — resolve only, no duplication
  • Queue engine: async queue, scheduling, priority, backoff retry, DLQ, batch
  • Delivery tracking: queued/sent/delivered/failed/expired/cancelled + timeline
  • OTP platform: generate/verify/expire, rate limit, brute-force lock, multi-channel path
  • Incoming provider webhooks with signature verification
  • Health /health, Capability /capabilities, providers status, monitoring stats
  • Permissions communication.*; events communication.*; audit on every send
  • Alembic 0001_initial, 0002_validation_hardening; version 0.8.10.1
  • Tests: architecture, health/security, providers/SMS/failover/queue, templates/contacts/OTP/webhooks, validators (42 passing)
  • Production Ready (SMS MVP) — feature-complete for current scope; future channels in communication-roadmap.md only
  • Docs: communication-phase-8.md, phase-handover/phase-8.md, service-snapshots/communication.yaml, ADR-012, module/provider registry, progress
  • Frontend: frontend/modules/communication/ — SMS connected; future modules Feature Lock (frontend/docs/communication-frontend-architecture.md)

Phase AF — AI Development Framework

Documentation-only. No business functionality. No modifications to existing services, schemas, or APIs.

  • Permanent area docs/ai-framework/
  • Master prompt, development loop, phase handover, quality gates
  • Templates: phase, service, module, entity, repository, service-layer, API, event, testing, documentation
  • Manifests: phase-manifest.yaml, service-manifest.yaml
  • Prompt rules + Cursor guidelines
  • Docs index / module registry / progress integration
  • ADR-013 Accepted
  • Architecture, documentation, cross-reference, link, template, and manifest validation

Phase AF-Enterprise — Enterprise Development Framework Upgrade

Documentation-only. Upgrades the AI Development Framework into an Enterprise Development Framework. No business feature code. No changes to completed business phases or implementations.


Phase AF-Discovery — Enterprise Phase Discovery Mandate

Documentation-only. Adds mandatory Enterprise Phase Discovery before every phase. No business feature code. No changes to completed business phases or implementations.


Phase SC-Reg — Sports Center Platform Registration

Documentation-only registration. No business code, models, APIs, migrations, or repositories.


Phase 9.0 — Sports Center Platform Foundation

  • backend/services/sports_center service scaffold (API / services / repositories / models)
  • Foundation aggregates: SportsCenter, Branch, Sport, MembershipType, Membership, Coach, SportsRole, SportsPermission, Facility, Court, Room, LockerRoom, Locker, DeviceProvider, Device, AttendanceGateway, SportsConfiguration, SportsEvent, SportsSetting, SportsAuditLog
  • Adapter-based connector framework (QR/RFID/Barcode/Fingerprint/Face/Turnstile/Door/Payment/Attendance) — interfaces only
  • Platform provider contracts only (Accounting, CRM, Loyalty, Communication, Notification, Storage, AI, Identity, Customer360)
  • Publish-only events (sports_center.member|membership|coach|facility|device|attendance|locker.*)
  • Sports APIs under /api/v1 + device connect/disconnect + locker assign/release
  • Permissions sports_center.* trees; tenant isolation via X-Tenant-ID
  • Alembic 0001_initial + sports_center_db wiring (compose port 8006)
  • Architecture / API / permissions / migration / dependency / connectors / docs tests
  • Docs: sports-center-phase-9-0.md, phase-handover/phase-9-0.md, ADR-014, module registry
  • No business workflow engines (booking/attendance lifecycle deferred)

Phase 9.1 — Sports Center Membership Catalog

  • Catalog aggregates: SportCategory, AgeGroup, PricingModel, MembershipPackage, MembershipPlan, MembershipRule, RenewalPolicy, FreezingRule, ExpirationPolicy
  • MembershipType extended with catalog refs (package/plan/pricing/age/category/policies), transferability, sort order
  • Validators for age range, pricing/billing/rule kinds, money amounts, catalog ref integrity
  • Publish-only catalog events; permissions trees for catalog modules
  • APIs under /api/v1/sport-categories|age-groups|pricing-models|membership-packages|membership-plans|membership-rules|renewal-policies|freezing-rules|expiration-policies
  • /capabilities endpoint; version 0.9.1.0
  • Alembic 0002_phase_91_membership_catalog
  • Tests: catalog API, tenant isolation, age validation, architecture, docs
  • Docs: sports-center-phase-9-1.md, phase-handover/phase-9-1.md
  • No member enrollment / coach / attendance / booking engines

Phase 9.2 — Sports Center Member Management

  • Members aggregate + family members, emergency contacts, medical information shells
  • Membership assignment (member_id) consuming Phase 9.1 catalog types
  • Status management: activate / suspend / cancel / freeze / unfreeze
  • Membership cards (QR/physical/digital), digital membership passes, waivers (sign), member documents (Storage refs)
  • Validators, permissions (sports_center.members.* trees), publish-only events
  • Alembic 0003_phase_92_member_management; version 0.9.2.0
  • Tests: members API, tenant isolation, transitions, architecture, migration, docs
  • Docs: sports-center-phase-9-2.md, phase-handover/phase-9-2.md
  • No coach / attendance / booking engines

Phase 9.3 — Sports Center Coach & Staff Management

  • Extended Coach profile (staff_kind, bio, hire_date, payroll refs)
  • Staff certificates, skills, working hours, availability, assignments
  • Alembic 0004_phase_93_coach_staff; version 0.9.3.0
  • Docs + handover phase-9-3.md

Phase 9.4 — Sports Center Scheduling & Booking

  • Sessions, bookings, waiting list, equipment, resource reservations
  • Capacity checks and session/resource conflict detection
  • Alembic 0005_phase_94_booking; version 0.9.4.0; booking_engine: true

Phase 9.5 — Sports Center Attendance & Access Control

  • Attendance records, access logs, check-in/check-out with membership validation
  • Alembic 0006_phase_95_attendance; version 0.9.5.0; attendance_engine: true

Phase 9.6 — Sports Center Training Management

  • Training programs, exercises, workout plans/assignments, goals, measurements, progress, nutrition, assessments, performance, body composition
  • Alembic 0007_phase_96_training; version 0.9.6.0; training_management: true
  • Docs + handover phase-9-6.md

Phase 9.7 — Sports Center Competition & Event Management

  • Competitions, teams, groups, registrations, matches, results, rankings, medals, judges, certificates
  • Alembic 0008_phase_97_competitions; version 0.9.7.0; competition_management: true
  • Docs + handover phase-9-7.md

Phase DP-Reg — Delivery & Fleet Platform Registration

Documentation-only registration. No business code, models, APIs, migrations, or repositories.


Phase XP-Reg — Experience Platform Registration

Documentation-only registration. No business code, models, APIs, migrations, or repositories.


Phase 11.0 — Experience Platform Foundation

  • Independent backend/services/experience (experience_db, port 8008, version 0.11.0.0, commercial product Torbat Pages)
  • Foundation aggregates: Workspace, LocaleProfile, ExternalProviderConfig, RenderEngineRegistration, Configuration, Setting, Role/Permission shells, AuditLog
  • GET /health, /capabilities, /metrics; permissions experience.*; publish-only events
  • Provider contracts only (Storage, CRM, Hospitality, Marketplace, Sports, Delivery, Communication, Loyalty, Accounting, AI, Automation, …)
  • Alembic 0001_initial; compose + .env.example + init-dbs.sql wiring
  • Tests: architecture, API, tenant isolation, permissions, migration, dependency, security, docs
  • Docs: experience-phase-11-0.md, phase-handover/phase-11-0.md
  • No sites/pages/page-builder/theme/template/CMS/forms engines

Phase 11.1 — Experience Sites & Page Resources

  • Sites under workspaces (multiple sites); draft/publish/archive lifecycle
  • Pages-as-resources with page types (landing, menu, bio, portfolio, QR, blog, …)
  • Site domain/subdomain binding refs (experience_site_domains)
  • Permissions experience.sites.* / experience.pages.* / experience.domains.*
  • Events experience.site.* / experience.page.* / experience.site_domain.*
  • Alembic 0002_phase_111_sites_pages; version 0.11.1.0
  • Tests: sites API, tenant isolation, publish/archive rules, architecture, migration, docs
  • Docs: experience-phase-11-1.md, phase-handover/phase-11-1.md
  • No page builder / theme / template engines

Phase 11.2 — Experience Component Library & Versioning

  • Versioned component catalog (ExperienceComponent) with kinds + lifecycle
  • Immutable published component versions (ExperienceComponentVersion)
  • Page composition shells (PageComponentPlacement slot pins)
  • Policies, specifications, commands, queries; list filter/sort/search
  • Permissions experience.components.*; events experience.component* / experience.page_component.*
  • Alembic 0003_phase_112_components; version 0.11.2.0
  • Tests: policies, API flow, immutability, tenant isolation, architecture, migration, docs
  • Docs: experience-phase-11-2.md, phase-handover/phase-11-2.md
  • No theme / layout engines

Phase 11.3 — Experience Theme & Layout Engine

  • Replaceable theme packs (ExperienceTheme) with tokens + directionality
  • Dynamic layouts (ExperienceLayout) with regions/slots shells
  • Site theme + page layout assignments (swap without rewriting pages)
  • Policies, specifications, commands, queries; list filter/sort/search
  • Permissions experience.themes.* / experience.layouts.*
  • Events experience.theme.* / experience.layout.* / experience.site_theme.* / experience.page_layout.*
  • Alembic 0004_phase_113_themes_layouts; version 0.11.3.0
  • Tests: policies, API flow, tenant isolation, architecture, migration, docs
  • Docs: experience-phase-11-3.md, phase-handover/phase-11-3.md
  • No template catalog engine

Phase 11.4 — Experience Template System

  • Template catalog (ExperienceTemplate) — code, name, page_type, category, tags, starter-pack flag
  • Immutable published template versions (ExperienceTemplateVersion) with blueprint_json
  • Template instantiation (TemplateInstantiation) — audit trail from a published version to a created page
  • Lifecycle: draft → active → deprecated/archived; version draft → published (immutable) → retired
  • Policies, specifications, commands, queries; list filter/sort/search
  • Permissions experience.templates.* (full CRUD tree)
  • Events experience.template.* / experience.template_version.* / experience.template.instantiated
  • Alembic 0005_phase_114_templates; version 0.11.4.0
  • Tests: health, full lifecycle + instantiation flow, tenant isolation, immutable version update blocked, architecture, migration, permissions, docs
  • Docs: experience-phase-11-4.md, phase-handover/phase-11-4.md
  • No forms / surveys / locales / media / SEO engines

Phase 11.5 — Experience Localization, RTL/LTR & Media

  • Site locale bindings (SiteLocaleBinding) — locale profile + concrete RTL/LTR + default flag
  • Localization shells (ExperienceLocalization) — target/locale upsert with directionality
  • Media refs (ExperienceMediaRef) — storage_file_ref only; reject data-URI / binary metadata
  • Policies, specifications, commands, queries; list filter/sort/search
  • Permissions experience.locales.* / experience.media_refs.*
  • Events experience.site_locale.* / experience.localization.* / experience.media_ref.*
  • Alembic 0006_phase_115_localization_media; version 0.11.5.0
  • Tests: health, binding + localization lifecycle, media isolation, architecture, migration, permissions, docs
  • Docs: experience-phase-11-5.md, phase-handover/phase-11-5.md
  • No forms / surveys / appointments / SEO engines

Phase 11.6 — Experience Forms, Surveys & Appointments

  • Forms + form submissions (payload + CRM/Communication refs only)
  • Surveys + survey responses
  • Appointment pages + external booking refs (no scheduler ownership)
  • Policies/validators reject inactive intake and ownership JSON keys
  • Permissions experience.forms.* / experience.surveys.* / experience.appointments.*
  • Events for form/survey/appointment + submission/response/booking-ref lifecycle
  • Alembic 0007_phase_116_forms_surveys_appointments; version 0.11.6.0
  • Tests: health, form/submission, survey/appointment booking refs, architecture, migration, docs
  • Docs: experience-phase-11-6.md, phase-handover/phase-11-6.md
  • No SEO/PWA engines

Phase 11.7 — Experience Publishing, Domains, SEO & PWA

  • Publish releases and domain edge binding references
  • SEO metadata, sitemap and robots shells, and PWA manifests
  • Permissions experience.publishing.*, experience.seo.*, experience.pwa.*
  • Publish-only lifecycle events and optimistic versioning
  • Alembic 0008_phase_117_publishing_seo_pwa; version 0.11.7.0
  • DNS/SSL/edge/storage ownership remains external; PEM/private keys rejected
  • Docs: experience-phase-11-7.md, phase-handover/phase-11-7.md

Phase 11.8 — Experience Bundles, Licensing & Feature Toggles

  • Bundle definitions, tenant bundle assignments, Core entitlement refs, and feature toggles
  • Filtered/paginated CRUD APIs, audit, optimistic locking, soft delete, tenant isolation
  • Permissions experience.bundles.* and experience.feature_toggles.*; lifecycle events
  • Alembic 0009_phase_118_bundles_toggles; version 0.11.8.0
  • Core retains plan/subscription/billing ownership; forbidden ownership metadata rejected
  • Docs: experience-phase-11-8.md, phase-handover/phase-11-8.md

Phase 11.9 — Experience Consumer Integrations & Widgets

  • Consumer connector registrations/dispatches, widget definitions/instances, notify dispatches
  • Mock providers for connector execute and notify send; forbidden ownership keys rejected
  • Filtered/paginated CRUD APIs, execute/send actions, audit, optimistic locking, soft delete
  • Permissions experience.consumer_connectors.*, experience.widgets.*, experience.notify.*
  • Alembic 0010_phase_119_consumer_widgets; version 0.11.9.0
  • Docs: experience-phase-11-9.md, phase-handover/phase-11-9.md

Phase 11.10 — Experience Analytics, AI Content & Enterprise Validation

  • Analytics report definitions + snapshots (local COUNT on experience_db only)
  • AI content hook registrations + dispatches via MockAIProvider.generate_content
  • Forbidden ownership keys in config/metadata/payload; suspended registration → generate 409
  • Permissions experience.analytics.*, experience.ai_hooks.*
  • Alembic 0011_phase_1110_analytics_ai_hooks; version 0.11.10.0
  • Enterprise validation audit + service snapshot
  • Docs: experience-phase-11-10.md, phase-handover/phase-11-10.md
  • Experience track 11.011.10 complete

Phase 12.0 — Hospitality Platform Foundation

  • Independent backend/services/hospitality (hospitality_db, port 8009, version 0.12.0.0, commercial product Torbat Food)
  • Foundation aggregates: Venue, Branch, DiningArea, DiningTable, Menu, MenuCategory, MenuItem, BundleDefinition, TenantBundle, FeatureToggle, roles/permissions, configuration/settings/events/audit
  • Feature-based architecture: bundle licensing + feature toggles + /capabilities discovery
  • Venue formats catalog (cafe → catering) without hardcoded engines
  • Publish-only events hospitality.*; permissions hospitality.*
  • Provider contracts only (Accounting, CRM, Loyalty, Communication, Delivery, Experience/Website, AI, …)
  • Alembic 0001_initial; compose + .env.example wiring
  • Tests: architecture, API, tenant isolation, permissions, bundles, migration, dependency, security, performance, docs
  • Docs: hospitality-phase-12-0.md, phase-handover/phase-12-0.md, hospitality-roadmap.md, ADR-017
  • Historical restaurant-foundation / restaurant scaffold superseded by hospitality
  • No POS / kitchen / ordering / reservation engines

Phase 12.1 — Digital Menu Catalog

  • Catalog aggregates: Allergen, ModifierGroup, ModifierOption, MenuItemModifier, MenuItemAllergen, AvailabilityWindow, MenuMediaRef, MenuLocalization
  • Additive MenuItem fields (prep time, calories, dietary flags, tags, primary_media_ref)
  • Catalog APIs + validators + permissions + publish-only events
  • Alembic 0002_phase_121_digital_menu_catalog; version 0.12.1.0; capabilities digital_menu_catalog
  • Tests: catalog happy path, tenant isolation, validation, architecture/migration/docs updates
  • Docs: hospitality-phase-12-1.md, phase-handover/phase-12-1.md
  • No POS / kitchen / QR ordering / reservation engines

Phase 12.2 — QR Menu & QR Ordering

  • Aggregates: QrCode, QrMenuSession, QrOrderingSession, Cart, CartLine
  • APIs + validators + permissions + publish-only events
  • Alembic 0003_phase_122_qr_menu_ordering; version 0.12.2.0; capabilities qr_menu, qr_ordering
  • Tests: QR happy path, tenant isolation, validation, architecture/migration/docs
  • Docs: hospitality-phase-12-2.md, phase-handover/phase-12-2.md
  • No POS / kitchen / payment / reservation engines

Phase 12.3 — Table Service & Reservations

  • Aggregates: Reservation, TableAssignment, ServiceRequest, WaitlistEntry
  • APIs + validators + permissions + publish-only events (status transitions with terminal-state guards)
  • Alembic 0004_phase_123_table_service_reservations; version 0.12.3.0; capabilities table_service, reservation
  • Tests: reservation/table-assignment/service-request/waitlist happy paths, tenant isolation, validation, architecture/migration/docs
  • Docs: hospitality-phase-12-3.md, phase-handover/phase-12-3.md
  • No POS / kitchen / payment engines

Phase 12.4 — POS Lite

  • Aggregates: PosRegister, PosShift, PosTicket, PosTicketLine
  • APIs + validators + permissions + publish-only events (shift open/close, ticket void)
  • Alembic 0005_phase_124_pos_lite; version 0.12.4.0; capabilities pos_lite
  • Tests: register/shift/ticket/line happy path, tenant isolation, quantity validation, architecture/migration/docs
  • Docs: hospitality-phase-12-4.md, phase-handover/phase-12-4.md
  • No POS Pro (payments/discounts/taxes) / kitchen engines

Phase 12.5 — POS Pro

  • Aggregates: PosPayment, PosDiscount, PosTaxLine, PosFloorPlan, PosStation
  • APIs + validators + permissions + publish-only events
  • Alembic 0006_phase_125_pos_pro; version 0.12.5.0; capabilities pos_pro
  • Tests: payment/discount/tax/floor-plan/station happy path, tenant isolation, discount percent + payment amount validation, architecture/migration/docs
  • Docs: hospitality-phase-12-5.md, phase-handover/phase-12-5.md
  • No accounting journal posting / real payment gateway / kitchen dispatch

Phase 12.6 — Kitchen

  • Aggregates: KitchenStation, KitchenTicket, KitchenTicketItem
  • APIs + validators + permissions + publish-only events (status transitions with terminal-state guards)
  • Alembic 0007_phase_126_kitchen; version 0.12.6.0; capabilities kitchen, kitchen_engine
  • Tests: station/ticket/item happy path, tenant isolation, quantity validation, architecture/migration/docs
  • Docs: hospitality-phase-12-6.md, phase-handover/phase-12-6.md
  • No connector integrations yet; kitchen tickets reference POS/QR sources by UUID only

Phase 12.7 — Connectors

  • Aggregates: ConnectorRegistration, ConnectorDispatch
  • app/providers/mocks.py: no-op mocks for Accounting/CRM/Loyalty/Communication/Delivery/WebsiteBuilder Protocols (no httpx, no cross-service imports)
  • APIs + validators + permissions + publish-only events (dispatch → sent if registration active, else failed)
  • Alembic 0008_phase_127_connectors; version 0.12.7.0; capabilities delivery_integration, accounting_integration, crm_integration, loyalty_integration, communication_integration, website_integration
  • Tests: registration/dispatch happy path, tenant isolation, code uniqueness, architecture/migration/docs
  • Docs: hospitality-phase-12-7.md, phase-handover/phase-12-7.md
  • No real connector SDK calls; all dispatch responses are locally mocked

Phase 12.8 — Analytics

  • Aggregates: AnalyticsReportDefinition, AnalyticsSnapshot
  • APIs + validators + permissions + publish-only events (POST /analytics-snapshots/refresh computes metrics via local COUNT(*) queries)
  • Alembic 0009_phase_128_analytics; version 0.12.8.0; capability analytics
  • Tests: report/snapshot happy path, tenant isolation, code uniqueness, unknown metric_key rejection, architecture/migration/docs
  • Docs: hospitality-phase-12-8.md, phase-handover/phase-12-8.md
  • No external analytics engine or cross-service reads; local table counts only

Phase 10.0 — Delivery Platform Foundation

  • backend/services/delivery service scaffold (API / services / repositories / models)
  • Foundation aggregates: DeliveryOrganization, DeliveryHub, DeliveryRole, DeliveryPermission, ExternalProviderConfig, RoutingEngineRegistration, DeliveryConfiguration, DeliverySetting, DeliveryAuditLog
  • Platform provider contracts (Accounting, CRM, Loyalty, Communication, Notification, Storage, AI, Identity, RoutingEngine, Fleet)
  • Publish-only events (delivery.organization|hub|external_provider|routing_engine|configuration|setting.*)
  • Health /health, Capabilities /capabilities, Metrics /metrics
  • APIs under /api/v1 for organizations, hubs, external-providers, routing-engines, configurations, settings, audit
  • Permissions delivery.* trees; tenant isolation via X-Tenant-ID
  • Alembic 0001_initial + delivery_db wiring (compose port 8007); version 0.10.0.0
  • Architecture / API / tenant / permissions / migration / dependency / security / docs tests
  • Docs: delivery-phase-10-0.md, phase-handover/phase-10-0.md
  • No driver/fleet/dispatch/routing/tracking engines (deferred)

Phase 10.1 — Driver Management

  • Aggregates: Driver, DriverCredential, DriverDocument, DriverLifecycleEvent, OutboxEvent
  • Lifecycle: activate / suspend / resume / deactivate / block / unblock / archive + append-only history
  • Soft delete + optimistic locking; list pagination / filter / sort / search
  • Commands, queries, policies, specifications, validators
  • APIs /api/v1/drivers + /api/v1/permissions/catalog; capabilities/metrics phase: 10.1
  • Permissions delivery.drivers.*; events delivery.driver.* via transactional outbox
  • Alembic 0002_phase_101_drivers; version 0.10.1.0
  • Tests: lifecycle, credentials/documents, tenant, architecture, migration, permissions, performance indexes, docs
  • Docs: delivery-phase-10-1.md, phase-handover/phase-10-1.md
  • No fleet / dispatch / routing / tracking engines (deferred)

Delivery Platform Frontend (Torbat Driver) baseline

  • Module scaffold frontend/modules/delivery/ per frontend architecture migration
  • Thin App Router routes app/delivery/ (56+ screens, loading/error per segment)
  • BFF proxy /api/delivery/* → delivery-service :8007
  • Typed delivery-api client — organizations, hubs, drivers (full lifecycle), providers, routing engines, configurations, settings, audit, permissions catalog, health/capabilities/metrics
  • Portal shell, CRUD factory, capability phase gates (no mock data for future APIs)
  • Driver detail: profile, lifecycle actions, credentials, documents
  • Executive dashboard with real tenant-scoped counts
  • Design tokens --delivery-accent*; apps catalog tile → /delivery/hub
  • npm run validate:delivery; ESLint + architecture boundary for delivery domain
  • Docs: frontend/docs/delivery-*.md

Remaining (honest): dispatch/fleet/tracking/maps live/realtime/settlement screens unlock when backend phases 10.210.10 enable /capabilities flags.


Phase HC-Reg — Healthcare Platform Registration

Documentation-only registration. No business code, models, APIs, migrations, or repositories.

  • Phase roadmap 13.013.7 documented in healthcare-roadmap.md
  • Planned modules registered in module-registry.md
  • Phase area README: phases/Healthcare/README.md
  • Phase documents: 13.0 Foundation through 13.7 Delivery Integration
  • Roadmap / progress / next-steps integration
  • Port 8010 and healthcare_db reserved in registry
  • No business services modified at registration time

Phase 13.0 — Healthcare Platform Foundation

  • Independent backend/services/healthcare (healthcare_db, port 8010, version 0.13.0.0, commercial product Torbat Health)
  • Foundation aggregates: Clinic, Branch, Department, Doctor, Patient, HealthcareRole, HealthcarePermission, ExternalProviderConfig, HealthcareConfiguration, HealthcareSetting, HealthcareAuditLog, OutboxEvent
  • Provider contracts only (Communication, CRM, Loyalty, Accounting, Delivery, Storage, AI, Identity)
  • Publish-only events healthcare.clinic.*, healthcare.doctor.*, healthcare.patient.*, healthcare.setting.*
  • Permissions healthcare.*; APIs under /api/v1/clinics|branches|departments|doctors|patients|settings|…
  • Alembic 0001_initial; compose + .env.example + postgres init wiring
  • Tests: architecture, API, tenant, permissions, migration, dependency, security, docs
  • Docs + handover: phase-handover/phase-13-0.md
  • No appointment/clinical/pharmacy/delivery engines

Phase 13.1 — Healthcare Appointment Engine

  • Aggregates: Schedule, AvailabilityWindow, AppointmentType, Appointment, WaitingListEntry
  • Lifecycle: book, confirm, cancel, reschedule, no-show; conflict detection on overlapping slots
  • Communication reminder via provider mock
  • Alembic 0002_phase_131_appointments; version 0.13.1.0
  • Events healthcare.appointment.*, healthcare.schedule.*
  • Handover: phase-handover/phase-13-1.md

Phase 13.2 — Healthcare Doctor Panel

  • VisitSession, VisitNote, doctor dashboard/queue APIs
  • Visit lifecycle: start, finish, defer, call-next; finish → appointment completed
  • Alembic 0003_phase_132_doctor_panel; version 0.13.2.0
  • Handover: phase-handover/phase-13-2.md

Phase 13.3 — Healthcare Clinic Management

  • ClinicService catalog, StaffAssignment, ClinicPolicy, OperatingHoursPolicy
  • Policy validators (cancellation vs booking lead time)
  • Alembic 0004_phase_133_clinic_management; version 0.13.3.0
  • Handover: phase-handover/phase-13-3.md

Phase 13.4 — Healthcare Patient Portal

  • Patient-scoped APIs under /api/v1/patient-portal/* (profile, appointments, documents, notification preferences)
  • Alembic 0005_phase_134_patient_portal; version 0.13.4.0
  • Handover: phase-handover/phase-13-4.md

Phase 13.5 — Healthcare Medical Record

  • MedicalRecord, Encounter (finalize immutability), Condition, Allergy, MedicationStatement, ImmunizationRecord, access audit
  • Alembic 0006_phase_135_medical_record; version 0.13.5.0
  • Handover: phase-handover/phase-13-5.md

Phase 13.6 — Healthcare Pharmacy Network

  • Pharmacy, PrescriptionOrder, PrescriptionLine, fulfillment lifecycle (accept → ready → picked_up / cancelled)
  • Alembic 0007_phase_136_pharmacy_network; version 0.13.6.0
  • Handover: phase-handover/phase-13-6.md

Phase 13.7 — Healthcare Delivery Integration

  • DeliveryIntegrationRegistration, DeliveryJobIntent, DeliveryJobStatusSnapshot, webhook status ingest
  • Delivery provider mock (no cross-service imports); Communication notify on milestones
  • Alembic 0008_phase_137_delivery_integration; version 0.13.7.0
  • 57 backend tests passing; frontend /healthcare shell + BFF + catalog tile
  • Handover: phase-handover/phase-13-7.md
  • Snapshot: service-snapshots/healthcare.yaml

Healthcare Platform

  • Phases 13.013.7 complete (Foundation through Delivery Integration)

Phase BB-Reg — Beauty Business Platform Registration

Documentation-only registration. No business code, models, APIs, migrations, or repositories.

  • Phase roadmap 14.014.7 documented in beauty-business-roadmap.md
  • Planned modules registered in module-registry.md
  • Phase area README: phases/BeautyBusiness/README.md
  • Phase documents: 14.0 Foundation through 14.7 Marketing & Loyalty
  • Roadmap / progress / next-steps integration
  • Port 8011 and beauty_business_db reserved in registry (implementation deferred)
  • Documented independence from Healthcare module (separate docs, phases, frontend, permissions, branding)
  • No business services modified

Phase 14.0 — Beauty Business Platform Foundation

  • Independent backend/services/beauty_business (beauty_business_db, port 8011, version 0.14.0.00.14.7.0, commercial product Torbat Beauty)
  • Foundation aggregates: BeautyOrganization (incl. business_format), BeautyBranch, BeautyRole, BeautyPermission, ExternalProviderConfig, BookingEngineRegistration, BeautyConfiguration, BeautySetting, BeautyAuditLog, OutboxEvent
  • BusinessFormat enum: salon, barbershop, clinic, laser, skin_care, hair_treatment, spa
  • Provider contracts only (CRM, Accounting, Loyalty, Communication, Delivery, Experience, Storage, AI, Identity)
  • Publish-only events beauty_business.*; permissions beauty_business.*
  • Alembic 0001_initial; compose + .env.example wiring
  • Tests: architecture, API, tenant, permissions, migration, dependency, security, docs
  • No booking/catalog/customer engines in 14.0 scope

Phase 14.1 — Beauty Booking Engine

  • Aggregates: StaffSchedule, StaffAvailability, ScheduleException, AppointmentType, Appointment, AppointmentStatusHistory, WaitingListEntry
  • Appointment lifecycle: confirm, check-in, complete, cancel, no-show
  • Alembic 0002_phase_141_booking; APIs under /staff-schedules, /appointments, /waiting-list, …
  • Events beauty_business.appointment.*; permissions beauty_business.appointments.*, beauty_business.schedules.*

Phase 14.2 — Beauty Salon Management

  • Aggregates: TreatmentRoom, Station, BranchPolicy; optional business_format on branch
  • Alembic 0003_phase_142_salon; APIs /treatment-rooms, /stations, /branch-policies
  • Events beauty_business.room.*, beauty_business.station.*

Phase 14.3 — Beauty Service Catalog

  • Aggregates: ServiceCategory, BeautyService (+ ServiceVariant, BranchServiceAssignment, ServiceMediaRef in schema)
  • Alembic 0004_phase_143_catalog; APIs /service-categories, /services
  • Events beauty_business.service.*

Phase 14.4 — Beauty Customer Management

  • Aggregates: CustomerProfile (CRM ref), CustomerPreference, VisitHistoryEntry, CustomerDocumentRef
  • Alembic 0005_phase_144_customers; API /customers
  • Events beauty_business.customer.*

Phase 14.5 — Beauty Package & Membership

  • Aggregates: PackageDefinition, CustomerPackage, MembershipPlan, CustomerMembership (+ lines/redemptions/lifecycle in schema)
  • Alembic 0006_phase_145_packages; APIs /package-definitions, /membership-plans
  • Events beauty_business.package.*, beauty_business.membership.*

Phase 14.6 — Beauty Staff & Commission

  • Aggregates: StaffProfile, StaffSkill, StaffCertificate, CommissionRule, CommissionEntry
  • Alembic 0007_phase_146_staff; APIs /staff, /commission-rules
  • Events beauty_business.staff.*, beauty_business.commission.*

Phase 14.7 — Beauty Marketing & Loyalty Integration

  • Aggregates: MarketingCampaignRef, LoyaltyIntegrationConfig, CommunicationIntegrationConfig, IntegrationDispatch
  • Provider mocks for CRM, Loyalty, Communication, Accounting, Delivery, Experience
  • Alembic 0008_phase_147_marketing; APIs /marketing-campaigns, /loyalty-integrations, /communication-integrations, /integration-dispatches
  • 30 backend tests passing; frontend /beauty shell + BFF + catalog tile
  • Handover: phase-handover/phase-14-7.md
  • Snapshot: service-snapshots/beauty-business.yaml
  • Independent from Healthcare (separate DB, port, frontend, permissions)

Beauty Business Platform

  • Phases 14.014.7 complete (Foundation through Marketing & Loyalty Integration)

Loyalty Frontend (2026-07-26)

  • Added frontend/modules/loyalty engage portal + thin app/loyalty routes.
  • BFF /api/loyalty → Loyalty service 8004; wired CRUD/workflows for phases 7.07.6.
  • Docs: frontend/docs/loyalty-*.md.