9.7 KiB
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
activity.completed
Timeline shows
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
activity.completed
↓
Completed Site Survey
Another
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
-
Timeline Projection Schema
-
Timeline Builder
-
Timeline Projection Consumer
-
Timeline Projection Registry
-
Event-to-Timeline Mapping
-
Legacy Timeline Adapter
-
Timeline Projection Storage
-
Timeline Rebuild
-
Timeline Health
-
Timeline UI Components
-
Workspace Timeline Integration
-
Timeline Filtering
-
Timeline Search
-
Timeline Grouping
-
Timeline Delivery Matrix
-
Timeline UX Review Report
-
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, andui-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: