# NuQloud Master Calendar plan

## Goal

Provide each authenticated Nextcloud user a single, read-only CalDAV calendar
named **NuQloud Master Calendar**. It dynamically combines every calendar the
user can read and has enabled. A personal setting can restrict it to calendars
the user can edit. The master collection is hidden by default in the Nextcloud
Calendar grid so local calendars remain the editable, non-duplicated view.

## Scope for the first release

- Use the Nextcloud Calendar provider API, so the virtual calendar appears in
  the existing Calendar app and at the standard CalDAV endpoint.
- Include native, shared, and subscribed calendars returned by the DAV
  providers. Disabled calendars are excluded.
- Default to `all`; allow `editable` as the personal source filter.
- Mark the master collection as disabled by default for the Nextcloud Calendar
  grid. It remains discoverable and fully readable through CalDAV clients.
- Expose a read-only collection. Creating, updating, deleting, and sharing
  through the master calendar are intentionally unavailable.
- Namespace virtual event UIDs and resource filenames by source calendar. This
  prevents collisions when two source calendars use the same UID while keeping
  recurrence instances from one source together.

## Architecture

```
CalDAV client -> standard Nextcloud CalDAV home -> MasterCalendarProvider
                                           -> MasterCalendar (read-only)
                                           -> native + subscription providers
                                           -> accessible source calendars
```

The app registers a direct CalDAV provider and declares the required `dav` app
type. This avoids the public calendar manager, whose search result format is
incompatible with a virtual CalDAV collection. It asks the DAV app's native and
subscription providers for source calendars; those provider classes are
implementation details, so the app explicitly targets Nextcloud 32–34 and
must be rechecked for future major versions.

## Permissions and privacy

- The provider receives the authenticated principal from Nextcloud; no route
  or CalDAV request accepts a user ID.
- Source events are obtained through Nextcloud's existing permission-aware DAV
  providers. A removed share disappears on the next request/sync.
- `editable` requires `ICalendarIsWritable::isWritable()`. Ownership is not
  used as a substitute for actual permission.
- The master collection itself advertises read-only permissions. It never
  chooses a destination calendar for an edit.

## Validation and rollout

1. Run PHP lint and the static validation script included with the app.
2. Create `NuQloud/nuqloud-master-calendar` in Gitea and push this folder as
   its repository root.
3. Run `./recreate-devprod.sh --nossl` (or the deployment's normal recreate).
   The updated scripts clone the repository into `custom_apps` and enable it.
   The updater scopes Git's safe-directory exception to this app checkout for
   the one fast-forward command, so a Nextcloud-owned app directory does not
   require a global Git configuration change.
4. In Nextcloud personal settings, select the source mode. Add the normal
   CalDAV account URL to a test client and select only **NuQloud Master
   Calendar**. Verify all/shared/subscribed calendars, disabled calendars,
   editable-only filtering, recurrence, and share revocation.

## Deferred work

- Per-calendar include/exclude overrides.
- Writable routing policy and conflict handling.
- Incremental sync tokens/ETags tuned for large calendar sets.
- Automated integration tests against supported Nextcloud releases.