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

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

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

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

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

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:

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

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.