ar2
This commit is contained in:
phaichayon
Binary file not shown.
Binary file not shown.
@@ -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.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Task AR.1 Implementation Report - 2026-07-07
|
||||
|
||||
## Scope
|
||||
|
||||
- start and complete AR.1 as a documentation-only architecture transition phase
|
||||
- review the frozen BU-R business baseline, current production CRM implementation, reusable foundations, ADRs, security boundaries, and transition seams
|
||||
- record the official transition architecture baseline for later AR.2 epics and technical design
|
||||
|
||||
## What Was Produced
|
||||
|
||||
- created the main AR.1 transition architecture artifact:
|
||||
[task-ar.1-architecture-transition-plan-2026-07-07.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-ar.1-architecture-transition-plan-2026-07-07.md)
|
||||
|
||||
## Key Decisions Captured
|
||||
|
||||
1. Current production CRM domains remain the write owners and must be preserved.
|
||||
2. New capability should arrive as:
|
||||
- shared `Activity` domain
|
||||
- generated `Timeline` projection
|
||||
- generated `Calendar` projection
|
||||
- role-oriented CRM workspaces
|
||||
3. Existing admin `/dashboard/workspaces` routes are preserved for organization administration and must not be silently reused for business-role workspace navigation.
|
||||
4. `Approval` stays the document workflow owner, `Opportunity` stays the business outcome owner, and `Quotation` stays the document lifecycle owner.
|
||||
5. Notification expansion, My Day, Manager Workspace, and Executive Workspace must build on event/projection layers rather than creating duplicate lifecycle stores.
|
||||
|
||||
## Verification
|
||||
|
||||
- Documentation-only change.
|
||||
- No schema, API, UI, service, permission, or business-logic runtime change was made.
|
||||
- No build or test command was required for this phase.
|
||||
|
||||
## Outcome
|
||||
|
||||
AR.1 is now recorded as the architecture transition baseline that future epics can reference for preserve/extend/refactor decisions, event design, projection strategy, workspace routing, dependency analysis, and implementation ordering.
|
||||
@@ -0,0 +1,607 @@
|
||||
# Task AR.2 Epic & Technical Design Baseline - 2026-07-07
|
||||
|
||||
## Scope
|
||||
|
||||
- convert the AR.1 transition architecture into an implementation-ready epic and technical-design baseline
|
||||
- define epic boundaries, dependency order, delivery slices, technical contracts, and reuse rules for each AR.1 capability
|
||||
- include workspace-design prerequisites and design-governance checkpoints before code implementation begins
|
||||
- keep this phase documentation-only with no schema, API, UI, service, permission, or runtime business-logic changes
|
||||
|
||||
## Review Summary
|
||||
|
||||
Reviewed before drafting AR.2:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `plans/task-ar.2.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`
|
||||
- `layout.md`
|
||||
- `docs/business/relationship-sales-workspace-blueprint-v1.md`
|
||||
- `docs/implementation/task-bu-r.1-business-capability-audit-2026-07-07.md`
|
||||
- `docs/implementation/task-ar.1-architecture-transition-plan-2026-07-07.md`
|
||||
- `docs/implementation/task-ar.1-implementation-report-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`
|
||||
- `plans/task-j.md`
|
||||
- `plans/task-d.md`
|
||||
- `src/components/layout/page-container.tsx`
|
||||
- `src/features/crm/dashboard/components/crm-dashboard.tsx`
|
||||
- `src/features/crm/customers/components/customer-detail.tsx`
|
||||
- `src/features/crm/reports/components/pipeline-report-view.tsx`
|
||||
|
||||
UI/UX design process inputs:
|
||||
|
||||
- `.agents/skills/ui-ux-pro-max/SKILL.md`
|
||||
- `python .agents/skills/ui-ux-pro-max/scripts/search.py "relationship driven sales workspace enterprise crm operational dashboard" --design-system -f markdown -p "ALLA OS CRM Workspaces"`
|
||||
- `python .agents/skills/ui-ux-pro-max/scripts/search.py "dashboard information hierarchy filters empty loading" --domain ux -n 12`
|
||||
- `python .agents/skills/ui-ux-pro-max/scripts/search.py "minimalism enterprise dashboard" --domain style -n 8`
|
||||
- `python .agents/skills/ui-ux-pro-max/scripts/search.py "analytics dashboard operational crm" --domain chart -n 10`
|
||||
|
||||
## AR.2 Objective
|
||||
|
||||
AR.2 turns AR.1 from architecture baseline into delivery baseline. The result of AR.2 is not code. The result is a frozen set of implementation epics and technical-design contracts that future work must follow.
|
||||
|
||||
AR.2 therefore answers:
|
||||
|
||||
1. Which epic comes first and why.
|
||||
2. Which existing modules and foundations each epic must reuse.
|
||||
3. Which new routes, services, query layers, and UI shells are expected.
|
||||
4. Which schema/API risks exist before implementation starts.
|
||||
5. Which workspace surfaces require dedicated UI/UX notes before coding.
|
||||
|
||||
## Implementation Principles Carried Forward
|
||||
|
||||
1. Preserve current production write owners: Customer, Contact, Lead, Opportunity, Quotation, Approval.
|
||||
2. Introduce Activity, Timeline, Calendar, and role workspaces as extensions and projections.
|
||||
3. Keep route handlers thin and business logic in feature/foundation server services.
|
||||
4. Reuse resolved CRM access, approval, report, notification, audit, PDF, and artifact foundations.
|
||||
5. Preserve current admin `/dashboard/workspaces` meaning; business workspaces live under `/dashboard/crm/*`.
|
||||
6. Do not start any major workspace UI implementation without an approved UI/UX design note.
|
||||
|
||||
## Delivery Model
|
||||
|
||||
AR.2 groups future work into three layers of implementation:
|
||||
|
||||
| Layer | Purpose | Epics |
|
||||
| --- | --- | --- |
|
||||
| Foundational Runtime | create shared operational primitives | Activity Platform, Business Event Expansion |
|
||||
| Projection Layer | create generated read models | Timeline Projection, Calendar Projection |
|
||||
| Workspace Layer | create user-facing operational surfaces | Customer Workspace, My Day, Manager Workspace, Executive Workspace |
|
||||
|
||||
Supporting alignment epics:
|
||||
|
||||
- Lead Handoff & Outcome Alignment
|
||||
- Relationship Health & Forecast Semantics
|
||||
- Notification Expansion
|
||||
- Terminology & Governance Reconciliation
|
||||
|
||||
## Epic Sequencing
|
||||
|
||||
| Order | Epic | Reason |
|
||||
| --- | --- | --- |
|
||||
| 1 | Activity Platform Foundation | unblocks Timeline, Calendar, My Day, Manager signals, and notification expansion |
|
||||
| 2 | Business Event Publishing Expansion | creates shared event contracts and projection fan-out |
|
||||
| 3 | Customer Workspace Enhancement | strongest partial base and least risky visible value |
|
||||
| 4 | Timeline Projection | depends on Activity + event publishing |
|
||||
| 5 | Calendar Projection & Workspace | depends on Activity + milestone mapping + event contracts |
|
||||
| 6 | My Day Workspace | depends on Activity + Calendar + Approval + Hot Project signals |
|
||||
| 7 | Notification Expansion | safer after event taxonomy and activity lifecycle exist |
|
||||
| 8 | Manager Workspace | depends on Calendar, Dashboard, Timeline, My Day patterns |
|
||||
| 9 | Executive Workspace | depends on Dashboard + Reports + Relationship Health summaries |
|
||||
| 10 | Lead Handoff & Outcome Alignment | can proceed alongside workspace work, but should preserve current Lead foundation |
|
||||
| 11 | Relationship Health & Forecast Semantics | finalizes derived scoring and naming after projections exist |
|
||||
| 12 | Terminology & Governance Reconciliation | ongoing cross-epic cleanup with low runtime dependency |
|
||||
|
||||
## Epic Overview Matrix
|
||||
|
||||
| Epic | Type | Main Output | Depends On | Reuses | Risk |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Activity Platform Foundation | new capability | shared activity domain | none | security, audit, notifications, customers, leads, opportunities, quotations | high |
|
||||
| Business Event Publishing Expansion | extension | event envelope + publisher rules | none | approval notifications, audit, source services | medium |
|
||||
| Customer Workspace Enhancement | preserve + extend | relationship execution workspace | AR.1 only | customer detail, related opportunity/quotation links, audit tab | medium |
|
||||
| Timeline Projection | new projection | generated chronology read model | Activity + Events | audit naming, source services, CRM security | high |
|
||||
| Calendar Projection & Workspace | new projection + workspace | cross-role time view | Activity + Events | approval automation, dashboard filter patterns, PageContainer | high |
|
||||
| My Day Workspace | new workspace | personalized action home | Activity + Calendar + Approval | dashboard cards, report filters, notification signals | medium |
|
||||
| Notification Expansion | preserve + extend | broader operational event coverage | Events + Activity | notification foundation, templates, recipient resolver | medium |
|
||||
| Manager Workspace | new workspace | team control tower | Calendar + My Day + Dashboard | dashboard foundation, reports, approvals | medium |
|
||||
| Executive Workspace | new workspace | strategic monitoring surface | Manager dependencies partly complete | dashboard, reports, relationship summaries | medium |
|
||||
| Lead Handoff & Outcome Alignment | enhancement | richer lead-to-opportunity flow | Activity optional | lead foundation, opportunity links, CRM access | medium |
|
||||
| Relationship Health & Forecast Semantics | enhancement | derived health/forecast views | Timeline + Activity + Customer Workspace | customer, opportunity, quotation, dashboard | medium |
|
||||
| Terminology & Governance Reconciliation | controlled refactor | docs and naming cleanup | none | blueprint, ADRs, current routes | low |
|
||||
|
||||
## Technical Design Standards for Every Epic
|
||||
|
||||
Each future implementation epic under AR.2 must include:
|
||||
|
||||
1. objective and explicit non-goals
|
||||
2. historical review section
|
||||
3. foundations reused
|
||||
4. API boundary
|
||||
5. service-layer contract
|
||||
6. query/mutation design
|
||||
7. permission and pricing boundary
|
||||
8. audit events
|
||||
9. UI/UX design note reference if the epic includes user-facing workspace surfaces
|
||||
10. verification plan
|
||||
|
||||
## EPIC 1: Activity Platform Foundation
|
||||
|
||||
### Objective
|
||||
|
||||
Introduce the first production-grade shared Activity domain without breaking current lead/opportunity/quotation follow-up behavior.
|
||||
|
||||
### Non-goals
|
||||
|
||||
- no replacement of current follow-up APIs on day one
|
||||
- no silent migration of dashboard/report datasets
|
||||
- no automatic removal of audit-backed lead follow-up seam
|
||||
|
||||
### Existing foundations to reuse
|
||||
|
||||
- `src/lib/auth/crm-access.ts`
|
||||
- `src/features/crm/security/server/service.ts`
|
||||
- `src/features/foundation/audit-log/service.ts`
|
||||
- `src/features/foundation/notifications/**`
|
||||
- `src/features/crm/customers/**`
|
||||
- `src/features/crm/leads/**`
|
||||
- `src/features/crm/opportunities/**`
|
||||
- `src/features/crm/quotations/**`
|
||||
- `src/features/crm/activity/types.ts`
|
||||
|
||||
### Recommended implementation structure
|
||||
|
||||
```text
|
||||
src/features/crm/activities/
|
||||
api/
|
||||
types.ts
|
||||
service.ts
|
||||
queries.ts
|
||||
mutations.ts
|
||||
components/
|
||||
schemas/
|
||||
server/
|
||||
service.ts
|
||||
adapters/
|
||||
lead-followup.adapter.ts
|
||||
opportunity-followup.adapter.ts
|
||||
quotation-followup.adapter.ts
|
||||
```
|
||||
|
||||
### Expected route surface
|
||||
|
||||
- `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`
|
||||
|
||||
### Minimum technical design decisions
|
||||
|
||||
- one primary record reference plus optional related references
|
||||
- owner and assignee fields
|
||||
- lifecycle states: planned, in_progress, completed, cancelled
|
||||
- overdue derived in query/view layer, not lifecycle storage
|
||||
- activity-level security resolves from primary record plus assignment
|
||||
- pricing-sensitive notes must reuse quotation pricing visibility checks
|
||||
|
||||
### Required permission set
|
||||
|
||||
- `crm.activity.read`
|
||||
- `crm.activity.create`
|
||||
- `crm.activity.update`
|
||||
- `crm.activity.complete`
|
||||
- `crm.activity.cancel`
|
||||
- `crm.activity.delete`
|
||||
- `crm.activity.reassign`
|
||||
|
||||
### Query strategy
|
||||
|
||||
- define centralized query keys in `api/queries.ts`
|
||||
- use list/detail/related-entity keys
|
||||
- keep existing follow-up queries intact during transition
|
||||
|
||||
### Migration rule
|
||||
|
||||
Phase 1 must support coexistence:
|
||||
|
||||
- existing lead follow-up
|
||||
- existing opportunity follow-up
|
||||
- existing quotation follow-up
|
||||
- new Activity records
|
||||
|
||||
No destructive cutover is allowed until dashboard/report continuity is proven.
|
||||
|
||||
### Validation and testing expectations
|
||||
|
||||
- permission tests
|
||||
- ownership and visibility tests
|
||||
- primary/related reference validation tests
|
||||
- mutation audit tests
|
||||
- notification publication smoke tests
|
||||
|
||||
## EPIC 2: Business Event Publishing Expansion
|
||||
|
||||
### Objective
|
||||
|
||||
Standardize operational business events so source services can publish shared events consumed by Timeline, Calendar, Notification, Dashboard, My Day, and future automation.
|
||||
|
||||
### Foundations to reuse
|
||||
|
||||
- approval notification event pipeline
|
||||
- audit foundation
|
||||
- source-domain service layers
|
||||
|
||||
### Technical design
|
||||
|
||||
- keep source-of-truth writes inside existing services
|
||||
- publish event only after successful mutation
|
||||
- preserve current approval event names for compatibility
|
||||
- add shared envelope with `schemaVersion`
|
||||
|
||||
### Event families
|
||||
|
||||
- `relationship.*`
|
||||
- `lead.*`
|
||||
- `opportunity.*`
|
||||
- `quotation.*`
|
||||
- `approval.*`
|
||||
- `activity.*`
|
||||
|
||||
### Implementation note
|
||||
|
||||
This epic should not replace the notification foundation with a new event bus. It should formalize a shared publisher contract and allow the existing notification event service to consume it.
|
||||
|
||||
## EPIC 3: Customer Workspace Enhancement
|
||||
|
||||
### Objective
|
||||
|
||||
Extend current customer detail into the first production Customer Workspace aligned to the business blueprint.
|
||||
|
||||
### Starting point
|
||||
|
||||
- `src/features/crm/customers/components/customer-detail.tsx`
|
||||
- existing related opportunities and quotations
|
||||
- owner card
|
||||
- contacts tab
|
||||
- audit log tab
|
||||
|
||||
### Required new sections
|
||||
|
||||
- Relationship Health
|
||||
- Upcoming Activities
|
||||
- Activities
|
||||
- Timeline
|
||||
- PO / Won History
|
||||
- Files / Documents
|
||||
- Relationship Summary / Notes
|
||||
|
||||
### Technical design
|
||||
|
||||
- preserve current `/dashboard/crm/customers/[id]` route
|
||||
- extend the existing detail shell rather than replacing it
|
||||
- add new tabs/cards fed by Activity and Timeline projections when available
|
||||
- relationship health remains derived, not manually editable
|
||||
|
||||
### Dependency
|
||||
|
||||
Can start before Activity/Timeline are complete by using placeholders or staged sections, but final implementation depends on those epics.
|
||||
|
||||
## EPIC 4: Timeline Projection
|
||||
|
||||
### Objective
|
||||
|
||||
Create a generated chronology layer for Customer, Opportunity, Quotation, and later Lead contexts.
|
||||
|
||||
### Technical design
|
||||
|
||||
- query-time read model first
|
||||
- source adapters per domain
|
||||
- deterministic ordering and tie-break rules
|
||||
- no manual timeline CRUD
|
||||
- no timeline table as source-of-truth in phase 1
|
||||
|
||||
### Recommended server structure
|
||||
|
||||
```text
|
||||
src/features/crm/timeline/
|
||||
api/
|
||||
types.ts
|
||||
service.ts
|
||||
queries.ts
|
||||
server/
|
||||
service.ts
|
||||
adapters/
|
||||
activity.adapter.ts
|
||||
lead.adapter.ts
|
||||
opportunity.adapter.ts
|
||||
quotation.adapter.ts
|
||||
approval.adapter.ts
|
||||
customer.adapter.ts
|
||||
```
|
||||
|
||||
### Security rule
|
||||
|
||||
Projection service must apply source-record access and pricing redaction before returning rows.
|
||||
|
||||
## EPIC 5: Calendar Projection & Workspace
|
||||
|
||||
### Objective
|
||||
|
||||
Create a time-based operational workspace over activities, reminders, milestones, and approval due signals.
|
||||
|
||||
### Technical design
|
||||
|
||||
- new route: `/dashboard/crm/calendar`
|
||||
- day/week/month/agenda views
|
||||
- agenda is manager-friendly default view
|
||||
- milestone events are visually distinct from owned work
|
||||
- route uses server prefetch and client `useSuspenseQuery()`
|
||||
|
||||
### Sources
|
||||
|
||||
- activities
|
||||
- reminder signals
|
||||
- opportunity expected-award / expected-delivery milestones
|
||||
- quotation validity or milestone signals
|
||||
- approval due and escalation signals
|
||||
|
||||
### UI dependency
|
||||
|
||||
Must not start code before a workspace UI/UX note is approved.
|
||||
|
||||
## EPIC 6: My Day Workspace
|
||||
|
||||
### Objective
|
||||
|
||||
Create the personalized operational home screen for action-taking users.
|
||||
|
||||
### Technical design
|
||||
|
||||
- new route: `/dashboard/crm/my-day`
|
||||
- modules:
|
||||
- Today's Activities
|
||||
- Overdue Activities
|
||||
- Upcoming Meetings
|
||||
- Pending Approvals
|
||||
- Hot Projects Requiring Action
|
||||
- Urgent Quotations
|
||||
- Relationship Alerts
|
||||
|
||||
### Composition rule
|
||||
|
||||
My Day does not own data. It composes:
|
||||
|
||||
- Activity views
|
||||
- Calendar windows
|
||||
- Approval pending data
|
||||
- Hot Project signals
|
||||
- relationship health or follow-up gap signals
|
||||
|
||||
### UX rule
|
||||
|
||||
My Day must prioritize next action, not passive analytics.
|
||||
|
||||
## EPIC 7: Notification Expansion
|
||||
|
||||
### Objective
|
||||
|
||||
Extend the notification foundation from approval-centric delivery into broader operational activity and manager workflow coverage.
|
||||
|
||||
### New event coverage candidates
|
||||
|
||||
- activity assigned
|
||||
- activity due soon
|
||||
- activity overdue
|
||||
- manager escalation
|
||||
- quotation expiring soon
|
||||
- hot project flagged
|
||||
- expected award date changed
|
||||
|
||||
### Foundations to reuse
|
||||
|
||||
- `src/features/foundation/notifications/**`
|
||||
- existing recipient resolver
|
||||
- existing template system
|
||||
- existing inbox UI and React Query hooks
|
||||
|
||||
### Constraint
|
||||
|
||||
Do not widen notification writes in a way that duplicates Activity or Reminder as source-of-truth records.
|
||||
|
||||
## EPIC 8: Manager Workspace
|
||||
|
||||
### Objective
|
||||
|
||||
Create the team execution control tower for managers.
|
||||
|
||||
### Technical design
|
||||
|
||||
- new route: `/dashboard/crm/manager`
|
||||
- core modules:
|
||||
- Team Calendar
|
||||
- Overdue Activities
|
||||
- Idle Opportunities
|
||||
- Forecast Review
|
||||
- Hot Projects
|
||||
- Approval Queue
|
||||
- Workload Balance
|
||||
- Relationship Risk Alerts
|
||||
|
||||
### Reuse expectations
|
||||
|
||||
- reuse dashboard KPI service
|
||||
- reuse report datasets where possible
|
||||
- reuse approval runtime and visibility rules
|
||||
- consume calendar and timeline projections instead of building ad hoc tables
|
||||
|
||||
### Risk
|
||||
|
||||
Team visibility is still partially approximate until a first-class team graph exists. AR.2 must document that manager workspace should remain branch/product/access aware and avoid inventing a parallel team permission system.
|
||||
|
||||
## EPIC 9: Executive Workspace
|
||||
|
||||
### Objective
|
||||
|
||||
Create a high-level strategic workspace for pipeline health, revenue outlook, and strategic account monitoring.
|
||||
|
||||
### Technical design
|
||||
|
||||
- new route: `/dashboard/crm/executive`
|
||||
- emphasize summary + exception drilling, not operational task lists
|
||||
- reuse dashboard/report infrastructure first
|
||||
- use compact, high-value KPI modules and limited chart count
|
||||
|
||||
### Recommended data blocks
|
||||
|
||||
- Pipeline Health
|
||||
- Revenue Outlook
|
||||
- Strategic Accounts at Risk
|
||||
- Win/Loss Trend
|
||||
- Forecast Confidence
|
||||
- Key Relationship Movement
|
||||
|
||||
## EPIC 10: Lead Handoff & Outcome Alignment
|
||||
|
||||
### Objective
|
||||
|
||||
Strengthen lead-to-opportunity handoff and downstream lead-outcome derivation without destabilizing the current lead foundation.
|
||||
|
||||
### Scope ideas
|
||||
|
||||
- explicit handoff-ready flow
|
||||
- clearer lead-to-opportunity conversion markers
|
||||
- derived lead outcome rules based on linked opportunities
|
||||
- activity suggestions around handoff readiness
|
||||
|
||||
### Reuse
|
||||
|
||||
- current lead domain
|
||||
- opportunity links
|
||||
- customer ownership
|
||||
- CRM access
|
||||
|
||||
## EPIC 11: Relationship Health & Forecast Semantics
|
||||
|
||||
### Objective
|
||||
|
||||
Freeze the implementation rules for relationship health, follow-up health, expected award date, expected delivery date, and hot-project-driven urgency.
|
||||
|
||||
### Technical design
|
||||
|
||||
- derived scoring/service only
|
||||
- no user-maintained health override in phase 1 unless separately approved
|
||||
- consume activity recency, overdue count, open opportunity gaps, and strategic flags
|
||||
- align dashboard, customer workspace, my day, and manager workspace to one shared semantics layer
|
||||
|
||||
## EPIC 12: Terminology & Governance Reconciliation
|
||||
|
||||
### Objective
|
||||
|
||||
Clean up remaining historical `enquiry` wording and reconcile governance docs with the active `opportunity` production model.
|
||||
|
||||
### Constraints
|
||||
|
||||
- do not rename stable production routes or schema without explicit migration approval
|
||||
- prefer documentation, labels, and implementation-note reconciliation first
|
||||
|
||||
## UI/UX Design Gate
|
||||
|
||||
The following epics require a mandatory approved UI/UX design note before code starts:
|
||||
|
||||
- Customer Workspace Enhancement
|
||||
- Calendar Projection & Workspace
|
||||
- My Day Workspace
|
||||
- Manager Workspace
|
||||
- Executive Workspace
|
||||
- any Activity list/detail page that becomes a new major workspace surface
|
||||
|
||||
The UI/UX note must reference:
|
||||
|
||||
- Business Constitution / BU-R.0 / BU-R.0.1
|
||||
- BU-R.1
|
||||
- AR.1
|
||||
- this AR.2 baseline
|
||||
- `layout.md`
|
||||
- `docs/standards/ui-ux-rules.md`
|
||||
- `ui-ux-pro-max`
|
||||
|
||||
## Shared API and Service Conventions
|
||||
|
||||
Every new AR.2 feature should follow:
|
||||
|
||||
```text
|
||||
src/features/<feature>/
|
||||
api/
|
||||
types.ts
|
||||
service.ts
|
||||
queries.ts
|
||||
mutations.ts
|
||||
components/
|
||||
schemas/
|
||||
server/
|
||||
```
|
||||
|
||||
Route handlers remain under `src/app/api/**`.
|
||||
|
||||
## Shared Permission and Security Requirements
|
||||
|
||||
Every AR.2 epic touching CRM data must:
|
||||
|
||||
- require organization access
|
||||
- resolve CRM access server-side
|
||||
- enforce branch/product/ownership scope in service layer
|
||||
- enforce pricing visibility for quotation-derived commercial data
|
||||
- audit security denials where applicable
|
||||
|
||||
No epic may authorize from raw role strings alone.
|
||||
|
||||
## Shared Verification Standard
|
||||
|
||||
Implementation tasks spawned from AR.2 should define:
|
||||
|
||||
- `tsc --noEmit`
|
||||
- targeted lint, if touched area already has lint expectations
|
||||
- feature service tests where practical
|
||||
- route handler and permission scenarios
|
||||
- manual workspace checks for loading, empty, error, responsive, and permission-aware states
|
||||
|
||||
## Technical Risk Register
|
||||
|
||||
| Risk | Affected Epics | Why | Mitigation |
|
||||
| --- | --- | --- | --- |
|
||||
| Follow-up data fragmentation | Activity, Timeline, Calendar, Dashboard consumers | existing lead/opportunity/quotation follow-up storage differs | adapter-first rollout and dataset continuity tests |
|
||||
| Approval notification duplication | Events, Notification Expansion | approval flow already publishes notifications | keep approval event compatibility and dedupe strategy |
|
||||
| Workspace route meaning collision | Calendar, My Day, Manager, Executive | `/dashboard/workspaces` already used for admin workspaces | keep business workspaces under `/dashboard/crm/*` |
|
||||
| Pricing leakage | Timeline, Calendar, Executive, My Day | quotation-derived data may appear in new views | centralize pricing checks in projection/query services |
|
||||
| Team visibility ambiguity | Manager, Calendar, Executive | team graph not yet first-class | reuse current resolved access and document known limitation |
|
||||
| Over-engineered repository abstraction | Activity, Timeline | repo prefers service-layer-first pattern | keep internal adapters lightweight and feature-owned |
|
||||
|
||||
## AR.2 Freeze Outcome
|
||||
|
||||
AR.2 freezes:
|
||||
|
||||
1. the epic order for transition delivery
|
||||
2. the minimum technical design boundaries for each epic
|
||||
3. the no-code-before-design rule for major workspace surfaces
|
||||
4. the reuse-first rule for security, notification, dashboard, report, and document foundations
|
||||
5. the implementation expectation that Activity and projections arrive incrementally beside current production modules
|
||||
|
||||
## Verification
|
||||
|
||||
- Documentation-only change.
|
||||
- No schema, migration, API, service, UI, permission, or runtime business-logic file changed.
|
||||
- No build or test command was required for this phase.
|
||||
|
||||
## Outcome
|
||||
|
||||
AR.2 now provides the implementation-ready epic and technical design baseline for the Relationship-Driven Sales Workspace transition. Future implementation tasks can use this document to choose sequence, define scope, reuse correct foundations, prepare workspace UI/UX notes, and avoid breaking the mature production CRM backbone.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Task AR.2 Implementation Report - 2026-07-07
|
||||
|
||||
## Scope
|
||||
|
||||
- start and complete AR.2 as a documentation-only epic and technical-design phase
|
||||
- review AR.1, BU-R blueprint/audit, current CRM foundations, current UI patterns, and workspace UI governance
|
||||
- produce an implementation-ready epic baseline and a required workspace UI/UX design note
|
||||
|
||||
## What Was Produced
|
||||
|
||||
- epic and technical design baseline:
|
||||
[task-ar.2-epic-technical-design-2026-07-07.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-ar.2-epic-technical-design-2026-07-07.md)
|
||||
- workspace UI/UX design note:
|
||||
[task-ar.2-workspace-ui-ux-design-note-2026-07-07.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-ar.2-workspace-ui-ux-design-note-2026-07-07.md)
|
||||
|
||||
## Key Decisions Captured
|
||||
|
||||
1. AR.2 freezes the implementation sequence from foundational runtime to projection layer to workspace layer.
|
||||
2. Activity Platform and Business Event Expansion are the first delivery epics because they unblock most downstream work.
|
||||
3. Customer Workspace is the first major visible workspace because it extends the strongest existing production base.
|
||||
4. Calendar, My Day, Manager, Executive, and major Activity surfaces require an approved UI/UX design note before code starts.
|
||||
5. Business-role workspaces must stay under `/dashboard/crm/*` and must not reuse the existing admin `workspaces` route.
|
||||
|
||||
## Verification
|
||||
|
||||
- Documentation-only change.
|
||||
- No schema, API, UI, service, permission, or runtime business-logic files were changed.
|
||||
- No build or test command was required for this phase.
|
||||
|
||||
## Outcome
|
||||
|
||||
AR.2 now records both the implementation-ready epic/technical-design baseline and the approved workspace UI/UX baseline needed before future implementation work begins.
|
||||
@@ -0,0 +1,398 @@
|
||||
# Task AR.2 Workspace UI/UX Design Note - 2026-07-07
|
||||
|
||||
## Purpose
|
||||
|
||||
This note satisfies the AR.2 governance requirement that major workspace surfaces must have a UI/UX design note before implementation begins.
|
||||
|
||||
This is not final visual design. It is the approved interaction and composition baseline for future workspace implementation tasks.
|
||||
|
||||
## Inputs Reviewed
|
||||
|
||||
- `docs/business/relationship-sales-workspace-blueprint-v1.md`
|
||||
- `docs/implementation/task-bu-r.1-business-capability-audit-2026-07-07.md`
|
||||
- `docs/implementation/task-ar.1-architecture-transition-plan-2026-07-07.md`
|
||||
- `docs/implementation/task-ar.2-epic-technical-design-2026-07-07.md`
|
||||
- `layout.md`
|
||||
- `docs/standards/ui-ux-rules.md`
|
||||
- `docs/standards/architecture-rules.md`
|
||||
- existing shadcn/ui patterns in CRM detail/report/dashboard pages
|
||||
- `src/features/crm/dashboard/components/crm-dashboard.tsx`
|
||||
- `src/features/crm/customers/components/customer-detail.tsx`
|
||||
- `src/features/crm/reports/components/pipeline-report-view.tsx`
|
||||
- `ui-ux-pro-max` design-system and UX searches
|
||||
|
||||
## UI/UX Direction
|
||||
|
||||
### Visual direction
|
||||
|
||||
- preserve the existing dashboard shell and `PageContainer`
|
||||
- extend the current CRM card, tab, filter, and table language
|
||||
- use a restrained enterprise visual system
|
||||
- prefer Minimalism + Swiss-style structure over decorative redesign
|
||||
- keep CRM operational surfaces dense enough for work, but not noisy
|
||||
|
||||
### Style summary from `ui-ux-pro-max`
|
||||
|
||||
- enterprise / operational dashboard fit
|
||||
- Minimalism & Swiss Style is the best match
|
||||
- use clear type hierarchy, subtle hover, minimal shadow, clean borders
|
||||
- keep high contrast and strong layout rhythm
|
||||
|
||||
### Layout behavior
|
||||
|
||||
- summary and action modules first
|
||||
- active work queue second
|
||||
- contextual history and related-record panels next
|
||||
- keep page composition modular and card-based
|
||||
- use bento-style composition only where it improves scanning, not as decoration
|
||||
|
||||
### Chart guidance
|
||||
|
||||
- use bullet charts for compact performance-vs-target manager/executive KPIs
|
||||
- use line highlights for anomaly or risk spikes
|
||||
- use gauge only for isolated single target KPIs, not crowded summary rows
|
||||
|
||||
## Shared Design Rules Across All New Workspaces
|
||||
|
||||
1. Each workspace must make the next decision obvious within the first screenful.
|
||||
2. Filters should stay compact, reusable, and URL-aware where sharing matters.
|
||||
3. Empty states must explain the missing condition and the next useful action.
|
||||
4. Loading states should preserve layout using skeletons.
|
||||
5. Use text and icons in addition to color for status or urgency.
|
||||
6. Preserve current CRM terminology helpers and do not create a second terminology registry.
|
||||
7. New workspace routes must feel connected to the existing CRM nav, not like a parallel product.
|
||||
|
||||
## Surface 1: Customer Workspace
|
||||
|
||||
### Page purpose
|
||||
|
||||
Relationship execution hub for sales and managers.
|
||||
|
||||
### Primary user role
|
||||
|
||||
Sales first, managers second.
|
||||
|
||||
### Layout structure
|
||||
|
||||
- top header with customer code, status, owner, and quick actions
|
||||
- main left column:
|
||||
- overview summary
|
||||
- relationship health
|
||||
- upcoming work
|
||||
- activities
|
||||
- timeline
|
||||
- related leads/opportunities/quotations
|
||||
- right column:
|
||||
- owner card
|
||||
- quick metrics
|
||||
- recent meetings / visits
|
||||
- system metadata
|
||||
|
||||
### Key actions
|
||||
|
||||
- edit customer
|
||||
- manage owner
|
||||
- add contact
|
||||
- add activity
|
||||
- jump to open opportunity or quotation
|
||||
|
||||
### Empty state
|
||||
|
||||
- if no open work: explain that the relationship exists but has no upcoming action
|
||||
- primary CTA should be create activity or open opportunity depending on access
|
||||
|
||||
### Loading state
|
||||
|
||||
- keep the existing detail-shell rhythm with card skeletons
|
||||
|
||||
### Permission-aware visibility
|
||||
|
||||
- contacts and sharing controls remain permission-gated
|
||||
- quotation-related commercial values must obey pricing visibility
|
||||
|
||||
### Responsive behavior
|
||||
|
||||
- mobile stacks left and right columns
|
||||
- tabs remain usable without horizontal clipping
|
||||
- quick actions wrap into compact rows
|
||||
|
||||
### Relation to current nav
|
||||
|
||||
- stays on `/dashboard/crm/customers/[id]`
|
||||
- this is an extension of current customer detail, not a new disconnected route
|
||||
|
||||
## Surface 2: Calendar Workspace
|
||||
|
||||
### Page purpose
|
||||
|
||||
Time-based operational workspace for activities, reminders, milestones, and approval due signals.
|
||||
|
||||
### Primary user role
|
||||
|
||||
All operational roles, with manager emphasis in agenda view.
|
||||
|
||||
### Layout structure
|
||||
|
||||
- page header and lens switcher
|
||||
- compact filter bar
|
||||
- calendar body with:
|
||||
- day/week/month/agenda tabs
|
||||
- side summary rail for selected date or selected item
|
||||
|
||||
### Key actions
|
||||
|
||||
- change lens
|
||||
- filter by user/team/branch/entity/activity type
|
||||
- open linked record
|
||||
- create activity from selected slot, when permitted
|
||||
|
||||
### Empty state
|
||||
|
||||
- no scheduled work in period
|
||||
- explain whether filters or true no-work condition caused it
|
||||
|
||||
### Loading state
|
||||
|
||||
- skeleton for toolbar and calendar grid/list shell
|
||||
|
||||
### Permission-aware visibility
|
||||
|
||||
- personal lens defaults to owned and assigned work
|
||||
- manager lens shows only permitted team work
|
||||
- milestone rows do not leak unauthorized quotation data
|
||||
|
||||
### Responsive behavior
|
||||
|
||||
- agenda becomes the mobile-friendly default
|
||||
- month view should degrade carefully on small widths
|
||||
|
||||
### Relation to current nav
|
||||
|
||||
- new route under `/dashboard/crm/calendar`
|
||||
|
||||
## Surface 3: My Day
|
||||
|
||||
### Page purpose
|
||||
|
||||
Personal action home screen for the logged-in user.
|
||||
|
||||
### Primary user role
|
||||
|
||||
Sales and marketing; managers can still use it as a personal operating view.
|
||||
|
||||
### Layout structure
|
||||
|
||||
- high-priority queue at the top:
|
||||
- overdue
|
||||
- due today
|
||||
- urgent meetings
|
||||
- pending approvals
|
||||
- lower sections:
|
||||
- hot projects requiring action
|
||||
- urgent quotations
|
||||
- relationship alerts
|
||||
- upcoming schedule snapshot
|
||||
|
||||
### Key actions
|
||||
|
||||
- mark activity complete
|
||||
- reschedule
|
||||
- open source record
|
||||
- open today's calendar
|
||||
|
||||
### Empty state
|
||||
|
||||
- celebrate cleared queue but provide a useful next action, such as reviewing upcoming work
|
||||
|
||||
### Loading state
|
||||
|
||||
- summary and queue skeletons
|
||||
|
||||
### Permission-aware visibility
|
||||
|
||||
- approvals and quotation urgency must obey approval/pricing boundaries
|
||||
|
||||
### Responsive behavior
|
||||
|
||||
- priority queue stays first on mobile
|
||||
- cards collapse into a single-column task feed
|
||||
|
||||
### Relation to current nav
|
||||
|
||||
- new route under `/dashboard/crm/my-day`
|
||||
|
||||
## Surface 4: Manager Workspace
|
||||
|
||||
### Page purpose
|
||||
|
||||
Operational control tower for team execution quality.
|
||||
|
||||
### Primary user role
|
||||
|
||||
Manager.
|
||||
|
||||
### Layout structure
|
||||
|
||||
- summary band:
|
||||
- team overdue
|
||||
- idle opportunities
|
||||
- pending approvals
|
||||
- forecast at risk
|
||||
- main body:
|
||||
- team calendar / agenda
|
||||
- hot projects
|
||||
- approval queue
|
||||
- workload balance
|
||||
- relationship risk alerts
|
||||
|
||||
### Key actions
|
||||
|
||||
- drill into overdue item
|
||||
- reassign or escalate
|
||||
- jump to approval blocker
|
||||
- review tomorrow risk
|
||||
|
||||
### Empty state
|
||||
|
||||
- if no risks or overdue work, show healthy-state copy plus forecast review CTA
|
||||
|
||||
### Loading state
|
||||
|
||||
- KPI band skeleton
|
||||
- agenda/table skeleton
|
||||
|
||||
### Permission-aware visibility
|
||||
|
||||
- use team/branch/product scope rules
|
||||
- no UI should imply broader access than current security model grants
|
||||
|
||||
### Responsive behavior
|
||||
|
||||
- mobile prioritizes risk list and agenda over wider comparison panels
|
||||
- workload balance and comparison charts move below action queues
|
||||
|
||||
### Relation to current nav
|
||||
|
||||
- new route under `/dashboard/crm/manager`
|
||||
|
||||
## Surface 5: Executive Workspace
|
||||
|
||||
### Page purpose
|
||||
|
||||
Strategic monitoring workspace for executives.
|
||||
|
||||
### Primary user role
|
||||
|
||||
Executive or high-level decision maker.
|
||||
|
||||
### Layout structure
|
||||
|
||||
- top KPI row with limited count
|
||||
- trend and exception cards next
|
||||
- strategic accounts and pipeline/risk summaries below
|
||||
|
||||
### Key actions
|
||||
|
||||
- drill into strategic account
|
||||
- open executive report slice
|
||||
- inspect risk trend
|
||||
|
||||
### Empty state
|
||||
|
||||
- not likely full empty; if limited access, explain scope instead of showing blank business panels
|
||||
|
||||
### Loading state
|
||||
|
||||
- stable KPI and trend skeletons
|
||||
|
||||
### Permission-aware visibility
|
||||
|
||||
- commercial values and strategic summaries follow pricing visibility and report context rules
|
||||
|
||||
### Responsive behavior
|
||||
|
||||
- mobile reduces chart count and shows stacked summary cards
|
||||
- avoid forcing dense wide tables on first view
|
||||
|
||||
### Relation to current nav
|
||||
|
||||
- new route under `/dashboard/crm/executive`
|
||||
|
||||
## Surface 6: Activity Workspace or Major Activity Views
|
||||
|
||||
### Page purpose
|
||||
|
||||
Shared operational work management across customers, leads, opportunities, and quotations.
|
||||
|
||||
### Primary user role
|
||||
|
||||
All operational roles.
|
||||
|
||||
### Layout structure
|
||||
|
||||
- filter bar
|
||||
- queue/list view first
|
||||
- optional board or grouped sections later if justified
|
||||
- detail drawer or detail route for context
|
||||
|
||||
### Key actions
|
||||
|
||||
- create activity
|
||||
- complete
|
||||
- reschedule
|
||||
- reassign
|
||||
- open linked record
|
||||
|
||||
### Empty state
|
||||
|
||||
- distinguish between no activities and filters producing no result
|
||||
|
||||
### Loading state
|
||||
|
||||
- data-table skeleton or list skeleton, not blank feed
|
||||
|
||||
### Permission-aware visibility
|
||||
|
||||
- show source record badges, but hide or redact unauthorized commercial details
|
||||
|
||||
### Responsive behavior
|
||||
|
||||
- mobile uses stacked activity cards rather than wide data tables where needed
|
||||
|
||||
## Recommended Visual Patterns by Surface
|
||||
|
||||
| Surface | Best Current Pattern to Extend |
|
||||
| --- | --- |
|
||||
| Customer Workspace | customer detail tabs + side cards |
|
||||
| Calendar Workspace | dashboard filter bar + new calendar composition |
|
||||
| My Day | dashboard summary + operational queue cards |
|
||||
| Manager Workspace | dashboard bento rhythm + report table density |
|
||||
| Executive Workspace | dashboard summary + report cards with fewer but stronger blocks |
|
||||
| Activity Views | report/list filter pattern + CRM detail drawer pattern |
|
||||
|
||||
## Anti-patterns to Avoid
|
||||
|
||||
- giant marketing-style hero sections inside dashboard workspaces
|
||||
- visual redesign that breaks nearby CRM pages
|
||||
- overusing charts when a ranked list or action queue is clearer
|
||||
- blank states without next actions
|
||||
- status communicated by color alone
|
||||
- new workspace nav under `/dashboard/workspaces`
|
||||
- layout shift on loading or button pending states
|
||||
|
||||
## Handoff Requirement
|
||||
|
||||
Any future implementation task for these surfaces must cite this design note and explicitly state:
|
||||
|
||||
- which surface it implements
|
||||
- whether it preserves this design note or intentionally deviates
|
||||
- why any deviation is needed
|
||||
|
||||
## Verification
|
||||
|
||||
- Documentation-only design note.
|
||||
- No runtime code, route, schema, API, or permission behavior changed.
|
||||
|
||||
## Outcome
|
||||
|
||||
AR.2 now has an approved UI/UX baseline for Customer Workspace, Calendar Workspace, My Day, Manager Workspace, Executive Workspace, and major Activity views, aligned with current CRM patterns and the required `ui-ux-pro-max` design process.
|
||||
698
plans/task-ar.1.md
Normal file
698
plans/task-ar.1.md
Normal file
@@ -0,0 +1,698 @@
|
||||
# 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.
|
||||
56
plans/task-ar.2.md
Normal file
56
plans/task-ar.2.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Task AR.2 - Epic & Technical Design
|
||||
|
||||
Status: Completed
|
||||
|
||||
## UI / UX Design Governance
|
||||
|
||||
All future workspace, dashboard, calendar, timeline, activity, customer, opportunity, quotation, manager, and executive UI design work must use the `ui-ux-pro-max` skill as part of the design process.
|
||||
|
||||
Before proposing or implementing any UI, the agent must review:
|
||||
|
||||
- `layout.md`
|
||||
- `docs/standards/ui-ux-rules.md`
|
||||
- `docs/standards/architecture-rules.md`
|
||||
- existing shadcn/ui usage patterns
|
||||
- existing dashboard layout conventions
|
||||
- existing CRM page/detail/table/form patterns
|
||||
|
||||
### Design Rules
|
||||
|
||||
- Preserve existing shadcn/ui foundation.
|
||||
- Prefer extension over visual redesign.
|
||||
- Follow existing layout rhythm unless the blueprint explicitly requires a new workspace pattern.
|
||||
- Do not introduce a disconnected design system.
|
||||
- New workspace UI must align with ALLA OS role-based workspace philosophy.
|
||||
- Calendar, My Day, Manager Workspace, Customer Workspace, Timeline, and Activity surfaces must be designed as operational workspaces, not generic CRUD pages.
|
||||
- Every UI proposal must include:
|
||||
- page purpose
|
||||
- primary user role
|
||||
- layout structure
|
||||
- key actions
|
||||
- empty state
|
||||
- loading state
|
||||
- permission-aware visibility
|
||||
- responsive behavior
|
||||
- relationship to existing CRM navigation
|
||||
|
||||
### Required Design Inputs
|
||||
|
||||
Use:
|
||||
|
||||
- `ui-ux-pro-max` for UX quality, interaction flow, visual hierarchy, and enterprise usability
|
||||
- `layout.md` for layout structure and page composition rules
|
||||
- `ui-ux-rules.md` for ALLA OS UI standards
|
||||
- existing shadcn/ui components as the implementation baseline
|
||||
|
||||
### Frozen Rule
|
||||
|
||||
No future workspace implementation may start with code first.
|
||||
|
||||
Every new workspace or major UI surface must first produce a UI/UX design note that references:
|
||||
|
||||
- Business Constitution
|
||||
- AR.1 Architecture Transition Plan
|
||||
- `layout.md`
|
||||
- `ui-ux-rules.md`
|
||||
- `ui-ux-pro-max`
|
||||
Reference in New Issue
Block a user