# GovOPlaN Calendar Integration Concept ## Module Boundary `govoplan-calendar` owns calendar primitives: - calendar collections - VEVENT storage and iCalendar import/export - event recurrence data, recurrence exceptions, and future recurrence expansion - availability and free/busy semantics - resources such as rooms, shared equipment, and service desks - groupware calendar adapter boundaries, including CalDAV and Open-Xchange Calendar does not own meeting-poll decisions, bookable service appointments, task lifecycle, mail transport, or document lifecycle. Those modules should reference calendar events through stable IDs, iCalendar UIDs, capabilities, or API contracts. ## First Implementation The first standalone module provides: - `CalendarCollection` records for tenant calendars - `CalendarEvent` records for VEVENT data - normalized query fields: start, end, summary, location, all-day flag, status, transparency, classification, calendar ID, UID, recurrence ID, sequence, source, and ETag - iCalendar preservation: raw VEVENT properties, parameters, and generated `text/calendar` export - API endpoints for listing calendars, creating/updating/deleting events, importing iCalendar, and exporting event ICS - free/busy API primitive with recurrence expansion for scheduling and appointment conflict checks - calendar-owned CalDAV sync sources with credential references, scheduled due-sync metadata, full/incremental inbound sync, two-way PUT/DELETE writes, and ETag conflict handling - a Calendar-owned durable desired-state outbox for two-way CalDAV writes. Event state and the exact external resource snapshot commit atomically; workers use deterministic hrefs, conditional requests, expiring leases, bounded exponential retry, and semantic GET reconciliation after ambiguous outcomes - WebUI views: month, week, workweek, day, and continuous week-row scrolling The first implementation is not yet a full CalDAV network server. It is the internal calendar storage, sync, availability, and UI foundation on which Open-Xchange integration, richer recurrence editing, scheduling inbox/outbox behavior, and CalDAV server endpoints can be built. ## Outbound delivery operations No event API or cross-module capability performs CalDAV network I/O inside the caller's transaction. A local mutation instead creates a `calendar_outbox_operations` row containing the exact desired ICS resource, target href, expected ETag, conflict-policy snapshot, and idempotency key. The registered `govoplan.calendar.dispatch_outbox` worker commits an expiring lease before doing network I/O and commits each outcome independently. If a worker loses the database connection after a successful remote write, the next attempt reads the remote object and compares semantic ICS fingerprints. A matching PUT or an already absent DELETE completes successfully without a blind duplicate write. Pending updates for one href supersede older never-attempted rows; attempted predecessors are reconciled first, and updates queued behind an in-flight write inherit the ETag produced by that write. Delivery and inbound REPORT application take the same source-row lock, and only one operation per source is leased at a time. This deliberately trades per-source throughput for a simple ordering guarantee: a stale inbound report cannot land after a newer outbound result, and queued leases do not expire while waiting behind another network request for the same source. Operators can list, dispatch, retry, reconcile, and discard tenant operations through the `/calendar/caldav/outbox` administration endpoints. Terminal ETag conflicts and exhausted retries remain the current local desired state and shield that resource from inbound overwrite until explicitly resolved. Discarding is the administrator's accept-remote transition: it is allowed only for the latest generation, atomically cancels its unresolved predecessor chain, marks the event projection as discarded, clears the sync token, and schedules a full inbound reconciliation so an unchanged remote object is not missed. Disabling outbound delivery or switching to inbound-only is rejected while unresolved desired state exists; retirement is the explicit exception and cancels unresolved work. Endpoint/calendar changes also require no active event bindings or unresolved delivery. Credential rotation does not discard committed desired state. Public event mutation cannot set sync-owned source hrefs, kinds, or ETags. Deleting a synchronized collection or retiring its source is a local unlink: it never deletes the remote collection or its remaining remote events. The current singular ownership model permits one active sync source per calendar; multi-source fan-in will require per-event source routing. Celery beat triggers recovery every minute, while root-transaction after-commit dispatch provides the normal low-latency path. ### Collection retirement and bulk event moves Collection deletion accepts two explicit, non-destructive external actions for `event_action="move"`: - `detach_keep_remote` applies only when the source collection is synchronized and the target is local. It moves the local event projections, clears their sync-owned source kind, href, ETag, and CalDAV projection metadata, retires the source locally, and cancels undelivered outbox state. An active delivery lease blocks the transaction. The action never enqueues a remote DELETE, so the remote collection and remote events remain unchanged. - `copy_to_remote` applies only when the source is local and the target has an active, enabled, two-way CalDAV source. It moves the local events and commits destination PUT desired states in the durable outbox in the same database transaction. Remote failures therefore remain visible and retryable without rolling back or hiding the local move. Local-to-local moves retain their existing behavior and do not accept an `external_action`. Implicit or mismatched actions, inbound-only destinations, and synchronized-to-synchronized moves are rejected. `remote_move` is a known but deliberately unsupported action: implementing it requires a separately approved saga for destination reconciliation, conditional source deletion, collision handling, and concurrent-edit policy. The WebUI does not offer that destructive mode. Resolved terminal rows (`succeeded`, `superseded`, and `cancelled`) are removed in bounded batches after `CALENDAR_OUTBOX_TERMINAL_RETENTION_DAYS` (90 days by default; `0` disables cleanup). `conflict` and `dead` rows are never removed by this cleanup because they still carry unresolved local desired state. Each periodic or after-commit dispatch also performs one bounded cleanup batch for the same tenant scope. ## Integration Points ### Scheduling `govoplan-scheduling` should use calendar for: - organizer availability lookup - candidate slot conflict checks - final event creation after a poll decision - participant invitation state as VEVENT attendees when a meeting becomes real Scheduling remains owner of polls, candidate ranking, external participation links, and decision audit. ### Appointments `govoplan-appointments` should use calendar for: - confirmed appointment placement - staff/resource conflict checks - room and desk calendars - cancellation or rescheduling events Appointments remains owner of public booking flows, service definitions, capacity rules, queues, and no-show handling. ### Tasks And Workflow `govoplan-tasks` and `govoplan-workflow` should use calendar for: - due-date and reminder calendar overlays - workflow deadlines - escalation dates - optional event creation for hearings, reviews, inspections, and internal meetings Tasks/workflow remain owners of assignment, status, SLA logic, and completion semantics. ### Mail And Notifications `govoplan-mail` and `govoplan-notifications` should use calendar for: - outbound iCalendar invites and updates - inbound invite parsing from messages - RSVP state changes - reminders and digest notifications Mail remains owner of SMTP/IMAP profiles and mailbox transport. Notifications remains owner of delivery channels and delivery policy. ### Documents And DMS `govoplan-dms` can link documents to events for: - agendas - minutes - attachments - legal deadlines - retention and audit context DMS remains owner of versions, locks, approvals, collaboration, legal hold, and document retention. ### Cases, Campaigns, Forms, And Portal Domain modules may attach calendar references to domain objects: - cases: hearings, inspections, review meetings - campaigns: send windows and review deadlines - forms: submission windows and office-hour sessions - portal: citizen-facing event or appointment visibility Calendar should expose reusable event and availability APIs instead of importing those modules. ### Connectors And Public-Sector Groupware `govoplan-connectors` should own generic connector catalogue behavior, connection setup patterns, and external-system inventory. Calendar owns the actual calendar semantics for: - CalDAV - Open-Xchange calendar - OpenDesk calendar stack integration - resource-calendar mapping - free/busy sync - recurrence and exception mapping - conflict handling The connector boundary should hand calendar a configured profile and credentials reference, not a domain-specific event model. ## Follow-Up Work - Full recurrence expansion for RRULE, RDATE, EXDATE, RECURRENCE-ID, overridden instances, and detached instances. - User-facing recurrence editing for RRULE, RDATE, EXDATE, RECURRENCE-ID, overridden instances, and detached instances. - UI management for CalDAV credentials, sync status, sync direction, and conflict resolution. - CalDAV server endpoints if GovOPlaN should expose calendars to external clients rather than only syncing remote collections. - Open-Xchange adapter that maps OX calendars, attendees, resources, recurrence, and free/busy to the internal calendar model. - Attendee RSVP workflow and mail/notification bridge. - Resource calendars for rooms, equipment, counters, and service desks. - Calendar ACLs beyond tenant-wide permissions.