alla-allaos-fullstack/plans/task-ep.1.6.md

Task EP.1.6 – Calendar Projection, Workspace & Big Calendar Foundation

Status: Foundation Implemented

Priority: Critical

Type: Projection Platform / Workspace / UI Foundation

---

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
• EP.1.5 Timeline Projection Foundation
• 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
• AR.2 Workspace UI/UX Design Note
• ENG.0 Engineering Constitution

---

Objective

Introduce the first production Calendar Workspace of ALLA OS by combining:

• Calendar Projection
• Calendar Workspace
• Big Calendar UI Foundation
• Activity scheduling
• Business milestones
• Team visibility
• Calendar interaction

Calendar becomes the operational scheduling workspace for CRM while preserving existing source-domain ownership.

Calendar is NOT:

• a source-of-truth
• another Activity module
• another Opportunity module
• another Quotation module

Calendar is a governed projection and operational workspace.

---

Business Outcome

After EP.1.6 users can answer:

• What should I do today?
• Which customers should I visit?
• Which follow-ups are overdue?
• Which quotations are expiring?
• Which projects are Hot Projects?
• Which approvals are waiting?
• Which customer visits are scheduled?
• What is my team's workload today?
• What are tomorrow's priorities?

Managers gain a Team Calendar without creating duplicate business data.

---

Calendar Business Principles

Calendar is Projection

Calendar is generated from:

• Activity
• Business Events
• Opportunity milestones
• Quotation milestones
• Approval milestones
• Legacy adapters during rebuild

Calendar rows are rebuildable.

---

Activity Owns Operational Work

Editable Calendar events always belong to Activity.

Examples:

• Follow-up
• Meeting
• Site Survey
• Visit
• Internal Task
• Phone Call
• Reminder

Calendar actions must call Activity Services.

Calendar never edits projection rows directly.

---

Milestones Remain Source-Owned

Read-only Calendar milestones include:

• Expected Award Date
• Expected Delivery Date
• Quotation Expiration
• Approval Due
• Approval Escalation
• PO Milestones

Editing must always occur through the owning domain.

---

Calendar ≠ Timeline

Timeline answers:

What happened?

Calendar answers:

What must happen?

Both consume Business Events but serve different business purposes.

---

UI Foundation Decision

The Calendar UI must adopt:

lramos33/big-calendar

Repository:

https://github.com/lramos33/big-calendar

This repository becomes the Calendar UI foundation only.

It does NOT become:

• Calendar database
• Calendar backend
• Activity service
• Projection runtime
• CRM authorization
• Source-of-truth

The governed architecture remains:

Activity / Opportunity / Quotation / Approval
                ↓
          Business Events
                ↓
      Projection Runtime
                ↓
crm_calendar_projection
                ↓
Calendar Adapter
                ↓
lramos33/big-calendar

---

Review Required

Governance

Review:

• AGENTS.md
• Engineering Constitution
• Project Foundations
• Architecture Rules
• UI UX Rules
• Task Review Checklist
• CRM Authorization Boundaries
• LAYOUT.md

Business

Review:

• Relationship Sales Workspace Blueprint
• BU-R.1

Architecture

Review:

• AR.1
• AR.2
• Workspace UI UX Design Note

Existing Runtime

Review:

• Projection Runtime
• Worker Runtime
• Timeline Projection
• Activity Service
• Business Event Registry
• Calendar-related Activity scheduling
• Date formatting utilities
• CRM security

UI Review

Must use:

• ui-ux-pro-max
• LAYOUT.md
• ui-ux-rules.md

No code-first Calendar implementation is allowed.

---

Scope

Part 1 — Calendar Projection Schema

Introduce:

crm_calendar_projection

Containing:

• organization
• branch
• product
• activity
• customer
• lead
• opportunity
• quotation
• approval
• owner
• assignee
• title
• summary
• location
• start
• end
• timezone
• priority
• category
• editable
• milestone
• overdue
• hot project
• projection version
• source event
• metadata

Projection rows remain rebuildable.

---

Part 2 — Calendar Projection Builder

Implement

CalendarProjectionBuilder

Responsibilities

• Business Event mapping
• milestone mapping
• display enrichment
• permission metadata
• icon registry
• urgency calculation
• projection persistence

Builder never mutates source domains.

---

Part 3 — Activity Event Mapping

Support

• activity.created
• activity.assigned
• activity.reassigned
• activity.started
• activity.rescheduled
• activity.completed
• activity.cancelled
• activity.deleted

Projection updates must be incremental through Business Events.

---

Part 4 — Milestone Projection

Project:

Opportunity

• Expected Award Date
• Expected Delivery Date
• Hot Project review

Quotation

• Valid Until
• Delivery milestone

Approval

• Due
• Escalation

Milestones are read-only.

---

Part 5 — Calendar Projection Consumer

Activate Calendar consumer through Projection Runtime.

Must support:

• checkpoint
• retry
• dead letter
• rebuild
• idempotency

---

Part 6 — Calendar Query Service

Provide secured query service.

Filters:

• date range
• user
• team
• branch
• product
• customer
• lead
• opportunity
• quotation
• activity type
• category
• priority
• overdue
• milestone
• Hot Project
• search

Supported lenses:

• Personal
• Team
• Manager
• Executive

---

Part 7 — Calendar Rebuild

Hybrid rebuild.

Initial build:

• Activity
• Opportunity
• Quotation
• Approval

Incremental:

• Business Events

Support:

• organization
• customer
• opportunity
• quotation
• date range
• dry run
• reset existing
• restart

---

Part 8 — Calendar Workspace

Route:

/dashboard/crm/calendar

Views:

• Day
• Week
• Month
• Agenda

Agenda is default for:

• mobile
• manager
• high-density work

---

Part 9 — Big Calendar Source Audit

Before implementation:

Audit:

• dependency compatibility
• React compatibility
• Next.js compatibility
• shadcn compatibility
• Tailwind compatibility
• accessibility
• dark mode
• timezone assumptions
• drag/drop libraries
• demo code
• mock data

Document:

• files adopted
• files rejected
• modification strategy

---

Part 10 — Big Calendar Adaptation

Do NOT import the whole repository.

Only adapt:

• Calendar Views
• Toolbar
• Event Rendering
• Drag & Drop
• Resize
• Navigation
• User Filter
• Working Hours

Move adapted source into:

src/features/crm/calendar/

Maintain ALLA OS architecture.

---

Part 11 — Calendar Adapter Layer

Introduce

CalendarProjectionItem

↓

BigCalendarEvent

Implement

mapCalendarProjectionToBigCalendarEvent()

UI must never consume database rows directly.

---

Part 12 — Calendar Rendering Strategy

Differentiate:

Editable Activity

Examples

• Follow-up
• Meeting
• Visit
• Site Survey

Supports

• Complete
• Reschedule
• Cancel
• Open
• Reassign

---

Read-only Milestone

Examples

• Expected Award
• Expected Delivery
• Approval Due
• Quotation Expiration

Supports

• Open Source
• View Detail
• Create Related Activity

No editing.

---

Part 13 — Drag and Drop

For Activities

Drag

↓

Activity API

↓

Business Event

↓

Projection Update

↓

Calendar Refresh

No direct Calendar persistence.

Milestones cannot be dragged.

---

Part 14 — User Filter

Integrate upstream user filter with:

• CRM permissions
• team hierarchy
• ownership
• manager scope

Never load unauthorized users.

---

Part 15 — Working Hours

Support

• organization defaults
• user preferences
• Bangkok timezone
• all-day events
• current time
• business hours

---

Part 16 — Schedule Conflict Detection

Detect

• overlapping visits
• meetings
• site surveys
• tasks

Read-only advisory.

No blocking.

---

Part 17 — Calendar Summary

Display

• Due Today
• Overdue
• Meetings
• Visits
• Milestones
• Approval Due
• Hot Projects

Derived from Calendar projection.

---

Part 18 — Calendar Performance

Support

• indexes
• bounded queries
• lazy loading
• virtual agenda
• cursor pagination
• projection batching

No N+1.

---

Part 19 — Projection Health

Track

• lag
• retries
• dead letters
• row count
• stale rows
• rebuild status

---

Part 20 — Calendar Delivery Matrix

Document

Source

↓

Business Event

↓

Projection

↓

Calendar Item

↓

Workspace

Include:

• Activity
• Opportunity
• Quotation
• Approval

---

Part 21 — Calendar UI / UX Review

Review with

• ui-ux-pro-max
• LAYOUT.md
• ui-ux-rules.md

Validate

• hierarchy
• spacing
• typography
• icons
• filters
• density
• accessibility
• dark mode
• responsiveness
• keyboard
• loading
• empty state

---

Part 22 — Upstream License

Retain

MIT License

Document

• adopted files
• attribution
• modification history

---

Deliverables

1. Calendar Projection Schema
2. Calendar Builder
3. Calendar Projection Consumer
4. Calendar Query Service
5. Calendar Rebuild
6. Calendar Workspace
7. Day / Week / Month / Agenda
8. Big Calendar Source Audit
9. Big Calendar Adaptation
10. Calendar Adapter Layer
11. Activity Calendar Actions
12. Milestone Projection
13. Drag & Drop Integration
14. User Filter Integration
15. Working Hours Support
16. Schedule Conflict Detection
17. Calendar Summary Panels
18. Projection Health
19. Calendar Delivery Matrix
20. UI/UX Review Report
21. Upstream License & Attribution Report
22. EP.1.7 Readiness Report

---

Constraints

Must preserve:

• Activity ownership
• Opportunity ownership
• Quotation ownership
• Approval ownership
• Timeline
• Dashboard
• Reports
• Notifications
• Audit Log
• CRM security
• Projection Runtime

Do NOT implement:

• Google Calendar Sync
• Outlook Sync
• recurring engine
• My Day
• Manager Workspace
• Executive Workspace
• Relationship Health
• Forecast
• automatic Activity generation
• legacy migration

Calendar remains an additive projection.

---

Testing

• Projection
• Builder
• Consumer
• Rebuild
• Activity Events
• Milestones
• Query
• Permissions
• Drag & Drop
• Resize
• Agenda
• Day
• Week
• Month
• Timezone
• Conflict Detection
• UI
• Accessibility
• Dark Mode
• Performance
• Compatibility

---

Acceptance Criteria

• Calendar Projection is fully rebuildable.
• Calendar uses Business Events for incremental updates.
• Activity remains the only editable operational work source.
• Opportunity, Quotation, and Approval milestones are projected as read-only Calendar items.
• lramos33/big-calendar is successfully adopted as the UI foundation without importing its application shell or backend.
• A dedicated adapter maps CalendarProjectionItem to the Calendar UI event model.
• Drag-and-drop and resize update Activities only through Activity Services and Business Events.
• Read-only milestones cannot be dragged or resized.
• Personal, Team, Manager, and Executive lenses enforce existing CRM authorization.
• Day, Week, Month, and Agenda views are available, with Agenda optimized for managers and mobile.
• Working hours, timezone, and schedule conflict detection behave consistently.
• Calendar integrates with the Projection Runtime (checkpoint, retry, rebuild, health).
• UI conforms to LAYOUT.md, ui-ux-rules.md, and ui-ux-pro-max.
• Existing Activity, Timeline, Dashboard, Reports, Notifications, Approval flows, and Follow-up APIs remain unchanged.

---

Success Criteria

ALLA OS gains a production-ready Calendar Workspace built on a governed Projection architecture.

Users can plan and execute daily operational work from a single Calendar while preserving Activity, Opportunity, Quotation, and Approval as the authoritative business domains.

The Calendar foundation is ready for:

EP.1.7 – My Day Workspace Foundation