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

# Task EP.1.6.2-R1 – Replace Reimplemented Calendar with Upstream Big Calendar Source

Status: Implemented

Priority: Critical

Type: Corrective UI Refactor / Direct Upstream Adoption

Supersedes:

- EP.1.6.2 custom Calendar UI implementation

---

# Objective

Remove the locally reimplemented Calendar UI and replace it with the actual source components from:

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

Pinned upstream commit:

```text
fbb8485e3d54b267261056c784632229ba6f7bc3
```

The goal is:

> Use Big Calendar itself, not an ALLA OS Calendar that imitates Big Calendar.

The implementation must preserve the upstream Calendar structure, rendering, navigation, views, event layout, drag-and-drop, resize behavior, responsive behavior, and dark-mode behavior.

Customization is limited to:

- ALLA OS theme integration
- Calendar projection adapter
- CRM permission enforcement
- Activity integration
- source-record navigation
- timezone and date integration

Reimplementation of Calendar rendering is prohibited.

---

# Background

EP.1.6.2 intended to adopt `lramos33/big-calendar` directly.

However, the current implementation recreated Calendar concepts locally, including:

- custom Calendar provider
- custom Calendar header
- custom Day view
- custom Week view
- custom Month view
- custom Agenda view
- custom Calendar slots
- custom event cards
- custom drag-and-drop handling
- command-based resize approximation

The resulting UI is structurally and visually different from the upstream Big Calendar.

This task corrects the implementation by removing the recreated Calendar UI and adopting the upstream source components directly.

---

# Depends On

- EP.1.6 Calendar Projection, Workspace & Big Calendar Foundation
- EP.1.6.1 Calendar Empty State Rendering Improvement
- EP.1.6.2 Direct Big Calendar UI Adoption
- EP.1.7 My Day Workspace Foundation
- AR.2 Workspace UI/UX Design Note
- ENG.0 Engineering Constitution

---

# Review Required

Review before implementation:

## Governance

- `AGENTS.md`
- `LAYOUT.md`
- `docs/standards/engineering-constitution.md`
- `docs/standards/architecture-rules.md`
- `docs/standards/ui-ux-rules.md`
- `docs/standards/task-review-checklist.md`
- `docs/security/crm-authorization-boundaries.md`

## Existing ALLA OS Implementation

- current Calendar Workspace
- current Calendar projection adapter
- current Calendar API
- `crm_calendar_projection`
- Activity APIs and services
- Business Event Outbox
- Projection Runtime
- Calendar projection consumer
- My Day Calendar consumers
- CRM navigation
- timezone and date utilities

## Upstream Source

Review:

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

Pinned commit:

```text
fbb8485e3d54b267261056c784632229ba6f7bc3
```

Review upstream:

- `src/calendar/**`
- provider and context
- Calendar container
- header and navigation
- Day view
- Week view
- Month view
- Agenda view
- Year view
- event components
- event-positioning logic
- overlapping-event handling
- multi-day-event handling
- drag-and-drop
- resize
- user filtering
- working hours
- responsive behavior
- dark mode
- accessibility
- dependencies
- MIT license

---

# Non-Negotiable Rule

The implementation must not recreate Calendar UI components that already exist upstream.

The following are prohibited:

- writing a new Month grid
- writing a new Week grid
- writing a new Day grid
- writing a new Agenda renderer
- writing a new Calendar toolbar
- writing a new Calendar header
- writing a new event-positioning engine
- writing a new overlapping-event algorithm
- writing a new multi-day-event layout
- writing a new drag-preview system
- writing a new resize system
- replacing upstream Calendar views with shadcn card grids
- retaining the current locally recreated Calendar as the active renderer

Where an upstream source component exists, that component must be copied and adapted directly.

---

# Approved Customization Boundary

Only the following customization is permitted.

## Theme Integration

Allowed:

- map colors to ALLA OS semantic tokens
- map typography
- map borders
- map radius
- map focus ring
- map dark-mode variables
- map button variants
- map icon registry

Not allowed:

- redesign the Calendar composition
- replace upstream grids
- replace upstream toolbar layout
- replace upstream event layout
- replace event-positioning behavior

## Projection Adapter

Allowed:

- map `CalendarProjectionItem` to upstream Calendar event types
- normalize date and timezone values
- map owner and assignee
- map customer and project context
- attach editable and milestone metadata
- attach source-domain references
- attach visibility metadata

The adapter must remain independent from React rendering.

## CRM Permission Integration

Allowed:

- remove unauthorized events before rendering
- disable drag and resize for read-only items
- restrict internal-only Activities
- redact pricing-sensitive content
- restrict user filters to authorized users
- enforce manager and team scope

The server remains authoritative.

Client-side flags must not replace server permission checks.

## Activity Integration

Allowed:

- create Activity
- open Activity
- reschedule Activity
- resize Activity
- complete Activity
- cancel Activity
- reassign Activity
- navigate to Customer
- navigate to Lead
- navigate to Opportunity
- navigate to Quotation

All mutations must use existing Activity APIs and services.

---

# Architecture Boundary

The governed data flow remains:

```text
Activity / Opportunity / Quotation / Approval
                    ↓
              Business Events
                    ↓
            Projection Runtime
                    ↓
          crm_calendar_projection
                    ↓
         CalendarProjectionItem
                    ↓
          ALLA Calendar Adapter
                    ↓
       Upstream Big Calendar Source
```

The upstream Calendar must not:

- read database rows directly
- query source domains directly
- become a source of truth
- persist Calendar records
- mutate projection rows
- own Activity lifecycle
- own milestone lifecycle
- calculate CRM authorization
- bypass Activity APIs
- bypass Business Events

---

# Scope

## Part 1 – Current Reimplementation Inventory

Inspect all Calendar files introduced by EP.1.6.2.

Expected candidates include:

```text
src/features/crm/calendar/big-calendar/provider.tsx
src/features/crm/calendar/big-calendar/header.tsx
src/features/crm/calendar/big-calendar/views.tsx
src/features/crm/calendar/big-calendar/calendar-slot.tsx
src/features/crm/calendar/big-calendar/event-card.tsx
src/features/crm/calendar/big-calendar/helpers.ts
src/features/crm/calendar/big-calendar/types.ts
```

Classify every file as:

- remove
- replace with upstream source
- retain as adapter
- retain as ALLA integration wrapper

Produce a removal and replacement matrix before implementation.

## Part 2 – Import Upstream Source

Copy the required upstream Calendar source into an isolated directory.

Recommended structure:

```text
src/features/crm/calendar/upstream-big-calendar/
├── components/
├── contexts/
├── hooks/
├── helpers/
├── interfaces/
├── types/
├── styles/
├── LICENSE
└── UPSTREAM.md
```

Rules:

- preserve upstream structure where practical
- preserve upstream file names where practical
- preserve attribution
- keep local modifications reviewable
- do not mix ALLA business integration into upstream files
- record every modified upstream file

## Part 3 – Preserve Upstream Composition

Use the upstream composition directly.

Expected structure:

```text
CalendarProvider
        ↓
ClientContainer / CalendarContainer
        ↓
CalendarHeader
        ↓
Selected View
        ├── Day
        ├── Week
        ├── Month
        ├── Agenda
        └── Year
```

Do not wrap upstream views inside a replacement Calendar layout that changes their structure.

## Part 4 – Replace Current Active Calendar UI

Update:

```text
/dashboard/crm/calendar
```

to render the actual upstream Calendar source.

The ALLA Calendar Workspace may retain only:

- `PageContainer`
- permission boundary
- server and React Query data loading
- projection adapter
- user adapter
- Activity mutation handlers
- event detail sheet
- optional supporting status messages

Remove the locally recreated active Calendar renderer.

## Part 5 – Calendar Projection Adapter

Implement or revise:

```ts
mapCalendarProjectionToUpstreamEvent(
  item: CalendarProjectionItem
): UpstreamCalendarEvent
```

The mapping must include:

- id
- title
- description
- start date
- end date
- all-day state
- timezone
- location
- owner
- assignee
- avatar
- Activity type
- Calendar category
- priority
- overdue state
- Hot Project state
- editable state
- milestone state
- source entity type
- source entity id
- customer id
- lead id
- opportunity id
- quotation id
- pricing-sensitive state
- internal-only state

The upstream component must never receive unrestricted database rows.

## Part 6 – Permission-Aware User Adapter

Implement:

```ts
mapCrmCalendarUserToUpstreamUser()
```

User data must come from a server-authorized Calendar user endpoint.

Support:

- current user
- permitted team members
- manager scope
- branch scope
- product scope
- existing display resolver
- avatar resolver

Do not load every organization user and hide unauthorized users in the browser.

## Part 7 – Direct Header and Toolbar Adoption

Use the upstream header and toolbar directly for:

- Today
- Previous
- Next
- Date-range title
- View selector
- User filter
- Date navigation

A thin URL synchronization adapter may persist:

- selected date
- selected view
- lens
- selected users

Do not recreate the toolbar.

## Part 8 – Direct Day View Adoption

Use upstream Day view directly.

Required behavior:

- real time grid
- working-hour rows
- event positioning based on start and end time
- overlapping-event layout
- current-time indicator
- Today highlight
- drag targets
- resize behavior
- empty grid when there are no events

Do not render a manual list of hour cards as Day view.

## Part 9 – Direct Week View Adoption

Use upstream Week view directly.

Required behavior:

- seven-day time grid
- current-day highlight
- current-time indicator
- all-day area where supported
- overlapping events
- event drag between days and times
- resize behavior
- empty grid when there are no events

Do not recreate the Week grid.

## Part 10 – Direct Month View Adoption

Use upstream Month view directly.

Required behavior:

- upstream month-cell layout
- upstream row sizing
- Today highlight
- event stacking
- event overflow
- multi-day events
- date-cell interaction
- empty month grid
- responsive event density

Do not render independent card-style date cells.

## Part 11 – Direct Agenda View Adoption

Use upstream Agenda view directly.

Agenda may show a full list-style empty state when no events exist.

Remove the separately recreated ALLA Agenda renderer when upstream Agenda is available.

## Part 12 – Year View Decision

Adopt upstream Year view when compatible.

Year view may be excluded only when documented evidence shows:

- incompatibility
- unacceptable performance
- accessibility issues
- unsupported data behavior

Document the final decision.

## Part 13 – Direct Drag-and-Drop Integration

Use upstream drag-and-drop behavior.

For editable Activities:

```text
Upstream Drag
        ↓
ALLA Interaction Adapter
        ↓
Activity Reschedule Command
        ↓
Activity API
        ↓
Business Event Outbox
        ↓
Calendar Projection Refresh
```

Rules:

- permission validated by server
- read-only milestone cannot move
- completed Activity cannot move
- cancelled Activity cannot move
- failed mutation restores the original position
- projection rows are never mutated directly

## Part 14 – Direct Resize Integration

Use the actual upstream resize interaction.

Remove the current duration-extension approximation.

For editable Activities:

- support start/end resizing as provided upstream
- validate minimum duration
- validate Activity lifecycle
- call Activity API
- rollback on failure
- reconcile with projection update

Milestones must not show resize handles.

## Part 15 – Upstream Event Rendering

Use upstream event rendering and event-positioning logic.

Minimal ALLA-specific rendering additions may show:

- title
- Activity type
- milestone type
- customer
- opportunity or quotation
- owner or assignee
- overdue badge
- Hot Project badge
- read-only badge

Do not replace every upstream event with an unrelated shadcn card.

## Part 16 – Event Detail Integration

Selecting an event opens an ALLA integration surface outside the upstream rendering core.

### Editable Activity

Support:

- Activity detail
- Complete
- Reschedule
- Cancel
- Reassign
- Open source record

### Read-Only Milestone

Support:

- Open Opportunity
- Open Quotation
- Open Approval
- Show milestone explanation
- Create related Activity

The detail surface must not become a second Calendar state store.

## Part 17 – Empty-State Behavior

### Day / Week / Month

Always render the upstream Calendar grid.

When empty:

- pass an empty event list
- preserve navigation
- preserve time and date slots
- optionally show a lightweight non-blocking hint
- allow Activity creation from a slot where supported

Do not replace the Calendar with a full-page empty card.

### Agenda

Use the upstream list-style empty state or a minimally themed version.

## Part 18 – Optimistic Update and Projection Reconciliation

Because Calendar projection updates asynchronously:

- keep optimistic event position after successful Activity API mutation
- track pending projection reconciliation
- invalidate and refetch Calendar data
- confirm updated schedule or projection version
- avoid snapping back to stale projection data
- rollback immediately when Activity API fails
- show a controlled error when reconciliation times out

Document the reconciliation state machine.

## Part 19 – Theme Token Integration

Apply only semantic ALLA OS theme mapping:

- typography
- background
- foreground
- borders
- focus ring
- dark mode
- icons
- buttons
- badges

Do not modify upstream structural layout merely to match existing custom Calendar code.

The visual target is:

> Upstream Big Calendar with ALLA OS theme tokens.

## Part 20 – Dependency Compatibility Review

Review upstream dependencies against:

- Next.js 16
- React 19
- Tailwind CSS 4
- shadcn/ui
- date-fns
- drag-and-drop library
- TypeScript
- Oxlint
- current build configuration

When a dependency is required for upstream parity, perform a compatibility and security review.

Do not replace a dependency-driven upstream interaction with an incomplete custom approximation merely to avoid installing the dependency.

## Part 21 – Accessibility Validation

Validate:

- keyboard navigation
- focus visibility
- screen-reader labels
- date-cell semantics
- event semantics
- drag accessibility
- resize accessibility
- color contrast
- dark mode
- reduced motion

Document all deviations from upstream.

## Part 22 – Responsive Validation

Validate:

- desktop
- laptop
- tablet
- mobile

Agenda may remain the default mobile view.

Day, Week, and Month must remain available.

Do not replace mobile views with unrelated custom renderers.

## Part 23 – Remove Obsolete Custom Code

After upstream parity is verified:

- delete the custom Day renderer
- delete the custom Week renderer
- delete the custom Month renderer
- delete the custom Agenda renderer
- delete the custom Calendar header
- delete the custom slot renderer
- delete the custom event-positioning logic
- delete the resize approximation
- delete unused styles
- delete dead hooks
- delete unused types and helpers

Do not keep two active Calendar implementations.

## Part 24 – Feature Flag and Rollback

A temporary feature flag may be used:

```text
CRM_BIG_CALENDAR_DIRECT_UI
```

Support:

- upstream direct Calendar UI
- previous Calendar UI only as short-lived rollback

After acceptance and stabilization:

- remove the old implementation
- remove the rollback flag
- document the removal

## Part 25 – Upstream License and Tracking

Preserve the MIT license.

Create:

```text
src/features/crm/calendar/upstream-big-calendar/LICENSE
src/features/crm/calendar/upstream-big-calendar/UPSTREAM.md
```

Document:

- repository URL
- commit hash
- copied files
- modified files
- removed files
- dependencies added
- local patch notes
- synchronization procedure

---

# Deliverables

1. Custom Calendar Removal Matrix
2. Upstream Source Import
3. Upstream Provider Integration
4. Upstream Container Integration
5. Upstream Header and Toolbar
6. Upstream Day View
7. Upstream Week View
8. Upstream Month View
9. Upstream Agenda View
10. Year View Adoption Decision
11. Calendar Projection Adapter
12. Permission-Aware User Adapter
13. Direct Drag-and-Drop Integration
14. Direct Resize Integration
15. Event Detail Integration
16. Activity Command Integration
17. Milestone Read-Only Integration
18. Empty-State Parity
19. Optimistic Projection Reconciliation
20. Theme Token Integration
21. Dependency Compatibility Report
22. Accessibility Review
23. Responsive Browser Review
24. Obsolete Custom Code Removal
25. Feature Flag and Rollback Plan
26. Upstream License and Attribution Record
27. Visual Parity Report
28. Regression Report

---

# Visual Parity Requirement

Compare ALLA OS Calendar with upstream using equivalent:

- selected date
- selected view
- event data
- working hours
- users
- viewport
- light mode
- dark mode

Verify:

- header composition
- toolbar
- navigation
- view switching
- Day grid
- Week grid
- Month grid
- Agenda layout
- Year layout when adopted
- event positioning
- overlapping events
- multi-day events
- event overflow
- current-time indicator
- Today highlight
- drag behavior
- resize behavior
- responsive behavior

Minor theme-token differences are acceptable.

Structural differences caused by reimplementation are not acceptable.

---

# Constraints

Must preserve:

- Activity ownership
- Opportunity ownership
- Quotation ownership
- Approval ownership
- Calendar Projection
- Business Events
- Transactional Outbox
- Projection Runtime
- CRM authorization
- Calendar API
- Timeline behavior
- My Day behavior
- existing source-domain services

Must not:

- recreate Calendar views
- retain active custom Day/Week/Month renderers
- retain the custom Agenda renderer
- create local Calendar event storage
- mutate projection rows directly
- bypass Activity APIs
- trust client-side permission flags
- import upstream demo backend
- import upstream demo database
- import upstream mock users
- import upstream app shell
- duplicate Activity logic
- duplicate Calendar business logic

No schema changes are expected unless an upstream integration requirement is reviewed and explicitly approved.

---

# Testing Requirements

## Visual Tests

- Day view parity
- Week view parity
- Month view parity
- Agenda view parity
- Year view parity when adopted
- light mode
- dark mode
- desktop
- tablet
- mobile

## Interaction Tests

- Today
- Previous
- Next
- view switching
- date selection
- user filter
- event selection
- Activity drag
- Activity resize
- milestone drag prevention
- milestone resize prevention
- API error rollback
- projection reconciliation

## Layout Tests

- overlapping events
- multi-day events
- all-day events
- empty Day
- empty Week
- empty Month
- empty Agenda
- long event titles
- many events in one day
- events outside working hours

## Permission Tests

- own Activity
- assigned Activity
- manager-permitted Activity
- unauthorized Activity
- internal-only Activity
- pricing-sensitive milestone
- read-only milestone
- completed Activity
- cancelled Activity

## Regression Tests

- Calendar API unchanged
- Calendar Projection unchanged
- Activity API unchanged
- Timeline unchanged
- My Day unchanged
- Dashboard unchanged
- Reports unchanged
- Notification unchanged
- Projection Worker unchanged
- no duplicate Activity event publication
- no direct projection mutation

## Quality Checks

- `npm run typecheck`
- targeted Oxlint
- Calendar unit tests
- interaction tests
- browser tests
- accessibility checks

---

# Acceptance Criteria

- The current reimplemented Calendar UI is removed from the active route.
- ALLA OS uses actual upstream `lramos33/big-calendar` source components.
- Month, Week, Day, Agenda, header, toolbar, navigation, event layout, drag, and resize are not recreated locally.
- Calendar structure and interaction reach upstream parity, except for approved ALLA OS theme-token differences.
- Calendar data continues to pass through `CalendarProjectionItem` and the adapter layer.
- Editable operations continue through Activity APIs.
- Read-only milestones cannot be moved or resized.
- CRM permission enforcement remains server authoritative.
- Day, Week, and Month render genuine upstream Calendar grids when empty.
- Agenda uses the upstream list presentation.
- Optimistic drag and resize reconcile safely with asynchronous projection updates.
- Obsolete custom Calendar code is removed.
- Upstream MIT license and pinned commit are documented.
- Existing Activity, Calendar Projection, Timeline, My Day, Dashboard, Reports, Approval, Notification, and Projection Runtime behavior remains unchanged.
- Visual parity, browser, responsive, interaction, accessibility, and regression validation pass.

---

# Success Criteria

ALLA OS uses Big Calendar itself—not a locally recreated approximation.

The Calendar Workspace preserves the upstream Calendar structure, views, event layout, drag-and-drop, resize, toolbar, navigation, responsive behavior, and dark-mode experience.

ALLA OS continues to own data, Activity commands, Business Events, Projection Runtime, security, and source-domain business rules.