# 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, referenced from
environment variables with `env:NAME`, stored through a platform secret provider
when one is available, or stored as encrypted calendar-owned credentials.

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.

This is not yet a full CalDAV network server. Scheduling inbox/outbox behavior,
CalDAV server endpoints, UI credential management, and full user-facing
recurrence editing remain follow-up work. The backend now includes a free/busy
API primitive for scheduling and appointment modules.

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