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