govoplan-calendar/docs/CALENDAR_INTEGRATION_CONCEPT.md

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 unlink immediately scrubs Calendar-owned credential ciphertext and external provider references and audits the deletion. External provider failure blocks retirement before queued work is changed; a later retry tolerates a provider secret already removed by an earlier attempt whose database transaction rolled back. Provider errors and audit details never contain credential values or secret references. 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.