# 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.
