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.