ar2

docs/implementation/task-ar.1-architecture-transition-plan-2026-07-07.md

@@ -0,0 +1,791 @@
+# Task AR.1 Architecture Transition Plan - 2026-07-07
+
+## Scope
+
+- complete AR.1 as an architecture-only transition-planning phase
+- map the current ALLA OS production architecture to the frozen Relationship-Driven Sales Workspace blueprint
+- define the target architecture, transition rules, ownership boundaries, projection strategy, workspace strategy, business-event strategy, and epic order
+- keep the phase documentation-only with no schema, API, UI, service, permission, or business-logic runtime changes
+
+## Review Summary
+
+Reviewed before writing this architecture baseline:
+
+- `AGENTS.md`
+- `plans/task-ar.1.md`
+- `docs/standards/task-contract-template.md`
+- `docs/standards/task-catalog.md`
+- `docs/standards/project-foundations.md`
+- `docs/standards/architecture-rules.md`
+- `docs/standards/ui-ux-rules.md`
+- `docs/standards/task-review-checklist.md`
+- `docs/business/relationship-sales-workspace-blueprint-v1.md`
+- `docs/implementation/task-bu-r.0-business-blueprint-freeze-2026-07-07.md`
+- `docs/implementation/task-bu-r.0.1-workspace-activity-business-blueprint-2026-07-07.md`
+- `docs/implementation/task-bu-r.1-business-capability-audit-2026-07-07.md`
+- `docs/security/crm-authorization-boundaries.md`
+- `docs/adr/0014-crm-multi-role-user-assignment.md`
+- `docs/adr/0015-customer-ownership-contact-sharing.md`
+- `docs/adr/0016-won-lost-lifecycle-governance.md`
+- `docs/adr/0017-report-foundation.md`
+- `docs/adr/0018-lead-enquiry-domain-separation.md`
+- `docs/implementation/task-f4-notification-framework-foundation.md`
+- `docs/implementation/task-f5-approval-automation-foundation.md`
+- `docs/implementation/task-d.6-crm-activity-foundation-audit-log-separation-2026-07-01.md`
+- `docs/implementation/task-d54-lead-enquiry-workspace-separation-ui-foundation.md`
+- `docs/implementation/task-d55-opportunity-sales-workspace-refinement.md`
+- `docs/implementation/task-d551-force-rename-enquiry-domain-opportunity.md`
+- `src/db/schema.ts`
+- `src/lib/auth/crm-access.ts`
+- `src/features/crm/security/server/service.ts`
+- `src/features/foundation/audit-log/service.ts`
+- `src/features/foundation/approval/server/service.ts`
+- `src/features/foundation/notifications/server/event-service.ts`
+- `src/features/crm/customers/server/service.ts`
+- `src/features/crm/opportunities/server/service.ts`
+- `src/features/crm/quotations/server/service.ts`
+- `src/features/crm/dashboard/server/service.ts`
+- `src/features/crm/reports/server/service.ts`
+- `src/features/crm/activity/types.ts`
+- `src/config/nav-config.ts`
+- `src/app/dashboard/workspaces/page.tsx`
+
+## Executive Summary
+
+1. The current production backbone is already strong and should be preserved: customer/contact governance, lead/opportunity split, quotation lifecycle, approval runtime, notification foundation, dashboard KPI, report foundation, PDF/artifact, document sequencing, and CRM resolved-access security.
+2. The main architecture gap is not core CRUD. The gap is the operating layer above it: shared Activity, generated Timeline, Calendar projection, My Day, Manager Workspace, Executive Workspace, and broader business-event fan-out.
+3. The transition strategy should preserve existing source-of-truth domains and introduce new capabilities as extension and projection layers, not replacements.
+4. Timeline, Calendar, Dashboard, Notification, and Workspace surfaces must consume derived views over governed source domains instead of storing duplicate business lifecycle state.
+5. Existing admin `/dashboard/workspaces` routes already mean organization administration. Future business workspaces must not silently reuse that path or overload its meaning.
+
+## 1. Current Architecture Diagram
+
+```mermaid
+flowchart TD
+  Auth[Auth.js + Session Helpers]
+  Access[Resolved CRM Access<br/>organization + role assignments + scope]
+  Routes[Route Handlers<br/>/api/crm/**]
+  Relationship[Relationship Layer<br/>Customer + Contact]
+  Lead[Lead Layer]
+  Opportunity[Opportunity / Project Layer]
+  Quotation[Quotation / Commercial Layer]
+  Approval[Approval Layer]
+  Dashboard[Dashboard Layer]
+  Reports[Report Layer]
+  Notifications[Notification Foundation]
+  Audit[Audit Foundation]
+  Foundations[Foundations<br/>master options, document sequence, storage, artifact, PDF, role management]
+  DB[(PostgreSQL + Drizzle)]
+
+  Auth --> Access
+  Access --> Routes
+  Routes --> Relationship
+  Routes --> Lead
+  Routes --> Opportunity
+  Routes --> Quotation
+  Routes --> Approval
+  Routes --> Dashboard
+  Routes --> Reports
+
+  Relationship --> Foundations
+  Lead --> Audit
+  Opportunity --> Audit
+  Quotation --> Audit
+  Approval --> Audit
+
+  Approval --> Notifications
+  Dashboard --> Opportunity
+  Dashboard --> Quotation
+  Dashboard --> Approval
+  Reports --> Opportunity
+  Reports --> Quotation
+  Reports --> Relationship
+
+  Relationship --> DB
+  Lead --> DB
+  Opportunity --> DB
+  Quotation --> DB
+  Approval --> DB
+  Notifications --> DB
+  Audit --> DB
+  Foundations --> DB
+```
+
+### Current-state interpretation
+
+- `Customer` and `Contact` are the production relationship anchor, with owner history and contact sharing already governed.
+- `Lead` is already a distinct domain, but its follow-up seam remains lighter than the target shared activity model.
+- `Opportunity` is already the active sales-owned project execution domain.
+- `Quotation` is already the active commercial document lifecycle owner.
+- `Approval` already publishes notification events and controls document workflow.
+- `Dashboard` and `Reports` already aggregate opportunity, quotation, follow-up, and approval data.
+- `Timeline`, `Calendar Workspace`, `My Day`, `Manager Workspace`, and `Executive Workspace` do not yet exist as production-grade architecture layers.
+
+## 2. Current Architecture Responsibility Matrix
+
+| Layer | Current Owner | Current Modules | Current Responsibility | Current Dependency | Extension Point |
+| --- | --- | --- | --- | --- | --- |
+| Security Layer | Auth + CRM access foundations | `src/lib/auth/crm-access.ts`, `src/features/crm/security/**` | resolve permission, branch, product, ownership, pricing, approval authority | memberships, CRM role assignments, route handlers | reuse for Activity, Timeline, Calendar, Workspace queries |
+| Relationship Layer | Customer domain | `src/features/crm/customers/**` | customer master, ownership, contacts, contact sharing, related commercial visibility | master options, document sequence, audit | extend into Customer Workspace projections |
+| Lead Layer | Lead domain | `src/features/crm/leads/**` | marketing signal capture, assignment, audit-backed follow-up seam | customer/contact foundation, access, audit | adapt lead follow-up into Activity later |
+| Project Layer | Opportunity domain | `src/features/crm/opportunities/**` | sales execution, assignment, forecast dates, Hot Project, project parties, won/lost outcome | customer, lead, storage, audit | primary consumer and publisher for Activity, Timeline, Calendar |
+| Commercial Layer | Quotation domain | `src/features/crm/quotations/**` | pricing, revision, approval entry, customer package, quotation follow-up, linked documents | opportunity, customer, approval, PDF, artifact | extend into richer timeline/calendar/event projections |
+| Approval Layer | Approval foundation | `src/features/foundation/approval/**` | workflow runtime, steps, request history, current actor resolution | quotations, notifications, audit, role assignments | preserve as workflow owner and publish more event consumers |
+| Notification Layer | Notification foundation | `src/features/foundation/notifications/**` | event persistence, recipient resolution, inbox delivery | approval events, templates, users | extend beyond approvals into operational activity events |
+| Reporting Layer | Report foundation | `src/features/crm/reports/**` | registry, filters, datasets, export, audit | resolved access, opportunity, quotation, ownership | reuse for manager/executive read models |
+| Dashboard Layer | Dashboard feature | `src/features/crm/dashboard/**` | KPI summary, follow-up analytics, approval widgets, hot projects | opportunity, quotation, approval, reporting helpers | split into manager/executive workspace modules later |
+| Foundation Layer | Shared foundations | audit, master options, document sequence, storage, PDF, artifact, role management | shared infrastructure and governed cross-cutting behavior | DB, auth context | preserve and compose rather than replace |
+
+## 3. Target Architecture Diagram
+
+```mermaid
+flowchart TD
+  Security[Security Layer<br/>resolved CRM access + pricing + scope]
+  Foundation[Foundation Layer<br/>audit, master options, sequence, storage, PDF, artifact, notification infra]
+  Relationship[Relationship Layer<br/>Customer + Contact + Relationship Health]
+  Lead[Lead Layer]
+  Project[Project Layer<br/>Opportunity + project parties + forecast + hot project]
+  Commercial[Commercial Layer<br/>Quotation + approval workflow + PO linkage]
+  Activity[Activity Layer<br/>shared operational work model]
+  Events[Business Event Layer]
+  Timeline[Timeline Projection]
+  Calendar[Calendar Projection]
+  Workspace[Workspace Layer<br/>Customer, Sales, My Day, Manager, Executive, Calendar]
+  Analytics[Analytics Layer<br/>Dashboard + Reports + Forecast Views]
+
+  Security --> Relationship
+  Security --> Lead
+  Security --> Project
+  Security --> Commercial
+  Security --> Activity
+  Security --> Timeline
+  Security --> Calendar
+  Security --> Workspace
+  Security --> Analytics
+
+  Foundation --> Relationship
+  Foundation --> Lead
+  Foundation --> Project
+  Foundation --> Commercial
+  Foundation --> Activity
+  Foundation --> Events
+
+  Relationship --> Activity
+  Lead --> Activity
+  Project --> Activity
+  Commercial --> Activity
+
+  Relationship --> Events
+  Lead --> Events
+  Project --> Events
+  Commercial --> Events
+  Activity --> Events
+
+  Events --> Timeline
+  Events --> Calendar
+  Events --> Analytics
+  Events --> Foundation
+
+  Activity --> Calendar
+  Activity --> Workspace
+  Timeline --> Workspace
+  Calendar --> Workspace
+  Analytics --> Workspace
+```
+
+### Target principles
+
+- `Activity` becomes the shared operational domain.
+- `Timeline` and `Calendar` are projections, not primary-write domains.
+- `Dashboard`, `Manager Workspace`, `Executive Workspace`, and `My Day` consume a combination of Activity, event, approval, and commercial projections.
+- `Approval` remains within the commercial/document control boundary, not inside Activity.
+- `Customer Workspace` extends the current customer detail foundation rather than creating a parallel relationship module.
+
+## 4. Domain Ownership Matrix
+
+| Domain | Primary Owner | Owns | Does Not Own |
+| --- | --- | --- | --- |
+| Organization | Foundation | tenant boundary, active workspace, plan | CRM lifecycle |
+| RBAC / CRM Access | Security foundation | permission union, scope union, pricing visibility, approval authority | business workflow state |
+| Customer | Relationship layer | account master, owner, relationship anchor | quotation status, opportunity outcome |
+| Contact | Relationship layer | person record, sharing | customer ownership, quotation pricing |
+| Lead | Marketing layer | early demand signal, handoff readiness | quotation approval, won/lost |
+| Opportunity | Project layer | project pursuit, forecast, hot project, business outcome | quotation revision history |
+| Quotation | Commercial layer | pricing, revision, approval lifecycle, approved document | won/lost outcome |
+| Approval | Approval layer | workflow execution and decision history | customer relationship state |
+| Activity | Activity layer | planned/completed work, owner/assignee, outcome summary | immutable audit, business result lifecycle |
+| Timeline | Projection layer | generated chronology view | manual source-of-truth editing |
+| Calendar | Projection layer | scheduled projection view | underlying work ownership |
+| Notification | Foundation delivery layer | delivery and inbox state | business lifecycle ownership |
+| Dashboard | Analytics layer | KPI aggregation and decision views | source business state |
+| Reports | Analytics layer | report datasets, exports, filters | live source mutations |
+
+## 5. Layer Responsibility Matrix
+
+| Layer | Responsibilities | Allowed Inputs | Outputs |
+| --- | --- | --- | --- |
+| Foundation | audit, storage, document generation, sequence, notification infra, master options | service-layer calls | shared services, artifacts, events, logs |
+| Security | auth, scope resolution, pricing visibility, approval visibility | session + memberships + role assignments | scoped context for services and read models |
+| Relationship | customer/contact data and ownership | route handlers, master options, security context | customer workspace source data, relationship event payloads |
+| Lead | marketing pipeline state and handoff | route handlers, customer/contact refs, security context | lead events, lead follow-up adapters |
+| Project | opportunity pursuit and outcome | route handlers, lead/customer refs, security context | forecast signals, hot project signals, activity adapters, project events |
+| Commercial | quotation, approval entry, approved package | route handlers, opportunity/customer refs, security context | document events, approval events, milestone signals |
+| Activity | shared work record lifecycle | route handlers, source-entity links, security context | activity events, timeline items, calendar items, My Day records |
+| Projection | timeline and calendar assembly | activities + business events + source-domain milestone fields | read models only |
+| Analytics | dashboard, reports, forecast | governed datasets, events, follow-up/activity views | KPI views, exports, manager/executive signals |
+| Workspace | role-oriented composition | projections + source detail + analytics summaries | navigable work surfaces |
+
+## 6. Transition Architecture Diagram
+
+```mermaid
+flowchart LR
+  Current[Current Production Domains<br/>Customer, Contact, Lead, Opportunity, Quotation, Approval]
+  Adapters[Adapter Layer<br/>follow-up adapters, event publishers, workspace composition]
+  Activity[New Activity Domain]
+  Projections[New Projection Layer<br/>Timeline + Calendar + My Day]
+  Workspaces[New Workspace Layer]
+  Analytics[Extended Dashboard / Reports]
+
+  Current --> Adapters
+  Adapters --> Activity
+  Current --> Projections
+  Activity --> Projections
+  Projections --> Workspaces
+  Current --> Workspaces
+  Current --> Analytics
+  Activity --> Analytics
+```
+
+### Transition rules
+
+1. Preserve existing source domains as write owners.
+2. Introduce adapters before moving any follow-up semantics.
+3. Introduce projections before changing navigation meaning.
+4. Extend dashboard and report datasets before creating manager and executive workspaces.
+5. Keep current APIs compatible while new read models are added beside them.
+
+## 7. Preserve / Extend / Refactor / Replace Matrix
+
+| Module | Strategy | Notes |
+| --- | --- | --- |
+| Organization | Preserve | existing tenant foundation remains unchanged |
+| RBAC / Resolved CRM Access | Preserve | mandatory security boundary for all future workspaces and projections |
+| Customer | Preserve + Extend | extend current detail into Customer Workspace sections |
+| Contact | Preserve | existing sharing rules stay authoritative |
+| Lead | Preserve + Minor Enhancement | preserve split lead domain and add activity adapter / richer handoff semantics |
+| Opportunity | Preserve + Extend | forecast, hot project, event publishing, activity adapter, workspace composition |
+| Quotation | Preserve | document lifecycle owner remains unchanged |
+| Approval | Preserve | existing approval engine remains the only workflow runtime |
+| PDF / Artifact | Preserve | no duplicate document pipeline |
+| Dashboard | Preserve + Extend | expand role-specific views from current KPI base |
+| Reports | Preserve + Extend | reuse report foundation for manager/executive read models |
+| Notification | Preserve + Extend | extend event coverage beyond approval |
+| Activity | New Capability | shared operational work model |
+| Timeline | New Projection | generated view only |
+| Calendar | New Projection | generated view only |
+| My Day | New Workspace | personalized action workspace |
+| Manager Workspace | New Workspace | control-tower composition |
+| Executive Workspace | New Workspace | strategic composition |
+| Existing admin `/dashboard/workspaces` | Preserve | reserved for organization administration, not business-role workspaces |
+| Replace | None approved | no production module currently justifies full replacement |
+
+## 8. Capability Transition Matrix
+
+| Capability | Current State | Transition Strategy | Migration Required | Backward Compatible | Risk |
+| --- | --- | --- | --- | --- | --- |
+| Customer Workspace | partial | extend current customer detail tabs and summary sections | yes | yes | medium |
+| Shared Activity | missing / contract-only | create new domain and adapt existing follow-up seams | yes | yes | high |
+| Timeline | missing | build generated read model over events and activities | yes | yes | medium |
+| Calendar Workspace | missing | build projection query + workspace UI over activity and milestones | yes | yes | medium |
+| My Day | missing | compose activity, approval, hot project, reminder signals | yes | yes | medium |
+| Manager Workspace | missing | extend dashboard + team calendar + overdue/idle datasets | yes | yes | medium |
+| Executive Workspace | missing | extend reports + dashboard + strategic customer signals | yes | yes | medium |
+| Notification Expansion | approval-centric | add activity/opportunity/quotation event publishers | yes | yes | medium |
+| Forecast Semantics | partial | preserve fields, freeze business meaning, expose via projections | no schema | yes | low |
+| Relationship Health | missing | new derived model in customer workspace | yes | yes | medium |
+
+## 9. Activity Platform Architecture
+
+### 9.1 Domain role
+
+`Activity` becomes the shared operational work record for customer-, lead-, opportunity-, quotation-, and internal-only execution.
+
+### 9.2 Ownership model
+
+- one activity has one accountable owner
+- one activity may also have one assignee
+- one activity has one primary reference
+- one activity may include many related references
+- visibility inherits from the primary record plus assignment rules
+
+### 9.3 Service architecture
+
+| Component | Responsibility |
+| --- | --- |
+| Activity Route Handlers | validate payload, require permissions, call activity service, map response |
+| Activity Service | lifecycle rules, ownership rules, next-action suggestions, event publication |
+| Activity Persistence Adapter | Drizzle-backed persistence module behind the service |
+| Activity Projection Adapter | map activity changes into timeline and calendar projections |
+| Activity Security Adapter | reuse resolved CRM access for scope validation |
+
+### 9.4 Repository rule
+
+This repo should not introduce a heavyweight new repository abstraction layer. `Activity Repository` in AR.1 means the internal Drizzle-backed persistence adapter owned by the Activity server service, consistent with existing repo service-layer patterns.
+
+### 9.5 API boundary
+
+Recommended future routes:
+
+- `GET /api/crm/activities`
+- `POST /api/crm/activities`
+- `GET /api/crm/activities/[id]`
+- `PATCH /api/crm/activities/[id]`
+- `POST /api/crm/activities/[id]/complete`
+- `POST /api/crm/activities/[id]/cancel`
+- `POST /api/crm/activities/[id]/reassign`
+
+### 9.6 Lifecycle
+
+```text
+Planned -> In Progress -> Completed
+Planned -> Cancelled
+In Progress -> Cancelled
+Overdue = derived operational view only
+Rescheduled = event, not standalone lifecycle owner
+```
+
+### 9.7 Integration points
+
+| Source / Consumer | Integration Rule |
+| --- | --- |
+| Customer | activities may attach to customer/contact relationship work |
+| Lead | existing lead follow-up becomes an adapter candidate, not a second source of truth |
+| Opportunity | opportunity follow-up is the first high-value migration seam |
+| Quotation | quotation chase and commercial follow-up adapt into Activity |
+| Notification | assignment, due soon, overdue, escalation, reminder |
+| Calendar | scheduled activities and reminders project into calendar |
+| Timeline | activity create/assign/reschedule/complete/cancel publish generated timeline items |
+| Dashboard / My Day | read operational workload and overdue signals from activity views |
+
+### 9.8 Transition rule
+
+Existing lead/opportunity/quotation follow-up APIs remain production-compatible during migration. Activity arrives beside them first, then adapters and dual-read views are introduced before any storage consolidation is attempted.
+
+## 10. Timeline Projection Architecture
+
+### 10.1 Source model
+
+Timeline is generated from:
+
+- activity lifecycle events
+- lead creation / assignment / handoff events
+- opportunity assignment, forecast, hot-project, and outcome events
+- quotation creation, revision, send, approval, acceptance, rejection, and expiry-adjacent events
+- approval actions
+- attachment / approved-artifact events
+- customer owner and contact-sharing governance events where relationship context matters
+
+### 10.2 Generator design
+
+| Component | Responsibility |
+| --- | --- |
+| Timeline Source Adapters | map source-domain rows and events into a common timeline item contract |
+| Timeline Generator | merge, normalize, sort, and tie-break timeline items |
+| Timeline Query Service | apply security, filters, paging, and caching |
+| Timeline Serializer | shape business-readable chronology for Customer/Opportunity/Quotation workspaces |
+
+### 10.3 Frozen rules
+
+- timeline is generated, never manually edited
+- timeline does not own workflow state
+- timeline visibility follows originating record access
+- pricing-sensitive timeline items must respect quotation pricing visibility
+
+### 10.4 Query strategy
+
+Phase 1:
+
+- query-time generation from source domains and activity/event adapters
+- no new timeline source-of-truth table required
+
+Phase 2, only if needed for scale:
+
+- optional cached projection table or materialized read store
+- cache remains derivative, rebuildable, and non-authoritative
+
+### 10.5 Security strategy
+
+- use resolved CRM access before source data is merged
+- pricing-sensitive quotation items are redacted for unauthorized readers
+- approval timeline visibility inherits approval boundary plus quotation access rules
+
+### 10.6 Caching strategy
+
+- cache by `organizationId + workspace + source record`
+- invalidate from source-domain event publication
+- never allow cache to become the only persisted business history
+
+### 10.7 Event mapping
+
+Minimum timeline events:
+
+- `activity.created`
+- `activity.reassigned`
+- `activity.rescheduled`
+- `activity.completed`
+- `activity.cancelled`
+- `lead.created`
+- `lead.assigned`
+- `lead.handoff_ready`
+- `opportunity.created`
+- `opportunity.reassigned`
+- `opportunity.expected_award_changed`
+- `opportunity.hot_project_flagged`
+- `opportunity.won`
+- `opportunity.lost`
+- `quotation.created`
+- `quotation.revised`
+- `quotation.sent`
+- `quotation.pending_approval`
+- `quotation.approved`
+- `quotation.rejected`
+- `quotation.returned`
+- `approval.completed`
+- `po.received`
+
+## 11. Calendar Projection Architecture
+
+### 11.1 Source model
+
+Calendar aggregates:
+
+- scheduled activities
+- reminder prompts
+- opportunity milestone dates
+- quotation milestone dates
+- approval due and escalation events
+- hot-project-sensitive near-term commitments
+
+### 11.2 Projection model
+
+| Projection Type | Owner | Notes |
+| --- | --- | --- |
+| Activity Projection | Activity | owned work, meetings, visits, tasks |
+| Reminder Projection | Activity / notification timing | visible prompt, not new work owner |
+| Milestone Projection | opportunity / quotation | expected-award, expected-delivery, validity, PO milestone |
+| Approval Projection | approval runtime | due, escalated, timeout-sensitive pending step |
+| Forecast Projection | opportunity | management awareness, not task ownership |
+
+### 11.3 Aggregation rules
+
+- activity events are first-class actionable rows
+- milestone events are visually distinct and not editable as activities
+- reminder prompts may render separately from the activity row when configured
+- manager and executive lenses are filtered calendar views, not separate source stores
+
+### 11.4 Filter strategy
+
+Required filters:
+
+- user
+- team
+- branch
+- customer
+- lead
+- opportunity
+- quotation
+- activity type
+- priority
+- status
+- Hot Project only
+
+### 11.5 Permission strategy
+
+- personal calendar shows owned/assigned activity and permitted milestones
+- team/manager calendar reuses resolved CRM access and future team graph rules
+- executive calendar is read-oriented and should not widen source-record access
+
+### 11.6 Query strategy
+
+Phase 1:
+
+- build a calendar aggregation service over Activity plus source-domain milestone fields
+- no separate scheduling domain table
+
+Phase 2, optional:
+
+- add optimized read-model caching when activity volume requires it
+
+## 12. Business Event Architecture
+
+### 12.1 Event philosophy
+
+Business events are immutable facts emitted after successful state change. One event may fan out to timeline, calendar, dashboard, notification, reminder, and future automation.
+
+### 12.2 Publisher ownership
+
+| Event Family | Publisher Owner |
+| --- | --- |
+| relationship.* | customer/contact service |
+| lead.* | lead service |
+| opportunity.* | opportunity service |
+| quotation.* | quotation service |
+| approval.* | approval service |
+| activity.* | activity service |
+
+### 12.3 Subscriber ownership
+
+| Consumer | Responsibility |
+| --- | --- |
+| Timeline | chronology projection |
+| Calendar | schedule and milestone projection |
+| Notification | inbox delivery and reminder prompts |
+| Dashboard / Workspace | aggregated operational signals |
+| Audit | mutation truth remains mandatory even when event also exists |
+| Future Automation | SLA, escalation, next-step suggestion, health monitoring |
+
+### 12.4 Contract envelope
+
+Recommended event envelope:
+
+```ts
+type BusinessEvent = {
+  eventType: string;
+  schemaVersion: 1;
+  organizationId: string;
+  entityType: string;
+  entityId: string;
+  occurredAt: string;
+  actorUserId: string | null;
+  primaryRecord: { type: string; id: string };
+  relatedRecords: Array<{ type: string; id: string }>;
+  visibility: {
+    branchId?: string | null;
+    productType?: string | null;
+    pricingSensitive?: boolean;
+  };
+  attributes: Record<string, unknown>;
+};
+```
+
+### 12.5 Naming strategy
+
+- lowercase, dot-separated event names
+- stable family prefixes: `activity.*`, `lead.*`, `opportunity.*`, `quotation.*`, `approval.*`
+- preserve existing approval notification event names for backward compatibility
+
+### 12.6 Versioning strategy
+
+- start with `schemaVersion: 1` in the envelope
+- only introduce a new version when payload meaning changes incompatibly
+- avoid renaming existing approval events that already drive the notification foundation
+
+### 12.7 Payload strategy
+
+- include business-readable identifiers only when safe
+- keep pricing-bearing attributes behind source authorization
+- include enough context for projections without forcing projection services to re-query everything
+
+## 13. Workspace Architecture
+
+### 13.1 Route strategy
+
+Do not reuse `/dashboard/workspaces` for business-role workspaces because production already reserves that path for organization administration.
+
+Recommended business workspace routes:
+
+- `/dashboard/crm/my-day`
+- `/dashboard/crm/calendar`
+- `/dashboard/crm/manager`
+- `/dashboard/crm/executive`
+- `/dashboard/crm/customers/[id]` extended as Customer Workspace
+- `/dashboard/crm/opportunities` and `/dashboard/crm/quotations` remain the sales execution backbone
+
+### 13.2 Workspace composition
+
+| Workspace | Primary Composition | Source Domains |
+| --- | --- | --- |
+| Customer Workspace | customer profile, contacts, upcoming work, activities, timeline, leads, opportunities, quotations, files | customer, contact, lead, opportunity, quotation, activity, timeline |
+| Sales Workspace | my-day signals, opportunity queue, quotation blockers, customer context | activity, opportunity, quotation, approval, customer |
+| Manager Workspace | overdue work, idle opportunities, team calendar, approvals, forecast, hot projects | activity, calendar, dashboard, reports, approval |
+| Executive Workspace | revenue outlook, strategic accounts, pipeline health, exception review | dashboard, reports, relationship health, timeline summaries |
+| Calendar Workspace | personal, team, manager, executive time lenses | activity, reminders, milestone projections, approval due events |
+| My Day | today's activities, overdue items, meetings, urgent quotations, approvals, relationship alerts | activity, approval, quotation, hot project, relationship signals |
+
+### 13.3 Navigation boundary
+
+- preserve existing entity routes
+- add workspace routes as composition surfaces, not replacements for source modules
+- keep Customer Workspace anchored on the existing customer detail route
+
+## 14. Integration Strategy
+
+| Concern | Strategy |
+| --- | --- |
+| Existing module reuse | extend customers, leads, opportunities, quotations, dashboard, reports, notifications; do not fork them |
+| Adapter layer | build follow-up adapters before any shared activity migration |
+| Projection layer | implement timeline/calendar as read-only aggregation services first |
+| Service composition | projections call owning services or datasets instead of bypassing them |
+| Shared components | reuse `PageContainer`, existing table/filter shells, and CRM detail patterns |
+| API compatibility | add new read routes; keep current lead/opportunity/quotation APIs stable |
+| Feature flags | optional for workspace rollout and projection swaps, especially timeline/calendar |
+| Migration strategy | dual-read/adapter-first, then storage convergence only when safe |
+
+## 15. Domain Dependency Graph
+
+```mermaid
+flowchart TD
+  Customer[Customer]
+  Contact[Contact]
+  Lead[Lead]
+  Activity[Activity]
+  Opportunity[Opportunity]
+  Quotation[Quotation]
+  Approval[Approval]
+  Timeline[Timeline]
+  Calendar[Calendar]
+  Dashboard[Dashboard]
+  Reports[Reports]
+  Notification[Notification]
+  MyDay[My Day]
+  Manager[Manager Workspace]
+  Executive[Executive Workspace]
+
+  Customer --> Contact
+  Customer --> Lead
+  Customer --> Opportunity
+  Customer --> Quotation
+  Contact --> Lead
+  Contact --> Activity
+  Lead --> Opportunity
+  Opportunity --> Quotation
+  Quotation --> Approval
+  Activity --> Timeline
+  Activity --> Calendar
+  Opportunity --> Dashboard
+  Quotation --> Dashboard
+  Approval --> Dashboard
+  Opportunity --> Reports
+  Quotation --> Reports
+  Approval --> Notification
+  Activity --> Notification
+  Timeline --> MyDay
+  Calendar --> MyDay
+  Dashboard --> Manager
+  Calendar --> Manager
+  Reports --> Executive
+  Dashboard --> Executive
+```
+
+## 16. Domain Dependency Matrix
+
+| Domain | Depends On | Used By | Shared Services | Projection Consumers | Potential Breaking Change Impact |
+| --- | --- | --- | --- | --- | --- |
+| Customer | foundation, security | contact, lead, opportunity, quotation, customer workspace | ownership, sharing, option lookup | timeline, dashboard, manager, executive | high |
+| Contact | customer | lead, activity, quotation follow-up | contact sharing | customer workspace, timeline | medium |
+| Activity | customer, contact, lead, opportunity, quotation, security | calendar, timeline, My Day, notifications, manager workspace | notification, audit, security | calendar, timeline, My Day, dashboard | very high |
+| Lead | customer, contact, security | opportunity, customer workspace, reports | assignment, audit | timeline, customer workspace | high |
+| Opportunity | customer, lead, security | quotation, dashboard, reports, manager workspace | hot project, outcome, follow-up | calendar, timeline, dashboard | very high |
+| Quotation | opportunity, customer, security | approval, PDF, dashboard, reports | document, revision, customer package | timeline, calendar, My Day | very high |
+| Approval | quotation, role assignments, security | notification, dashboard, manager workspace | reminder/escalation, audit | timeline, calendar, manager workspace | high |
+| Timeline | business events, activities | customer workspace, My Day, manager/executive drill-down | projection generator | customer, sales, manager, executive | medium |
+| Calendar | activity + milestones + approvals | My Day, Manager Workspace | projection query, reminder rules | personal/team/manager/executive | medium |
+| Dashboard | opportunity + quotation + approval + follow-up/activity | manager, executive | reporting helpers, security | manager, executive | high |
+
+### Coupling analysis
+
+1. `Opportunity -> Quotation -> Approval` is the strongest existing operational chain and must remain stable.
+2. `Customer` is the relationship anchor and should stay the main shared-reference root, not be duplicated in workspaces.
+3. `Activity` will become the main cross-cutting coupling point, so it must remain reference-based and projection-friendly instead of embedding duplicate lifecycle fields.
+4. `Dashboard` and `Reports` already depend on follow-up-like signals. Activity migration must preserve those datasets without KPI regressions.
+
+### High-risk dependency list
+
+- opportunity follow-up analytics currently drive dashboard behavior
+- quotation follow-up analytics currently drive dashboard behavior
+- approval notification events already exist and can be double-published if event layering is careless
+- current admin `workspaces` route meaning can be broken by navigation overloading
+- pricing-sensitive quotation data can leak if timeline/calendar/event payloads ignore security boundaries
+
+### Recommended decoupling strategy
+
+- introduce Activity adapters instead of immediate follow-up replacement
+- keep event fan-out behind source-service publishers
+- centralize timeline/calendar security in shared projection query services
+- preserve dashboard/report dataset contracts during activity transition
+
+## 17. Breaking Change Assessment
+
+| Area | Risk | Why | Mitigation |
+| --- | --- | --- | --- |
+| Follow-up migration | high | dashboard/report/current tabs already depend on existing follow-up storage | adapter-first, dual-read, explicit dataset regression checks |
+| Workspace navigation | medium | `/dashboard/workspaces` already has admin meaning | use `/dashboard/crm/*` for business workspaces |
+| Notification fan-out | medium | approval event pipeline already exists | preserve approval events, add new event families incrementally |
+| Timeline security | high | cross-entity chronology may surface pricing or restricted records | centralize source-security checks and pricing redaction |
+| Calendar milestones | medium | milestone dates come from several owners | keep milestone projections read-only and source-owned |
+| Customer Workspace expansion | low | current customer detail already provides a strong base | extend existing route and detail composition gradually |
+
+## 18. Migration Strategy
+
+### Preserve
+
+- organization and workspace-admin foundation
+- resolved CRM authorization
+- customer ownership and contact sharing
+- lead domain split
+- opportunity outcome governance
+- quotation lifecycle, approval runtime, PDF/artifact, reports, dashboard
+
+### Extend
+
+- customer detail into Customer Workspace
+- dashboard into manager/executive decision views
+- notifications into broader operational event coverage
+- forecast and Hot Project semantics into calendar/workspace projections
+
+### Controlled Refactor
+
+- follow-up semantics toward shared Activity
+- event publication as a reusable source-service concern
+- route/nav wording so business workspaces do not collide with admin workspaces
+
+### Replace
+
+- none approved in AR.1
+
+## 19. Epic Roadmap
+
+| Order | Epic | Why First / Dependency |
+| --- | --- | --- |
+| 1 | Activity Platform Foundation | unlocks timeline, calendar, My Day, manager signals |
+| 2 | Business Event Publishing Expansion | required for projections and notification breadth |
+| 3 | Customer Workspace | strongest existing base and relationship anchor |
+| 4 | Timeline Projection | consumes activity + event contracts |
+| 5 | Calendar Projection and Workspace | depends on activity and milestone mapping |
+| 6 | My Day Workspace | depends on activity, approvals, reminders, hot projects |
+| 7 | Manager Workspace | depends on calendar, dashboard extension, approvals, forecast |
+| 8 | Notification Expansion | grows with activity and manager workflows |
+| 9 | Executive Workspace | depends on dashboard/report/relationship health layering |
+| 10 | Relationship Health and Forecast Refinements | safer after core projections and workspaces exist |
+
+## 20. Official Architecture Governance Outcome
+
+AR.1 freezes these transition rules:
+
+1. Preserve current production CRM source domains.
+2. Add Activity as a new shared operational domain, not a shortcut rewrite of existing modules.
+3. Treat Timeline and Calendar as generated projections only.
+4. Keep Approval as the quotation/document workflow owner.
+5. Keep Opportunity as the business outcome owner.
+6. Keep business-role workspaces under CRM routes and preserve the existing admin workspaces route meaning.
+7. Require future implementation epics to reference this AR.1 baseline before modifying preserved modules.
+
+## Verification
+
+- Documentation-only change.
+- No schema, migration, API, service, UI, permission, or runtime business-logic files were changed for production behavior.
+- No build or test command was required for this architecture pass.
+
+## Outcome
+
+AR.1 now provides the transition baseline between the current production ALLA OS CRM foundation and the target Relationship-Driven Sales Workspace architecture. The baseline is implementation-ready for AR.2 because it defines the current architecture, target layering, transition strategy, ownership rules, event strategy, projection strategy, workspace routing strategy, coupling risks, and epic order without forcing unnecessary replacement of mature production modules.