# Task EP.1.5 – Timeline Projection Foundation Status: Completed Priority: Critical Type: Projection Platform / Timeline Read Model --- # Depends On * EP.1.1 Activity Domain Foundation * EP.1.2 Activity Integration & Legacy Follow-up Adapter * EP.1.3 Business Event Foundation * EP.1.4 Projection Foundation & Delivery Reliability * EP.1.4.1 Transactional Outbox Activation & Worker Runtime * BU-R.0 Business Blueprint Freeze * BU-R.0.1 Workspace & Activity Blueprint * BU-R.1 Business Capability Audit * AR.1 Architecture Transition Plan * AR.2 Epic Technical Design * ENG.0 Engineering Constitution --- # Objective Introduce the first production Business Projection of ALLA OS. This phase builds the Timeline Projection that becomes the official chronological business history of CRM. Timeline is **not** Activity. Timeline is **not** Audit Log. Timeline is **not** Follow-up. Timeline is a generated business projection that explains everything that happened to a Customer, Lead, Opportunity, Quotation, Activity, Approval, and PO in business language. Timeline becomes the foundation for: * Customer Workspace * Lead Workspace * Opportunity Workspace * Quotation Workspace * Relationship Workspace * Manager Workspace * Executive Workspace Future Calendar, My Day, Dashboard and Forecast continue consuming Business Events independently. Timeline never owns business state. --- # Background Current repository already contains * Audit Log * Activity Domain * Business Event Foundation * Transactional Outbox * Projection Runtime * Legacy Follow-up Adapters What still does not exist is a single business timeline. Today users must inspect * Audit Log * Lead Follow-up * Opportunity Follow-up * Quotation Follow-up * Activity * Approval History to understand one customer journey. Timeline consolidates these into one governed projection. --- # Timeline Principles ## Timeline is Business History Timeline answers > "What happened?" not > "What changed in the database?" --- ## Timeline is Read Only Timeline never edits data. Timeline never owns lifecycle. Timeline is always rebuildable. --- ## Timeline is Projection Timeline is generated from * Business Events * Activity * Legacy Follow-up adapters * Approval events * Source queries during rebuild --- ## Timeline is Human Friendly Example Instead of ```text activity.completed ``` Timeline shows ```text Completed site survey. Outcome: Customer requested revised quotation. ``` --- ## Timeline is Chronological Every Timeline Item has * occurredAt * source * actor * entity * business meaning --- # Review Required Review Governance * AGENTS.md * Engineering Constitution * Project Foundations * Architecture Rules * UI/UX Rules * Task Review Checklist Business * Relationship Sales Workspace Blueprint * BU-R.1 Architecture * AR.1 * AR.2 Implementation * EP.1.2 * EP.1.3 * EP.1.4 * EP.1.4.1 Existing * Activity Timeline Compatibility Layer * Audit Log * Approval History * Customer Detail * Lead Detail * Opportunity Detail * Quotation Detail Review layout.md Review ui-ux-rules.md Review ui-ux-pro-max Timeline UI must follow the Workspace UI Constitution. --- # Scope ## Part 1 — Timeline Projection Schema Introduce crm_timeline_projection Minimum fields * id * organizationId * branchId * customerId * leadId * opportunityId * quotationId * activityId * eventId * entityType * entityId * timelineType * timelineCategory * occurredAt * actorId * actorDisplay * title * summary * icon * color * priority * visibility * metadata * sourceEvent * sourceProjectionVersion * createdAt Timeline rows are rebuildable. Timeline rows are never source-of-truth. --- ## Part 2 — Timeline Builder Implement TimelineProjectionBuilder Responsibilities * consume Business Events * transform event * enrich display * resolve references * write projection Builder must never mutate source domains. --- ## Part 3 — Timeline Event Mapping Create mapping from Business Event ↓ Timeline Item Example ```text activity.completed ↓ Completed Site Survey ``` Another ```text quotation.approved ↓ Quotation Approved ``` Every supported Business Event requires mapping. --- ## Part 4 — Legacy Timeline Adapter Support timeline rebuild using Lead Follow-up Opportunity Follow-up Quotation Follow-up Activity Approval Audit No migration. Adapters remain read-only. --- ## Part 5 — Timeline Projection Consumer Activate Timeline consumer. Consumer responsibilities * consume event * build timeline item * persist projection * checkpoint * retry * rebuild safe Consumer uses Projection Runtime. --- ## Part 6 — Timeline Categories Freeze categories Activity Communication Meeting Site Survey Approval Quotation Revision Assignment Status Forecast PO Customer System Categories must be configurable using Master Options later. --- ## Part 7 — Timeline Rendering Model Freeze UI model Timeline Item contains Header Timestamp Actor Business Message Reference Links Status Badge Icon Optional Detail Attachment Indicator No editing inside Timeline. --- ## Part 8 — Timeline Visibility Timeline follows CRM Authorization. Visibility Organization ↓ Branch ↓ Product ↓ Pricing ↓ Ownership ↓ Internal Only Timeline never exposes hidden quotation pricing. --- ## Part 9 — Timeline Projection Rebuild Implement Timeline rebuild Supports Organization Customer Lead Opportunity Quotation Date Range Dry Run Reset Existing Progress Restart --- ## Part 10 — Timeline Projection Health Track Items Lag Last Event Checkpoint Rebuild Time Health Errors --- ## Part 11 — Timeline UI Components Introduce reusable components TimelineList TimelineCard TimelineItem TimelineFilter TimelineGroup TimelineEmpty TimelineLoading TimelineSkeleton TimelineVirtualList Use shadcn/ui Follow layout.md Follow ui-ux-rules.md Apply ui-ux-pro-max Timeline must feel modern and readable. --- ## Part 12 — Workspace Integration Embed Timeline into Customer Detail Lead Detail Opportunity Detail Quotation Detail Activity Detail Timeline replaces fragmented history panels over time. Existing panels remain until cutover. --- ## Part 13 — Filtering Support Date Actor Timeline Category Entity Activity Approval Quotation Customer Opportunity Lead PO Attachment Search Unread Internal Only --- ## Part 14 — Timeline Grouping Support grouping Today Yesterday Earlier This Week Last Week Earlier This Month Older Optional Group by Entity Group by Customer Group by Opportunity --- ## Part 15 — Timeline Search Introduce Full text search Business Message Summary Actor Customer Opportunity Quotation Activity Category --- ## Part 16 — Timeline Performance Support Virtual scrolling Incremental loading Cursor pagination Projection indexes Lazy detail expansion No N+1 queries. --- ## Part 17 — Timeline Delivery Matrix Freeze Business Event ↓ Timeline Item ↓ Workspace ↓ Consumer ↓ Projection Every event path documented. --- ## Part 18 — Timeline UX Review Before merge Review layout.md Review ui-ux-rules.md Review ui-ux-pro-max Verify Typography Spacing Hierarchy Icons Density Mobile Accessibility Keyboard Dark Mode Loading Empty State Skeleton Sticky Date Header Infinite Scroll --- # Deliverables 1. Timeline Projection Schema 2. Timeline Builder 3. Timeline Projection Consumer 4. Timeline Projection Registry 5. Event-to-Timeline Mapping 6. Legacy Timeline Adapter 7. Timeline Projection Storage 8. Timeline Rebuild 9. Timeline Health 10. Timeline UI Components 11. Workspace Timeline Integration 12. Timeline Filtering 13. Timeline Search 14. Timeline Grouping 15. Timeline Delivery Matrix 16. Timeline UX Review Report 17. Projection Readiness Report --- # Constraints Must preserve * Activity * Audit Log * Approval History * Follow-up APIs * Dashboard * Reports * Notifications * Current Detail Pages Timeline is additive. Do not replace Audit Log. Do not replace Activity. Do not replace Calendar. Do not replace Notification. Do not replace Dashboard. No business state mutation. No workflow changes. No permission changes. --- # Testing Projection Consumer Builder Rebuild Retry Checkpoint Timeline UI Search Grouping Filtering Pagination Virtual List Authorization Pricing Visibility Legacy Adapter Workspace Integration Dark Mode Accessibility Performance --- # Acceptance Criteria * Timeline Projection is generated entirely from Business Events and approved adapters. * Timeline never mutates source domains. * Timeline can be rebuilt safely. * Timeline respects all CRM authorization rules. * Timeline integrates into Customer, Lead, Opportunity, Quotation, and Activity detail pages without replacing existing history panels. * Legacy Follow-up history appears through adapters without data migration. * Timeline UI follows `layout.md`, `ui-ux-rules.md`, and `ui-ux-pro-max`. * Timeline supports filtering, grouping, search, cursor pagination, and virtual scrolling. * Projection health, rebuild, retry, and checkpoints integrate with the Projection Runtime. * Existing APIs, Dashboard, Notifications, Reports, and Approval flows remain unchanged. --- # Success Criteria ALLA OS gains its first production-grade Business Projection. Users can understand the complete customer and sales journey from one unified Timeline instead of opening multiple follow-up tabs, audit logs, and approval histories. Timeline becomes the canonical business history used by future Calendar, My Day, Manager Workspace, Executive Workspace, Relationship Health, Forecast, and Customer 360 features. Ready for: # EP.1.6 – Calendar Projection Foundation