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
• 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.

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.