# GovOPlaN Scheduling **Repository type:** module (domain). GovOPlaN Scheduling owns meeting scheduling and `Terminfindung`: finding suitable times across people, resources, calendars, constraints, and scheduling polls. This repository is initialized as a discoverable module seed. It exposes the module manifest, permission surface, role templates, and documentation metadata before runtime APIs, database models, migrations, and WebUI routes are introduced. The core boundary decision register is in `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`. ## Scope Scheduling owns: - meeting scheduling polls and proposals built on `govoplan-poll` - participant availability collection - time-window and resource constraints - candidate-slot ranking and conflict explanation - scheduling state, reminders, and decision handoff - optional links to external calendar/groupware systems through capabilities - organizer permissions and poll administration semantics Scheduling does not own: - calendar primitives such as events, recurrence, availability storage, resources, and calendar adapters; those belong in `govoplan-calendar` - fixed-slot public or internal appointment booking; that belongs in `govoplan-appointments` - tasks, case work, approvals, and generic workflow state; those belong in `govoplan-tasks`, `govoplan-cases`, and `govoplan-workflow` - mail delivery or notifications; those belong in `govoplan-mail` and `govoplan-notifications` ## Poll Audience Decision Scheduling polls should support both internal and external/public participation, but the first implementation may start internal-only. - Internal polls use Access/IDM identities, groups, permissions, and calendar free/busy capability lookups. - External/public polls use signed participation links through Portal, minimal participant identity, and explicit retention/privacy settings. - Mixed polls are allowed only when the organizer has permission to invite external participants and the poll explains which participant data is visible. ## Privacy, Retention, And Audit Participant availability is sensitive operational data. Scheduling must record: - poll creator, tenant, organizer, invited participants, and access scope - what each participant can see about other participants - retention deadline for availability responses and poll links - audit events for poll creation, invite send, response update, decision, cancellation, and handoff - trace IDs for mail/notification/portal handoff Availability responses should be removable or redacted after the poll decision unless a configured process requires longer evidence retention. ## Candidate Capabilities - `scheduling.polls` - `scheduling.availabilityCollector` - `scheduling.candidateSlots` - `scheduling.decisionHandoff` - `scheduling.portalParticipation` ## Manifest Dependency Decision The Scheduling manifest declares `poll` as a required dependency because availability collection and option/date poll primitives belong in `govoplan-poll`. Scheduling should model each meeting-finding flow as a poll-backed workflow: Poll owns candidate options, signed participation links, responses, visibility, and result aggregation. Scheduling stores the scheduling-specific context and uses Poll context fields to point back to its request or proposal resource. Typical workflow steps are collect availability, rank candidates, decide, notify participants, and hand off to Calendar or Appointments. The manifest declares `access`, `addresses`, and `evaluation` as optional dependencies. Scheduling uses Core's principal-aware people-search boundary to combine only the account and contact records visible to the current organizer; it never calls the instance-wide Identity search. It may trigger post-event or post-appointment feedback through Evaluation, and must not require any of these optional modules just to find a meeting time. ## Expected Integrations - `govoplan-poll`: required availability matrix and lightweight poll primitives - `govoplan-evaluation`: optional post-event, post-appointment, or process feedback - `govoplan-calendar`: availability, calendars, resources, rooms, recurrence, Open-Xchange/calendar adapters - `govoplan-appointments`: conversion from a selected meeting time into a booked appointment where appropriate - `govoplan-access` and `govoplan-idm`: optional participants, groups, directory lookup, permissions - `govoplan-mail` and `govoplan-notifications`: invitations, reminders, confirmations - `govoplan-portal`: external participant scheduling flows - `govoplan-workflow` and `govoplan-tasks`: follow-up work after a time is selected ## Participant selection boundary The editor uses Core's shared `PeoplePicker`. Its server-side search aggregates the optional `access.people_search` and `addresses.people_search` capabilities, and each provider applies the active principal and tenant visibility rules before returning a candidate. Scheduling exposes only the fields needed to select a person; provider provenance, address-book topology, group membership, and other internals are not returned by its picker endpoint. An account selection becomes an internal participant bound to that account. A visible address-book contact becomes an external participant with a bounded directory-selection reference and revision for later organizer editing. Manual name-and-email entry is available only while the request allows external participants. The picker stores neither provider-internal provenance nor a global Identity record reference in participant metadata. ## First Package Scaffold Decision The first backend implementation slice adds runtime APIs and storage around poll-backed scheduling requests: - scheduling request, candidate slot, and participant storage - automatic `govoplan-poll` availability poll creation - signed poll invitations for internal or external participants - request lifecycle APIs: draft, collecting, closed, decided, handed off, cancelled - result summaries sourced from Poll response aggregation - optional Calendar free/busy checks, tentative holds, and final event creation - notification outbox jobs for invitations, reminders, decisions, and cancellations - a first Scheduling WebUI package with request creation, slot matrix, Calendar actions, decisions, and notification-job creation The next slices should add real notification delivery workers, richer public participant pages, Calendar hold cleanup after decision, and advanced scoring constraints such as required participants and quorum rules. The active backlog lives in Gitea issues. ## Signed-participation policy gate Scheduling persists the response policy and snapshots it onto each governed Poll invitation. Public access uses `/scheduling/public/{request_id}/{token}`; Poll's ordinary public routes reject these gateway-bound tokens, so callers cannot bypass Scheduling's password and request checks. Passwords are write-only, stored only as salted PBKDF2 hashes, and failed checks are throttled through Redis when configured with a bounded in-process fallback. Poll is the transactional authority for response rules. Its governed submission holds the Poll-row lock while enforcing single choice, `Maybe`, participant email, comments, idempotency and per-option capacity. Scheduling then updates its participant projection in the same database transaction. Candidate-slot add/remove and participant-link revocation also go through the governed Poll capability; exact retries are idempotent, and option mutations invalidate only the affected answers. Public submissions lock the Scheduling request and participant rows before entering Poll, matching organizer edit lock order and making first-use email binding atomic. Both authenticated and public submission paths independently require the Scheduling request to be collecting and its deadline not to have passed, so a stale or incorrectly reopened Poll projection cannot accept a response. Changing a request deadline transactionally updates each governed invitation's expiry in Poll under owner- and gateway-bound row locks. The same link and invitation identity survive future, past, extended, and cleared deadlines: a past deadline makes the link unusable, a later extension makes the same link usable again, and clearing the deadline removes its expiry. No raw replacement token crosses the PATCH response, and existing responses plus participant status remain attached to the same durable respondent identity. Open lifecycle decision: cancellation closes the backing Poll, so submission fails, but an otherwise valid invitation can still resolve the reduced public view and show that the request was cancelled. Decide whether cancellation should revoke links immediately or retain that acknowledgement view for a bounded period; links without a deadline would otherwise remain readable. If the governed capability is absent, API responses advertise that policy enforcement is unavailable and restricted links fail closed. Plaintext passwords, token hashes, response-gateway internals and the participant roster are not exposed by the public response model. Authenticated participant list/detail projections likewise omit tenant, organizer, Poll and Calendar identifiers, connector metadata, invitation and identity bindings. Free/busy conflicts are reduced to useful time/status fields. Organizers and scheduling administrators retain the full management projection; participants retain candidate-slot revisions, their own marker and email, response settings, aggregates, and any roster names/statuses permitted by the configured privacy policy. The WebUI package exposes typed clients for the public access and submission endpoints. A signed-out browser page cannot yet be registered by a module: Core's `App` renders `PublicLandingPage` directly whenever `auth` is absent and only mounts module route contributions inside the authenticated branch. Until Core gains an explicit, allowlisted `publicRoutes` contract, notification action URLs under `/scheduling/public/{request}/{token}` must be treated as a blocked frontend handoff rather than a working guest page. The token is never moved into query parameters, browser storage, or an authenticated API contract while that shell boundary is unresolved. Creating, editing, and opening a request never issue public tokens or enqueue invitation delivery. The deprecated `create_participant_invitations` request field remains accepted for compatibility, defaults to `false`, and has no side effect. Authenticated in-module responses can still lazily create a gateway-bound invitation whose token is discarded. Organizers and Scheduling administrators use the participant-specific invitation action instead: - `POST /scheduling/requests/{request_id}/participants/{participant_id}/invitation` with `{"action":"copy"}` rotates the previous invitation and returns the new relative action URL once. The response is marked `no-store`. - The same endpoint with `{"action":"send"}` rotates the invitation and passes its URL directly to the notification dispatch job. Neither the API response nor Scheduling's durable notification projection contains the token. - `DELETE` on the same resource revokes the active link immediately; exact repeats are idempotent. Links can be issued in any request state. Collection state and deadline checks remain independent submission requirements, so a link to a draft, closed, or decided request is read-only. Issue, copy, send-request, and revoke actions are audited with request and participant identifiers but never a bearer token. Only an organizer (under the ordinary Scheduling write policy) or a tenant-wide Scheduling administrator can use these actions. If notification delivery is not installed, `send` fails before rotating the current link and the organizer can use `copy` for separate distribution. ## FieldLabel omission register Scheduling uses the shared `FieldLabel` for form controls that need explanatory inline help. The only intentional omissions are: - Candidate-slot and participant DataGrid cells: column headers supply the visible label and each interactive cell has an accessible name. - Per-slot availability selects: the enclosing visible slot/date text is the native label for that individual choice. There are no other authorized Scheduling omissions. Inline help remains controlled by the user's shared interface setting; hiding it does not remove accessible labels.