alla-allaos-fullstack/docs/implementation/task-ar.2-epic-technical-design-2026-07-07.md

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

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

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:

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.