TorbatYar/docs/experience-roadmap.md

# Experience Platform — Roadmap

> Registration document. **No implementation in this phase.**  
> Framework: [ai-framework/](ai-framework/README.md) · ADR: [ADR-016](architecture/adr/ADR-016.md) · Manifests: [phase-manifest.yaml](ai-framework/phase-manifest.yaml), [service-manifest.yaml](ai-framework/service-manifest.yaml)

| Field | Value |
| --- | --- |
| Service | `experience` |
| Commercial Product | Torbat Pages |
| Database | `experience_db` |
| Permission Prefix | `experience.*` |
| API Port (planned) | 8008 |
| Phases | 11.0 – 11.10 |
| Status | Phase 11.10 complete · **ARCHITECTURE COMPLETE** ([ADR-022](architecture/adr/ADR-022.md) — Published Resource + Actions + Access + Embed) |

## Vision

Deliver an independent, multi-tenant **Enterprise Experience Platform** inside TorbatYar so every current and future service can publish websites, landings, mini sites, menus, catalogs, profiles, forms, and campaign surfaces without owning page/theme/template engines — and without duplicating business logic or sharing databases.

## Business Scope

In scope (over Phases 11.0–11.10):

- Website Builder and Landing Pages
- Mini Sites and Business Profile Pages
- Restaurant Pages, Digital Menus, Digital Catalogs
- Link In Bio, Event, Campaign, Portfolio Pages
- Personal and Corporate Websites
- Forms, Surveys, Appointment Pages
- Public Profile, QR, SEO, Blog, Media, Knowledge Pages
- Versioned components, replaceable themes, dynamic layouts
- Template-based authoring; localization; RTL and LTR
- SEO, Mobile First, PWA readiness
- Optional AI content generation hooks
- Analytics shells; feature toggles; bundle licensing
- Widgets and consumer integration contracts
- Custom domain binding refs (DNS ownership remains platform edge / Core patterns)

## Architecture Scope

| Rule | Reference |
| --- | --- |
| Independent service + `experience_db` | [ADR-016](architecture/adr/ADR-016.md), [ADR-001](architecture/adr/ADR-001.md) |
| Layering API → Service → Repository → Model | [service-architecture.md](architecture/service-architecture.md) |
| Tenant-aware business tables | [ADR-003](architecture/adr/ADR-003.md) |
| Outbox-ready events `experience.*` | [ADR-006](architecture/adr/ADR-006.md) |
| White-label / branding alignment | [ADR-008](architecture/adr/ADR-008.md) |
| Messaging via Communication only | [ADR-012](architecture/adr/ADR-012.md) |
| Loyalty / CRM / vertical refs only | [ADR-011](architecture/adr/ADR-011.md) |
| AI optional / independent | [ai-architecture.md](architecture/ai-architecture.md) |
| FE/BE separation for builders & public shells | [ADR-002](architecture/adr/ADR-002.md) |
| Implementation via AI Framework | [ai-framework/](ai-framework/README.md) |

## Published Resource Architecture

Experience adopts the platform-wide **Published Resource** model ([ADR-022](architecture/adr/ADR-022.md), [published-resource-architecture.md](architecture/published-resource-architecture.md)).

| Rule | Meaning for Experience |
| --- | --- |
| `publish_id` | Cross-service public identity for every publishable surface |
| Publish Target Registry | Logical registry fields: `publish_id`, `tenant_id`, `resource_type`, `resource_id`, `canonical_url`, `publish_status`, `visibility`, `owner_service` |
| Open `resource_type` | Not a closed enum — Site, Page, Form, Survey, Appointment, Menu surface, Catalog, Campaign, Card, Event, Booking, and unlimited future types |
| Independent Form / Survey / Appointment | **Must not** require Site or Page; optional Site binding allowed; standalone publish required |
| Consumer integrations | Payment, Communication, Short Link, QR, Analytics, CRM, verticals attach via **`publish_id` only** |
| Reserved public URL prefixes | `/s/`, `/p/`, `/f/`, `/survey/`, `/book/`, `/menu/`, `/card/`, `/event/` (routing not implemented) |
| Published Actions | Open Action Registry; Experience binds actions; owning services execute ([published-action-registry.md](reference/published-action-registry.md)) |
| Public Access Model | Open access strategies; auth/payment/membership/OTP not owned by Experience ([public-access-contract.md](reference/public-access-contract.md)) |
| Universal Embed | Open embed types + security/sizing/theme/analytics contracts ([embed-contract.md](reference/embed-contract.md)) |
| Architecture status | **ARCHITECTURE COMPLETE** — implementation deferred to future registered phases (including frontend) |

**Implementation status:** Architecture / documentation only. Registry storage, access engine, embed SDK, and resolution APIs are **not** part of completed phases 11.0–11.10 and must not be coded until a future phase is registered.

### Future products (consume Published Resources — never own Experience data)

Torbat Link · Torbat QR · Torbat Card · Torbat Booking · Torbat Ticket · Torbat Event · Torbat Learning

Contracts: [published-resource-contracts.md](reference/published-resource-contracts.md).

## Platform Principles

| Principle | Meaning |
| --- | --- |
| Every Page is a Resource | First-class tenant-scoped resource with identity, lifecycle, permissions |
| Every Component is Versioned | Immutable versions; publish pins versions |
| Every Theme is Replaceable | Themes swap without rewriting page trees |
| Every Layout is Dynamic | Layout composition is data-driven |
| Template Based | New experiences start from templates |
| Localization | Multi-locale content and metadata |
| RTL and LTR | Directionality first-class |
| SEO | Canonical/meta/sitemap/robots shells |
| Mobile First | Responsive defaults; mobile contracts |
| PWA | Manifest/service-worker readiness hooks |
| AI generation | Optional; core works offline |
| Analytics | Event/metrics shells |
| Feature Toggles | Capability flags per tenant/bundle |
| Bundle Licensing | Commercial packs gated via entitlement |

## Supported Consumers

Hospitality · Marketplace · Sports Center · CRM · Accounting · Loyalty · Communication · Academy · Clinic · Hotel · Tourism · Future Services

## Supported Bundles

Mini Site · Business Website · Landing Builder · Digital Menu · Digital Catalog · Portfolio · Blog · Appointment · Campaign · QR Landing · Bio Link · Custom Domain · SEO · Analytics · AI Content · Forms · Widgets

## Module Map

| Module | Responsibility | Introduced |
| --- | --- | --- |
| Sites | Site aggregate / host binding refs | 11.1 |
| Pages | Page resources and lifecycle | 11.1 |
| Page Types | Typed page kinds (landing, menu, bio, …) | 11.1 |
| Components | Versioned component definitions | 11.2 |
| Component Versions | Immutable component revisions | 11.2 |
| Themes | Replaceable theme packs | 11.3 |
| Layouts | Dynamic layout definitions | 11.3 |
| Templates | Template catalog and instantiation | 11.4 |
| Locales | Localization and directionality | 11.5 |
| Media Refs | Storage file references (no binaries) | 11.5 |
| Forms | Form definitions and submissions shells | 11.6 |
| Surveys | Survey definitions | 11.6 |
| Appointments | Appointment page booking shells (refs) | 11.6 |
| Publishing | Publish/unpublish workflows | 11.7 |
| Domains | Custom domain binding refs | 11.7 |
| SEO | SEO metadata, sitemap/robots shells | 11.7 |
| PWA | PWA manifest readiness | 11.7 |
| Bundles | Capability bundles / licensing | 11.8 |
| Feature Toggles | Experience feature flags | 11.8 |
| Widgets | Embeddable widget contracts | 11.9 |
| Consumer Connectors | Vertical integration contracts | 11.9 |
| Analytics | Analytics shells | 11.10 |
| AI Hooks | Optional AI content contracts | 11.10 |
| Audit / Config / Health | Foundation shells | 11.0 |

Canonical inventory: [module-registry.md](module-registry.md#experience).

## Integration Map

```
Verticals (Hospitality / Marketplace / Sports / CRM / Clinic / Hotel / Tourism / …)
        │
        │ API / Events (entity refs only — no shared DB)
        ▼
   Experience Platform ──API─────────▶ Core         (entitlement, tenant, branding)
   Experience Platform ──API─────────▶ Storage      (media refs)
   Experience Platform ──API/Events──▶ CRM          (contact/org refs)
   Experience Platform ──API/Events──▶ Loyalty      (optional)
   Experience Platform ──API/Events──▶ Communication (notify / OTP forms)
   Experience Platform ──API/Events──▶ Hospitality / Marketplace / Sports / …
   Experience Platform ──API/Events──▶ Delivery     (optional campaign logistics refs)
   Experience Platform ──API─────────▶ AI Platform  (optional content assist)
   Experience Platform ──API/Events──▶ Automation   (optional triggers)
```

Forbidden: cross-DB queries, embedding SMS providers inside Experience, owning Restaurant menu/item catalogs as source of truth, owning CRM contacts, storing media binaries, creating Accounting journals.

## Disambiguation

| Term | Owner |
| --- | --- |
| Tenant branding / white-label defaults | Core (+ ADR-008) |
| Page / site / theme / template resources | Experience Platform (`experience`) |
| Menu item catalog / POS menu | Hospitality / Restaurant services |
| Product catalog | Marketplace / Ecommerce |
| Historical `website_builder` scaffold | Prefer Experience for new work |

## Phase Map

| Phase | ID | Name | Status |
| --- | --- | --- | --- |
| Reg | `experience-reg` | Platform Registration | Complete |
| 11.0 | `experience-11.0` | Foundation | Complete |
| 11.1 | `experience-11.1` | Sites & Page Resources | Complete |
| 11.2 | `experience-11.2` | Component Library & Versioning | Complete |
| 11.3 | `experience-11.3` | Theme & Layout Engine | Complete |
| 11.4 | `experience-11.4` | Template System | Complete |
| 11.5 | `experience-11.5` | Localization, RTL/LTR & Media | Complete |
| 11.6 | `experience-11.6` | Forms, Surveys & Appointments | Complete |
| 11.7 | `experience-11.7` | Publishing, Domains, SEO & PWA | Complete |
| 11.8 | `experience-11.8` | Bundles, Licensing & Feature Toggles | Complete |
| 11.9 | `experience-11.9` | Consumer Integrations & Widgets | Complete |
| 11.10 | `experience-11.10` | Analytics, AI Content & Enterprise Validation | Complete |
| Arch | `platform-published-resource-arch` | Published Resource Architecture (docs) | Complete |
| Arch | `platform-experience-arch-freeze` | Actions + Access + Embed freeze (docs) | Complete · **ARCHITECTURE COMPLETE** |

Details (dependencies, required docs/services, completion criteria): [phase-manifest.yaml](ai-framework/phase-manifest.yaml).

## Platform Expose (every implementation phase)

Health API · Capability API · Metrics · Events · REST APIs · Permission APIs

## Future Expansion

- Additional page-type packs without vertical code changes
- Third-party theme/component marketplaces behind provider protocols
- Deeper render CDN / edge caching when scoped
- Cross-tenant platform-admin experience analytics (explicit + audited)
- Publish Target Registry storage + resolution APIs (future registered phase)
- Public URL edge routing for reserved prefixes

## Out of Scope

- Owning Accounting ledgers or Posting Engine
- Owning Sales CRM aggregates
- Owning Loyalty ledger / campaigns
- Owning SMS/email/push providers (Communication owns them)
- Owning Hospitality menu/item or Marketplace product source of truth
- Owning File Storage binaries
- Implementing Phase 11.x business code in the registration phase
- Page Builder / public site UI (frontend phases)
- Replacing Core white-label tenant branding ownership (Experience consumes it)
- Owning Short Link / QR issuance engines as source of truth (reserved products resolve `publish_id`)
- Implementing Publish Target Registry storage/APIs without a registered phase

## Related Documents

- [ADR-016](architecture/adr/ADR-016.md)
- [ADR-022](architecture/adr/ADR-022.md) · [Published Resource Architecture](architecture/published-resource-architecture.md)
- [Phases / Experience](phases/Experience/README.md)
- [Phase Handover XP-Reg](phase-handover/phase-xp-reg.md)
- [Experience Published Resource handover](phase-handover/phase-experience-published-resource-arch.md)
- [Module Registry](module-registry.md#experience)
- [Module Boundaries](architecture/module-boundaries.md)
- [AI Development Framework](ai-framework/README.md)