nuqloud-master-calendar/PLAN.md

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.