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

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