# Task AR.1 – Architecture Transition Plan Status: Completed Priority: Critical Type: Solution Architecture / Transition Planning Depends On - BU-R.0 Business Blueprint Freeze - BU-R.0.1 Workspace & Activity Blueprint - BU-R.1 Business Capability Audit --- # Objective Produce the complete transition architecture from the current ALLA OS implementation to the approved Relationship-Driven Sales Operating Platform architecture. This phase defines **how** the future architecture will be introduced while preserving the existing production foundation. The primary goal is: > Preserve the current production CRM foundation and extend it through new architectural layers rather than replacing existing domains. This phase is architecture-only. No production implementation is allowed. --- # Background Business Discovery has completed. Business Blueprint has been frozen. Business Capability Audit confirms that: - Customer - Contact - Lead - Opportunity - Quotation - Approval - Organization - RBAC - PDF - Dashboard already provide a mature production foundation. The remaining gaps are primarily cross-cutting capabilities: - Activity Platform - Timeline - Calendar Workspace - My Day - Manager Workspace - Executive Workspace - Business Event Architecture AR.1 defines how these capabilities are introduced without breaking the existing architecture. --- # Architecture Principles Every proposal must follow: ## Preserve Before Replace Reuse existing production domains whenever possible. --- ## Extension Before Refactor Prefer adding new architectural layers. Avoid modifying existing domains unless unavoidable. --- ## Single Source of Truth Every business concept must have one owner. No duplicated lifecycle. No duplicated status. No duplicated business meaning. --- ## Projection over Duplication Timeline Calendar Dashboard Notification must consume projections instead of storing duplicated business data. --- ## Backward Compatibility First Existing APIs Existing UI Existing Schema must remain compatible unless a controlled migration is explicitly approved. --- # Review Required Review - Business Constitution - BU-R.1 Capability Audit - Current Schema - Current CRM Modules - Current Foundation Modules - Existing API Contracts - Existing Permission Model - Existing Notification Foundation - Existing Approval Runtime - Existing Dashboard - Existing PDF Engine --- # Scope ## Part 1 — Current Architecture Map Document the current architecture. Identify Relationship Layer CRM Layer Foundation Layer Reporting Layer Notification Layer Approval Layer Storage Layer Security Layer Document Responsibilities Ownership Dependencies Extension points --- ## Part 2 — Target Architecture Produce the target architecture. Include Relationship Layer Activity Layer Project Layer Commercial Layer Workspace Layer Analytics Layer Foundation Layer Security Layer Document Responsibilities Boundaries Ownership Interaction --- ## Part 3 — Transition Architecture Design the transition path. For every capability determine Preserve Extend Refactor Replace Migration Required Backward Compatible Breaking Change Risk --- ## Part 4 — Activity Platform Architecture Define Activity Domain Activity Service Activity Repository Activity API Activity Projection Activity Ownership Activity Lifecycle Integration with Customer Lead Opportunity Quotation Notification Calendar Timeline Dashboard --- ## Part 5 — Timeline Projection Architecture Define Timeline Source Timeline Generator Timeline Projection Timeline Query Timeline Security Timeline Caching Timeline Event Mapping Confirm Timeline is generated. Timeline is never manually edited. --- ## Part 6 — Calendar Projection Architecture Define Calendar Source Activity Projection Milestone Projection Reminder Projection Approval Projection Forecast Projection Calendar Aggregation Calendar Filters Calendar Permissions Calendar Query Strategy --- ## Part 7 — Business Event Architecture Freeze Domain Event Ownership Business Event Types Publisher Subscriber Timeline Consumer Dashboard Consumer Notification Consumer Automation Consumer Determine Event Contracts Event Naming Event Versioning Event Payload Strategy --- ## Part 8 — Workspace Architecture Design Customer Workspace Sales Workspace Manager Workspace Executive Workspace Calendar Workspace My Day Navigation Permission Boundary Workspace Composition --- ## Part 9 — Integration Strategy Determine Existing Module Reuse Adapter Layer Projection Layer Service Composition Shared Components API Compatibility Feature Flags Migration Strategy --- ## Part 10 — Implementation Strategy Group implementation into Epics. Example Epic Activity Platform Epic Timeline Projection Epic Calendar Workspace Epic Customer Workspace Epic Manager Workspace Epic My Day Epic Business Events Epic Notification Expansion Epic Forecast Enhancement --- # Deliverables Produce ## 1 Current Architecture Diagram --- ## 2 Target Architecture Diagram --- ## 3 Transition Architecture Diagram --- ## 4 Domain Ownership Matrix --- ## 5 Layer Responsibility Matrix --- ## 6 Business Event Architecture --- ## 7 Activity Architecture --- ## 8 Timeline Projection Architecture --- ## 9 Calendar Projection Architecture --- ## 10 Workspace Architecture --- ## 11 Dependency Graph --- ## 12 Migration Strategy Categorize Preserve Extend Refactor Replace --- ## 13 Breaking Change Assessment Risk Mitigation Compatibility --- ## 14 Epic Roadmap Priority Dependency Estimated Order --- ## 15. Domain Dependency Matrix Produce a dependency matrix describing how each business domain depends on and is consumed by other domains. The objective is to visualize architectural coupling before implementation begins. For every major domain identify: - Domain Owner - Depends On - Used By - Shared Services - Projection Consumers - Potential Breaking Change Impact Minimum domains: | Domain | Depends On | Used By | |----------|------------|---------| | Customer | Foundation | Contact, Activity, Lead, Opportunity | | Contact | Customer | Activity, Lead | | Activity | Customer, Contact, Lead, Opportunity, Quotation | Calendar, Timeline, My Day, Notification | | Lead | Customer | Opportunity | | Opportunity | Customer, Lead | Quotation, Dashboard, Forecast | | Quotation | Opportunity | Approval, PDF, Timeline | | Approval | Quotation | Notification | | Timeline | Business Events | Customer Workspace | | Calendar | Activity + Milestones | My Day, Manager Workspace | | Dashboard | Opportunity + Activity + Events | Manager, Executive | Deliverables - Domain Dependency Diagram - Domain Dependency Matrix - Coupling Analysis - High-Risk Dependency List - Recommended Decoupling Strategy --- ## 16. Preserve / Extend / Refactor Matrix Produce the official architectural transition strategy for every major module. Every module must be classified into one of the following categories: - Preserve - Preserve + Extend - Controlled Refactor - New Capability - Replace (only if explicitly justified) The objective is to minimize disruption to the existing production architecture. Minimum matrix: | Module | Strategy | Notes | |----------|----------|-------| | Organization | Preserve | Core Foundation | | RBAC | Preserve | Existing Permission Model | | Customer | Preserve + Extend | Add Customer Workspace capabilities | | Contact | Preserve | Existing Sharing Rules | | Lead | Preserve + Minor Enhancement | Align Business Blueprint | | Opportunity | Preserve + Extend | Forecast, Activity, Hot Project | | Quotation | Preserve | Document Lifecycle Owner | | Approval | Preserve | Existing Approval Engine | | PDF | Preserve | Existing Document Engine | | Dashboard | Preserve + Extend | Business-driven Metrics | | Notification | Preserve + Extend | Consume Business Events | | Activity | New Capability | Shared Operational Domain | | Timeline | New Projection | Generated View | | Calendar | New Projection | Workspace Layer | | My Day | New Workspace | Personalized Operational Workspace | | Manager Workspace | New Workspace | Operational Control Tower | | Executive Workspace | New Workspace | Strategic Monitoring | Deliverables - Preserve Matrix - Extension Matrix - Refactor Matrix - New Capability Matrix - Breaking Change Impact Matrix - Migration Recommendation Frozen Rule Every implementation epic after AR.1 must explicitly reference this matrix before modifying any production module. If a proposed implementation changes a module classified as "Preserve", the implementation must include an Architecture Decision Record (ADR) explaining the reason, impact analysis, rollback strategy, and backward compatibility assessment. # Constraints This phase is architecture only. DO NOT - modify schema - modify migrations - modify APIs - modify services - modify UI - modify permissions - modify business logic No production implementation is allowed. --- # Success Criteria A complete transition architecture exists. Every new capability has a defined architectural location. Every existing capability has a preservation strategy. Every integration point is documented. Every migration path is documented. Breaking changes are minimized. Core CRM foundation remains preserved. Architecture is implementation-ready. Ready for AR.2 – Epic & Technical Design ## Architecture Governance Rule AR.1 becomes the official architecture transition baseline. Every future Epic, ADR, schema change, API change, or implementation task must reference: - Business Constitution (BU-R.0 / BU-R.0.1) - Business Capability Audit (BU-R.1) - Architecture Transition Plan (AR.1) Any implementation that violates the approved transition strategy must provide explicit architectural justification and receive governance approval before implementation begins.