TorbatYar/docs/architecture/adr/ADR-024.md

# ADR-024: Independent Workspace Platform Service (Torbat Workspace)

| Field | Value |
| --- | --- |
| Status | Accepted |
| Date | 2026-09-12 |
| Deciders | Platform Architecture |
| Supersedes | — |
| Superseded by | — |

## Context

Organizations on TorbatYar need an **enterprise work-management** center: projects, tasks, content operations, editorial calendars, creative review, collaboration, files/assets, OKR/KPI, resource planning, time tracking, and reporting.

Those capabilities must not be absorbed into:

- **Core Platform** — owns the SaaS **Tenant Workspace** (onboarding, membership, entitlement), not work-management aggregates
- **CRM** — owns sales tasks, sales comments/mentions, and sales notes on leads/opportunities
- **Experience (Torbat Pages)** — owns public sites, page resources, themes, and publish surfaces
- **File Storage** — owns binary blobs and signed-URL storage
- **Accounting** — owns journals and the Posting Engine; “Project” there is an analytical dimension
- **Payment** — owns a tenant **Payment Workspace** (enablement/mode), not work items
- **AI Assistant (Torbat AI)** — owns the product AI platform; Workspace may consume it

The word **Workspace** is already used for the operational Tenant after onboarding, for Experience workspace shells, and for Payment workspace shells. A new independent service requires an explicit naming rule.

TorbatYar already isolates shared platforms as independent services (Loyalty [ADR-011](ADR-011.md), Communication [ADR-012](ADR-012.md), Sports Center [ADR-014](ADR-014.md), Delivery [ADR-015](ADR-015.md), Experience [ADR-016](ADR-016.md), Hospitality [ADR-017](ADR-017.md), Payment [ADR-020](ADR-020.md)). Work management follows the same pattern.

Commercial product name: **Torbat Workspace**. Category: **Platform Product**. Purpose: **Enterprise Work Management Platform**.

Commercial packaging is already extensible ([ADR-023](ADR-023.md)): registration + capability declaration + documentation is sufficient. This ADR does **not** implement Commercial Runtime rows, bundles, subscriptions, licenses, or trials.

## Decision

1. Introduce `workspace` as an **independent Workspace Platform service** (deployable name **`workspace-service`**) with sole ownership of `workspace_db` ([ADR-001](ADR-001.md)).
2. Permission prefix: `workspace.*`. Publish-only domain events: `workspace.*`.
3. Row-level multi-tenancy via `tenant_id` ([ADR-003](ADR-003.md)). The product is always scoped to a Core Tenant.
4. **Naming disambiguation (normative):**

   | Term | Owner | Meaning |
   | --- | --- | --- |
   | **Tenant Workspace** / Core Workspace | Core | Operational Tenant after onboarding |
   | **Experience Workspace** | Experience | Experience-owned site/workspace shell (`experience.workspace.*`) |
   | **Payment Workspace** | Payment | Payment enablement unit (`payment.workspace.*`) |
   | **Torbat Workspace** | this service | Enterprise work-management product |
   | **Work Hub** | this service | Tenant-scoped root aggregate inside Torbat Workspace (teams, spaces, settings) |

   Event namespace `workspace.*` is reserved for **Torbat Workspace** only. Core, Experience, and Payment keep their existing prefixes.
5. Consume Core, Identity, CRM, Accounting, File Storage, Communication, Experience, and AI Assistant **only** via REST API and Events — never shared tables or foreign model imports.
6. Financial journals only through Accounting Posting Engine ([ADR-010](ADR-010.md)). Workspace emits project-cost / time-cost **intents**; Accounting posts externally.
7. Sales CRM aggregates remain in CRM. Workspace tasks, notes, comments, and mentions are **work-management** records and may hold opaque `crm_*_ref` values only.
8. Public pages, themes, and `publish_id` surfaces remain in Experience ([ADR-016](ADR-016.md), [ADR-022](ADR-022.md)). Content Studio is editorial/operations, not a page builder.
9. Binary storage remains in File Storage. Workspace owns folders, asset catalog metadata, and `file_ref` pointers.
10. Product AI remains optional and external ([ai-architecture.md](../ai-architecture.md)). Workspace `ai-assistant` is a capability that calls AI Assistant contracts; core work-management works when AI is off.
11. Messaging / notifications only through Communication ([ADR-012](ADR-012.md)).
12. Implementation phases registered as **`workspace-15.0`–`workspace-15.11`** in [phase-manifest.yaml](../../ai-framework/phase-manifest.yaml); roadmap in [workspace-roadmap.md](../../workspace-roadmap.md). Registration phase: `workspace-reg`.
13. API port **8013** reserved; service path `backend/services/workspace`.
14. UI lives in `frontend/` only ([ADR-002](ADR-002.md)); this service exposes APIs and events.
15. **Commercial compatibility (architecture only):** Torbat Workspace is a Platform Product compatible with Commercial Runtime, Business Bundles, Capability Registry, Subscription, License, and Trial contracts ([ADR-023](ADR-023.md)). No commercial implementation, catalog seed, or runtime rows are authorized by this ADR.
16. Planned L1 entitlement key: `workspace.module.enabled`. Service-local L2 capability packs / L3 toggles (when implemented) live in `workspace_db` and must not recompute Core plan entitlements.

## Consequences

### Positive

- One reusable work-management platform for all tenant organizations
- Clear boundary with Core tenancy, CRM sales work, Experience publishing, File Storage binaries, and Accounting books
- Commercial Runtime can package Torbat Workspace later as registry rows only (zero Core architecture change)
- Event/permission prefix `workspace.*` is unambiguous once Core/Experience/Payment keep their existing namespaces

### Negative

- Additional deployable service and database
- The everyday word “workspace” now has four documented meanings and must be qualified in docs and APIs
- Eventual consistency between Workspace cost/time intents and Accounting journals, and between Workspace collaboration refs and CRM

### Neutral

- Registration (this ADR + manifests + roadmap) precedes business code; `workspace-15.0` implements the scaffold
- CRM collaboration (sales comments/tasks) and Workspace collaboration remain sibling domains
- No change to Commercial Runtime engines, seeds, or frontend catalogs

## Alternatives Considered

1. Expand Core Tenant Workspace into work management — rejected (violates business-module boundaries; couples tenancy with projects/tasks/content).
2. Expand CRM tasks/comments into a full PM suite — rejected (CRM is Sales CRM; work management is a different product).
3. Expand Experience into content operations / creative studio — rejected (Experience owns published pages, not editorial/project operations).
4. Embed files/assets as the File Storage product — rejected (storage owns blobs; Workspace owns work-management asset catalogs).
5. Defer as an unnamed future service — rejected (product, phases, commercial compatibility, and naming collisions must be registered first).

## Related Documents

- [Workspace Roadmap](../../workspace-roadmap.md)
- [Module Boundaries](../module-boundaries.md)
- [Module Registry — workspace](../../module-registry.md#workspace)
- [Commercial Platform Architecture](../commercial-platform-architecture.md)
- [Phase Manifest](../../ai-framework/phase-manifest.yaml)
- [Service Manifest](../../ai-framework/service-manifest.yaml)
- [ADR-001](ADR-001.md) · [ADR-002](ADR-002.md) · [ADR-003](ADR-003.md) · [ADR-006](ADR-006.md) · [ADR-010](ADR-010.md) · [ADR-012](ADR-012.md) · [ADR-016](ADR-016.md) · [ADR-022](ADR-022.md) · [ADR-023](ADR-023.md)