Sync Repo-docs-CALENDAR-INTEGRATION-CONCEPT from project files

Repo-docs-CALENDAR-INTEGRATION-CONCEPT.-.md

@@ -0,0 +1,127 @@
+<!-- codex-wiki-sync:bbcb2561c7bb7b7241d69580 -->
+
+> Mirrored from `/mnt/DATA/git/govoplan-calendar/docs/CALENDAR_INTEGRATION_CONCEPT.md`.
+> Origin: `repository`.
+> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
+
+---
+# 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
+- 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 and UI foundation on which CalDAV sync, Open-Xchange integration, recurrence expansion, and free/busy 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.
+- Free/busy endpoint and capability for scheduling, appointments, and resource checks.
+- CalDAV sync adapter with collection sync tokens, ETags, REPORT handling, and conflict resolution.
+- 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.