alla-allaos-fullstack/docs/implementation/task-ep1.6-calendar-projection-workspace-big-calendar-foundation-2026-07-13.md

# Task EP.1.6 Calendar Projection, Workspace & Big Calendar Foundation - 2026-07-13

## Scope Delivered

- introduced `crm_calendar_projection` materialized read model schema and migration `drizzle/0006_massive_scalphunter.sql`
- added Calendar projection contracts under `src/features/crm/calendar/**`
- added Activity business-event mapping for scheduled Activity calendar rows
- added terminal Activity event handling that removes completed/cancelled/deleted Activity rows from Calendar projection
- added Calendar projection consumer, registration seam, rebuild plan contract, query service, API route, React Query service, and dashboard workspace route
- added `CalendarProjectionItem -> BigCalendarEvent` adapter so UI never consumes database rows directly
- added Calendar Workspace UI at `/dashboard/crm/calendar` with Agenda, Day, Week, Month tabs, summary cards, search, empty/loading states, and read-only/editable visual distinction
- added Calendar navigation item under CRM
- preserved Activity, Timeline, Dashboard, Reports, Notifications, Approval, Follow-up APIs, and source-domain ownership

## Review Summary

Reviewed before/during implementation:

- `AGENTS.md`
- `plans/task-ep.1.6.md`
- `docs/standards/engineering-constitution.md`
- `docs/standards/project-foundations.md`
- `docs/standards/architecture-rules.md`
- `docs/standards/ui-ux-rules.md`
- `docs/standards/task-review-checklist.md`
- `docs/security/crm-authorization-boundaries.md`
- `docs/business/relationship-sales-workspace-blueprint-v1.md`
- `docs/implementation/task-ar.2-epic-technical-design-2026-07-07.md`
- `docs/implementation/task-ar.2-workspace-ui-ux-design-note-2026-07-07.md`
- `docs/implementation/task-bu-r.0.1-workspace-activity-business-blueprint-2026-07-07.md`
- `docs/implementation/task-ep1.4-projection-foundation-delivery-reliability-2026-07-13.md`
- `docs/implementation/task-ep1.4.1-transactional-outbox-activation-worker-runtime-2026-07-13.md`
- `docs/implementation/task-ep1.5-timeline-projection-foundation-2026-07-13.md`
- existing Projection Runtime, Activity Business Events, Timeline Projection, CRM security, and date formatting utilities

## Big Calendar Source Audit

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

Findings:

- Compatibility: upstream is a Next.js, TypeScript, Tailwind, shadcn-oriented calendar app, but targets Next.js 14 and Tailwind v3 while this repo is Next.js 16 and Tailwind v4.
- React/Next: source is useful as UI composition reference, but the upstream app shell, provider model, demo data, and direct event mutation flow are not compatible with ALLA OS projection governance.
- shadcn/Tailwind: visual approach is compatible, but code must be adapted to existing dashboard shell and token usage.
- Accessibility/dark mode/responsive: upstream explicitly supports responsive and dark-mode calendar behavior; ALLA OS implementation keeps shadcn primitives, semantic cards, badges, buttons, and deterministic date rendering.
- Timezone: upstream uses general date-fns/date string assumptions; ALLA OS calendar rendering uses `src/lib/date-format.ts` and stores projection timezone as `Asia/Bangkok`.
- Drag/drop: upstream supports direct drag/drop rescheduling. ALLA OS does not persist Calendar mutations directly; drag/resize must call Activity APIs, publish Business Events, and refresh the projection.
- License: upstream repository is MIT licensed.

Adoption decision:

- Adopted conceptually: Agenda/Day/Week/Month views, toolbar/search pattern, event rendering, editable vs read-only event behavior, user/lens filter seam, working-hours/timezone constraints.
- Rejected: upstream app shell, backend assumptions, mock event store, direct event CRUD, global Calendar context, uncontrolled user lists, direct drag/drop persistence.
- Modification strategy: implement native ALLA OS components under `src/features/crm/calendar/`, keep projection adapter as boundary, and wire future drag/resize only through Activity services.

## Implementation Summary

### Calendar Schema

Added `crm_calendar_projection` with organization, branch, product, source refs, activity/customer/lead/opportunity/quotation/approval refs, owner/assignee, event provenance, title/summary/location, start/end/timezone, priority/category, editable/milestone/overdue/hot-project/all-day flags, visibility metadata, source event, projection version, timestamps.

Indexes cover organization/date range, owner/assignee/date range, branch/date range, category/date range, customer/date range, activity/event lookup, and event/version idempotency.

### Calendar Builder and Consumer

Activity events supported:

- `activity.created`
- `activity.assigned`
- `activity.reassigned`
- `activity.started`
- `activity.rescheduled`
- `activity.completed`
- `activity.cancelled`
- `activity.deleted`

Non-terminal scheduled Activity events upsert one current Calendar row per Activity. Terminal events delete the Activity calendar row so Calendar remains a forward-looking operational workspace, not a history timeline.

### Query and Security

Calendar query service supports:

- date range
- user/team user IDs
- branch/product
- customer/lead/opportunity/quotation
- activity type/category/priority
- overdue/milestone/hot-project flags
- search
- Personal/Team/Manager/Executive lens contract

The service applies bounded SQL first, then server-side CRM scope checks through `CrmSecurityContext` and `canAccessScopedCrmRecord()`. Owner/assignee direct visibility is preserved. Internal-only rows remain restricted unless directly assigned or organization-wide scope applies.

### Workspace

Added `/dashboard/crm/calendar` using `PageContainer`, React Query prefetch/hydration, and existing shadcn UI primitives.

Workspace includes:

- summary cards: Due Today, Overdue, Meetings, Hot Projects
- Agenda default view
- Day/Week/Month tabs
- search
- empty/loading states
- event cards with read-only milestone vs editable activity distinction

### Rebuild and Health

Calendar rebuild contract added as a plan/result helper for hybrid rebuild:

- sources: Activity, Opportunity, Quotation, Approval, Business Event replay
- supports organization/date range/dry-run/reset/restart contract

Runtime checkpoint/retry/dead-letter behavior remains owned by Projection Runtime. Calendar consumer can be registered with runtime consumers without changing source-domain writes.

## Delivery Matrix

| Source | Business Event / Source Signal | Projection | Calendar Item | Workspace |
| --- | --- | --- | --- | --- |
| Activity | `activity.created`, assigned, reassigned, started, rescheduled | `crm_calendar_projection` | editable Activity event | Calendar Agenda/Day/Week/Month |
| Activity | `activity.completed`, cancelled, deleted | delete projection row | removed from forward schedule | Calendar refresh |
| Opportunity | Expected Award / Expected Delivery / Hot Project | rebuild contract seam | read-only milestone | future source adapter |
| Quotation | Valid Until / Delivery milestone | rebuild contract seam | read-only milestone | future source adapter |
| Approval | Due / Escalation | rebuild contract seam | read-only milestone | future source adapter |

## UI/UX Review

- Layout follows AR.2 Calendar Workspace note: PageContainer, header, compact filter/search, calendar body, summary cards.
- Agenda is default manager/mobile-friendly dense view.
- Day/Week/Month views are available as foundation tabs.
- State coverage includes loading skeleton and empty state.
- Status is not color-only: badges show overdue/hot-project/read-only/category text.
- Date/time rendering uses `src/lib/date-format.ts`.
- UI avoids importing upstream shell, backend, provider, or mock data.

## Known Follow-ups

- Opportunity, Quotation, and Approval milestone projection adapters are contract-ready but not populated until those domains publish durable milestone events or rebuild source adapters are expanded.
- Drag/drop and resize UI actions are represented as Activity-only affordances, but direct mutation wiring is intentionally deferred until Activity reschedule API integration is added to Calendar UI.
- User/team filter contract exists; UI currently exposes lens/search foundation only. Manager team hierarchy should be wired after team graph/scope UX is formalized.
- Working hours and conflict detection are schema/service-ready concepts but need fuller UI and source preference integration in a follow-up slice.
- `INITIAL_PROJECTION_CONSUMERS` remains skeleton-safe for foundation runtime tests; CRM runtime composition should opt into `CRM_CALENDAR_PROJECTION_CONSUMERS` or combined CRM registration when running production projection workers.

## Verification

- `npm run typecheck`
- `node --disable-warning=ExperimentalWarning --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types --test src/features/crm/calendar/server/builder.test.ts src/features/crm/timeline/server/builder.test.ts src/features/foundation/projections/runtime.test.ts`
- `npx oxlint src/features/crm/calendar src/app/api/crm/calendar src/app/dashboard/crm/calendar src/features/foundation/projections/consumers.ts src/features/foundation/projections/registry.ts src/features/crm/timeline/server/registration.ts src/db/schema.ts`
- `npm run db:generate`

## Outcome

EP.1.6 now has a governed Calendar Projection and first Calendar Workspace foundation. Calendar remains additive, rebuildable, and non-authoritative. Activity remains the only editable operational work source; Timeline remains unchanged as historical chronology.