125 lines
5.5 KiB
Markdown
125 lines
5.5 KiB
Markdown
# govoplan-calendar
|
|
|
|
<!-- govoplan-repository-type:start -->
|
|
**Repository type:** module (domain).
|
|
<!-- govoplan-repository-type:end -->
|
|
|
|
GovOPlaN Calendar is the standalone calendar module. It provides tenant calendar collections, iCalendar/VEVENT event storage, a calendar WebUI, and integration boundaries for scheduling, tasks, mail, appointments, workflow, notifications, and external groupware.
|
|
|
|
## Ownership
|
|
|
|
This repository owns:
|
|
|
|
- backend module manifest `calendar`
|
|
- calendar permissions such as `calendar:calendar:read`, `calendar:event:read`, `calendar:event:write`, and `calendar:event:export`
|
|
- tenant calendar collections
|
|
- VEVENT storage with structured query fields plus raw iCalendar property preservation
|
|
- iCalendar import/export endpoints
|
|
- calendar WebUI package `@govoplan/calendar-webui`
|
|
- `/calendar` route and navigation contribution
|
|
|
|
Core owns auth, tenants, RBAC evaluation, database/session primitives, CSRF/API helpers, and shell layout.
|
|
|
|
## Views
|
|
|
|
The WebUI starts with the standard operational views:
|
|
|
|
- month
|
|
- week
|
|
- workweek
|
|
- day
|
|
- continuous week-row calendar, where scrolling moves line by line through weeks rather than jumping from one month page to the next
|
|
|
|
## iCalendar model
|
|
|
|
The first backend implementation stores VEVENT data in two layers:
|
|
|
|
- normalized fields for API range queries and calendar rendering
|
|
- raw iCalendar property records and generated `text/calendar` output so unsupported VEVENT properties and parameters can round-trip
|
|
|
|
CalDAV sync is implemented as a calendar-owned backend primitive. A CalDAV source
|
|
records the remote collection URL, sync token, ETag/ctag state, username,
|
|
credential reference, sync interval, sync direction, and conflict policy.
|
|
Credentials can be supplied transiently for manual sync. Persisted API-managed
|
|
sources accept only a password or token: Calendar stores an opaque, tenant- and
|
|
source-bound local reference, backed by the platform secret provider when one is
|
|
available or by an encrypted calendar-owned credential otherwise. Caller-selected
|
|
environment and external-provider references are rejected. Trusted deployment
|
|
code may resolve an `env:NAME` reference only through the separate deployment
|
|
configuration helper.
|
|
|
|
Open-Xchange is available as an explicit profile over that CalDAV engine. The
|
|
calendar dialog can retain optional connector-profile, identity/group-mapping,
|
|
and resource-calendar references. Resource bindings mark the collection as a
|
|
resource calendar. Optional connector modules can configure the same profile
|
|
through the Core-mediated `calendar.externalProfiles` capability; Calendar has
|
|
no hard dependency on Connectors, IDM, or Access mapping implementations.
|
|
|
|
Deleting a source or its calendar immediately scrubs Calendar-owned ciphertext
|
|
and provider references and emits non-secret audit evidence. If an external
|
|
secret provider cannot confirm deletion, the operation fails closed without
|
|
retiring the source or cancelling its queued work; retry is idempotent after a
|
|
database rollback. Destructive module retirement first deletes and audits all
|
|
active and legacy retained provider secrets and stops before table removal on
|
|
provider failure.
|
|
|
|
Inbound sync uses CalDAV `calendar-query` for full sync and `sync-collection`
|
|
when a sync token exists. It imports all VEVENT components in a resource and
|
|
soft-deletes local events when remote resources disappear. Two-way sources also
|
|
write local creates, updates, and deletes back with CalDAV `PUT`/`DELETE` and
|
|
ETag preconditions. If a remote resource changed, the local mutation is rejected
|
|
and the user must sync before retrying. A calendar-owned task,
|
|
`govoplan_calendar.sync_due_caldav_sources`, can run due sources in a worker or
|
|
cron-style scheduler. Due-source and outbox-dispatch HTTP routes require a
|
|
service-account principal and are not interactive administration actions.
|
|
|
|
Calendar exposes collection and credential management, sync status/actions,
|
|
bounded outbound-change diagnostics and guarded retry/reconcile/discard recovery,
|
|
durable per-user view preferences, recurrence expansion, detached occurrence
|
|
overrides, instance/series editing, and a free/busy API primitive for scheduling
|
|
and appointment modules. It is not yet a CalDAV network server: external clients
|
|
cannot use GovOPlaN itself as their CalDAV endpoint, and scheduling inbox/outbox
|
|
delivery remains owned by the scheduling and mail integration work.
|
|
|
|
Calendar also publishes `privacy.dsar.calendar`. Core's governed
|
|
data-subject-request workflow can use it to find tenant-scoped organizer,
|
|
attendee, preference, synchronization, outbox, and migration metadata. The
|
|
provider isolates the matching party and omits raw ICS, connector locators,
|
|
credentials, tokens, worker claims, and unrelated attendees. It classifies
|
|
synchronized and correlated state as retained evidence, leaves shared event
|
|
changes for manual review, and can safely delete only the subject's personal
|
|
view preference after revalidating tenant and ownership.
|
|
|
|
## Development
|
|
|
|
Install through the core environment:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan-core
|
|
./.venv/bin/python -m pip install -r requirements-dev.txt
|
|
```
|
|
|
|
Run the WebUI from the core host:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan-core/webui
|
|
PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run dev
|
|
```
|
|
|
|
## Module integration
|
|
|
|
Backend entry point:
|
|
|
|
```toml
|
|
[project.entry-points."govoplan.modules"]
|
|
calendar = "govoplan_calendar.backend.manifest:get_manifest"
|
|
```
|
|
|
|
Frontend package:
|
|
|
|
```text
|
|
@govoplan/calendar-webui
|
|
```
|
|
|
|
The integration concept is maintained in `docs/CALENDAR_INTEGRATION_CONCEPT.md`.
|