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

Task EP.1.6.2 – Direct Big Calendar UI Adoption

Status: Foundation Implemented

Priority: High

Type: UI Modernization / Calendar UX / Frontend Refactor

---

Depends On

• EP.1.6 Calendar Projection, Workspace & Big Calendar Foundation
• EP.1.6.1 Calendar Empty State Rendering Improvement
• EP.1.7 My Day Workspace Foundation

---

Objective

Replace the current custom Calendar UI implementation with the original lramos33/big-calendar component architecture while preserving the ALLA OS backend architecture.

This task is UI-only.

No business logic, projection model, Activity ownership, Business Events, or Calendar Projection architecture shall change.

---

Background

EP.1.6 successfully introduced:

• Calendar Projection
• Calendar Query Service
• Calendar Workspace
• Calendar Projection Runtime
• Activity integration
• Calendar API
• Calendar security

However the current UI only references the upstream project conceptually.

It does NOT use the original Calendar UI implementation.

The goal of EP.1.6.2 is to adopt the upstream Calendar components directly so ALLA OS gains the same interaction quality and polished UX.

---

Review Required

Review before implementation:

• AGENTS.md
• LAYOUT.md
• ui-ux-rules.md
• Engineering Constitution
• EP.1.6
• EP.1.6.1
• EP.1.7

Review upstream project:

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

Review:

• component structure
• provider architecture
• drag & drop
• resize
• agenda
• month
• week
• day
• year
• event rendering
• toolbar
• filters
• responsive behavior
• dark mode

---

Architecture Principle

ALLA OS owns:

• Activity
• Calendar Projection
• Business Events
• Projection Runtime
• Permissions
• APIs

Big Calendar owns:

• Calendar rendering
• Calendar interactions
• View switching
• Event layout
• Drag UX
• Resize UX
• Toolbar
• Navigation

---

Data Flow

Must remain

Activity

↓

Business Event

↓

Projection Runtime

↓

crm_calendar_projection

↓

CalendarProjectionItem

↓

Calendar Adapter

↓

Big Calendar Components

No upstream component may read database rows directly.

---

Scope

---

Part 1 — Direct Component Adoption

Adopt upstream source components directly.

Do NOT recreate:

• Month Grid
• Week Grid
• Day Grid
• Agenda Layout
• Calendar Header
• Calendar Navigation

Use upstream implementation instead.

---

Part 2 — Remove Custom Calendar Rendering

Deprecate current custom:

• Day
• Week
• Month

renderers.

Only keep:

• ALLA adapter
• wrapper
• permissions
• Activity actions

---

Part 3 — Calendar Provider

Introduce upstream provider.

Wrap ALLA Calendar.

The provider receives

CalendarProjectionItem

through an adapter.

---

Part 4 — Adapter Layer

Implement

mapCalendarProjectionToBigCalendarEvent()

and

mapBigCalendarActionToActivityCommand()

No business logic inside UI.

---

Part 5 — Toolbar Integration

Use upstream toolbar.

Adapt:

• Today
• Previous
• Next
• Date Picker
• View Selector

Integrate with:

• URL search params
• React Query

---

Part 6 — View Integration

Support

• Day
• Week
• Month
• Agenda

Optional

• Year

Do not change upstream layout unnecessarily.

---

Part 7 — Event Rendering

Differentiate

Editable Activity

vs

Read-only Milestone

Show

• icon
• badge
• customer
• title
• priority
• overdue
• Hot Project

using ALLA adapter.

---

Part 8 — Drag & Drop

Enable upstream drag.

Rules

Editable

↓

Activity API

↓

Business Event

↓

Projection Refresh

Read-only milestones

↓

cannot move.

---

Part 9 — Resize

Enable resize.

Only

Activity

may resize.

Never

Milestones.

---

Part 10 — Event Detail

Selecting an event opens

ALLA Activity Sheet

or

Source Detail Sheet

depending on

Activity

or

Milestone.

---

Part 11 — Working Hours

Reuse upstream configuration.

Default

Asia/Bangkok

Support

Organization setting

Future

User preference.

---

Part 12 — Current Time

Enable

Now Indicator

from upstream.

---

Part 13 — Today Highlight

Use upstream

Today

highlight behavior.

---

Part 14 — User Filter

Replace upstream demo users.

Use

CRM Users API

Permission aware.

---

Part 15 — Theme Integration

Align

fonts

spacing

cards

buttons

badges

colors

with ALLA OS.

Avoid redesigning upstream.

---

Part 16 — Responsive Review

Validate

Desktop

Tablet

Mobile

Agenda remains mobile default.

---

Part 17 — Accessibility

Validate

• keyboard
• focus
• screen reader
• contrast
• dark mode

---

Part 18 — Calendar Empty State

Keep

EP.1.6.1 behavior.

Day

Week

Month

↓

render calendar.

Agenda

↓

render empty list.

---

Part 19 — Source Audit

Document

• adopted files
• modified files
• untouched files
• removed demo code

---

Part 20 — Upgrade Strategy

Record

• upstream commit hash
• version reviewed
• local patches
• synchronization strategy

Future updates must be traceable.

---

Part 21 — Performance

Verify

• Month rendering
• Week rendering
• Day rendering
• Agenda rendering
• Virtualization where applicable
• React re-render counts
• Lazy event loading

---

Part 22 — Regression Testing

Verify

Calendar

does not break

• Activity
• Timeline
• Dashboard
• My Day
• Projection Runtime
• Permission model

---

Deliverables

1. Direct Big Calendar integration
2. Calendar Provider
3. Calendar Adapter Layer
4. Toolbar Integration
5. Day View
6. Week View
7. Month View
8. Agenda View
9. Optional Year View
10. Drag & Drop
11. Resize
12. Current Time Indicator
13. Today Highlight
14. User Filter
15. Theme Integration
16. Responsive Review
17. Accessibility Review
18. Source Audit Report
19. Upgrade Strategy Document
20. Regression Report

---

Constraints

Must preserve

• Activity ownership
• Calendar Projection
• Timeline
• Projection Runtime
• Business Events
• CRM permissions
• API contracts

Must NOT

• replace Calendar Projection
• introduce local event storage
• duplicate Activity logic
• bypass Activity API
• bypass Business Events
• mutate projection rows directly

---

Verification

• npm run typecheck
• npm run db:generate
• npx oxlint src/features/crm/calendar
• Calendar interaction tests
• Drag & Drop tests
• Resize tests
• Permission tests
• Responsive tests
• Accessibility tests

---

Acceptance Criteria

• The Calendar UI is built directly on the lramos33/big-calendar source components rather than custom-rendered Day, Week, and Month grids.
• ALLA OS retains ownership of Activity, Calendar Projection, Business Events, Projection Runtime, and CRM authorization.
• CalendarProjectionItem is adapted into the upstream event model through a dedicated adapter layer.
• Upstream toolbar, navigation, Day, Week, Month, and Agenda views are reused with minimal structural modification.
• Editable Activities support drag-and-drop and resize through the Activity API only.
• Read-only milestones cannot be dragged or resized.
• The current-time indicator and Today highlighting are enabled.
• Day, Week, and Month always render the Calendar grid; Agenda retains the list-style empty state from EP.1.6.1.
• The upstream MIT license is preserved, and an audit documents all adopted and modified source files.
• The Calendar visually matches the upstream interaction quality while following LAYOUT.md, ui-ux-rules.md, and ui-ux-pro-max.
• Existing Activity, Calendar Projection, Timeline, My Day, Dashboard, Reports, Notifications, and Projection Runtime behavior remain unchanged.

---

Success Criteria

ALLA OS transitions from a custom Calendar implementation to a direct integration of the lramos33/big-calendar UI, delivering a polished enterprise calendar experience while preserving the existing backend architecture, business rules, security model, and Projection-based design.