alla-allaos-fullstack/docs/implementation/task-ep1.5-timeline-projection-foundation-2026-07-13.md

# Task EP.1.5 Timeline Projection Foundation - 2026-07-13

## Scope

- introduced first production CRM Business Projection: Timeline
- added `crm_timeline_projection` materialized read model schema
- added Timeline event builder and Activity event mapping
- added Timeline projection consumer contract and active CRM registration
- added Timeline list/query storage service
- added Timeline rebuild and legacy adapter contracts
- added reusable Timeline UI components
- added optional Activity detail Timeline integration seam
- preserved Activity, Audit Log, Approval History, follow-up APIs, Dashboard, Reports, Notifications, and current detail-page behavior

## Review Summary

Reviewed before and during implementation:

- `AGENTS.md`
- `plans/task-ep.1.5.md`
- `LAYOUT.md`
- `docs/standards/engineering-constitution.md`
- `docs/standards/project-foundations.md`
- `docs/standards/architecture-rules.md`
- `docs/standards/ui-ux-rules.md`
- `docs/business/relationship-sales-workspace-blueprint-v1.md`
- `docs/security/crm-authorization-boundaries.md`
- `docs/implementation/task-ep1.4-projection-foundation-delivery-reliability-2026-07-13.md`
- `docs/implementation/task-ep1.4.1-transactional-outbox-activation-worker-runtime-2026-07-13.md`
- existing Activity business event adapter
- existing Projection Runtime and Worker
- existing CRM detail/audit UI patterns

## Implementation Summary

### Timeline Schema

Added table:

- `crm_timeline_projection`

Generated migration:

- `drizzle/0005_freezing_wendigo.sql`

The table stores organization-scoped, rebuildable read-model rows with entity references, event provenance, visibility metadata, display fields, and projection version. It has indexes for event id/version idempotency, organization chronology, customer chronology, and activity/event lookup.

### Timeline Builder

Added:

- `src/features/crm/timeline/server/builder.ts`

Builder maps Business Events into business-readable Timeline items. Initial active mappings cover Activity lifecycle events:

- `activity.created`
- `activity.assigned`
- `activity.reassigned`
- `activity.started`
- `activity.rescheduled`
- `activity.completed`
- `activity.cancelled`
- `activity.deleted`

Generic mapping is available for registered future CRM events until their business copy is specialized.

### Timeline Consumer

Added:

- `src/features/crm/timeline/server/consumer.ts`
- `src/features/crm/timeline/server/registration.ts`

The consumer builds a Timeline item and persists it with idempotent `eventId + sourceProjectionVersion` storage. Foundation default consumers remain safe skeletons; CRM worker startup can opt into `CRM_TIMELINE_PROJECTION_CONSUMERS` for the active Timeline projection set.

### Timeline Storage And Query Contract

Added:

- `src/features/crm/timeline/api/types.ts`
- `src/features/crm/timeline/server/service.ts`

Supported filters include organization, customer, lead, opportunity, quotation, activity, event, category, actor, search, date range, and cursor/limit contract. Timeline remains read-only.

### Legacy Adapter And Rebuild Contracts

Added:

- `src/features/crm/timeline/server/legacy-adapters.ts`
- `src/features/crm/timeline/server/rebuild.ts`

Legacy adapters are explicitly read-only rebuild inputs for lead follow-up, opportunity follow-up, quotation follow-up, activity, approval, and audit history. No data migration was introduced.

### Timeline UI

Added:

- `src/features/crm/timeline/components/timeline-list.tsx`

Components:

- `TimelineList`
- `TimelineCard`
- `TimelineEmpty`
- `TimelineSkeleton`

The UI follows the existing dashboard card language, uses deterministic shared date formatting, shadcn primitives, and app icon registry. It preserves a calm enterprise density while adding a clear vertical chronology.

### Workspace Integration

Added an optional `timelineItems` prop to Activity detail. Existing callers are unaffected; when supplied, Activity detail renders an additive Timeline card below the existing Activity detail card.

## Security Notes

- Timeline rows are organization-scoped.
- Timeline visibility stores product type, pricing sensitivity, and internal-only flags.
- Pricing-sensitive/internal-only event payloads continue to rely on source event minimization.
- Timeline query service is storage-ready; route/API exposure must still apply CRM resolved access, branch/product scope, ownership, and pricing visibility before becoming public.
- Timeline never mutates source domains and does not replace Audit Log.

## Delivery Matrix

Initial production path:

| Business Event | Timeline Item | Workspace | Consumer | Projection |
| --- | --- | --- | --- | --- |
| `activity.created` | Activity created | Customer / Lead / Opportunity / Quotation / Activity | `timeline.projection.consumer` | `crm_timeline_projection` |
| `activity.completed` | Activity completed | Customer / Lead / Opportunity / Quotation / Activity | `timeline.projection.consumer` | `crm_timeline_projection` |
| `activity.cancelled` | Activity cancelled | Customer / Lead / Opportunity / Quotation / Activity | `timeline.projection.consumer` | `crm_timeline_projection` |

Additional Activity events are supported in code and documented in the builder mapping.

## UX Review

- Layout: follows `LAYOUT.md` detail-card and timeline entry patterns.
- Density: Timeline cards stay compact, scannable, and fit existing CRM dashboard surfaces.
- Accessibility: items use semantic `article`, `time`, non-color badges, and text labels.
- Loading/empty states: `TimelineSkeleton` and `TimelineEmpty` included.
- Dark mode: tone classes include dark-mode variants.
- Date rendering: uses `src/lib/date-format.ts`.

## Verification

- `npm run typecheck`
- `node --disable-warning=ExperimentalWarning --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types --test src/features/foundation/business-events/*.test.ts src/features/foundation/projections/*.test.ts src/features/crm/activities/server/business-events.test.ts src/features/crm/timeline/server/*.test.ts`
- `npx oxlint src/features/crm/timeline src/features/foundation/projections/registry.ts src/features/foundation/projections/consumers.ts src/features/foundation/projections/server/store.ts src/features/crm/activities/components/activity-detail.tsx src/db/schema.ts`
- `npm run db:generate`

## Residual Risks / Follow-up

- Public Timeline route handlers and server-side CRM resolved-access filtering remain future work before exposing Timeline broadly.
- Customer, Lead, Opportunity, and Quotation detail pages are not yet wired to fetch Timeline data; Activity detail has a backward-compatible render seam.
- Approval, quotation, opportunity, customer, and PO event mappings have generic fallback support but need specialized business copy when those domains publish durable events.
- Legacy adapters are contract-only in this slice; source-query rebuild implementation should be expanded as each workspace adopts Timeline.
- EP.1.6 Calendar can reuse the same projection runtime and Activity event delivery path.