From 1407617e85df757fa6daee29f6933d936f8748bd Mon Sep 17 00:00:00 2001 From: zemion Date: Sat, 1 Aug 2026 08:56:11 +0200 Subject: [PATCH] Sync Repo-docs-SERVICE-DIRECTORY-CONCEPT from project files --- Repo-docs-SERVICE-DIRECTORY-CONCEPT.-.md | 108 +++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 Repo-docs-SERVICE-DIRECTORY-CONCEPT.-.md diff --git a/Repo-docs-SERVICE-DIRECTORY-CONCEPT.-.md b/Repo-docs-SERVICE-DIRECTORY-CONCEPT.-.md new file mode 100644 index 0000000..da3e4f5 --- /dev/null +++ b/Repo-docs-SERVICE-DIRECTORY-CONCEPT.-.md @@ -0,0 +1,108 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-portal/docs/SERVICE_DIRECTORY_CONCEPT.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Role-Based Service Directory Concept + +GovOPlaN Portal should expose a role-aware service directory. The directory is +not a marketing catalogue; it is the user-facing map of what a person can do in +the configured institution. + +Portal owns presentation, discovery, entry, and channel-specific availability. +It must not become the long-term owner of the institutional service definition. +A shared Services contract should own the versioned promise independently so +Cases, Forms, Workflow Engine, Reporting, external publication, and more than +one portal surface can consume the same definition. + +## Purpose + +The service directory should help users find the right administrative action +without knowing the internal module layout. Available services depend on +tenant, role, organization unit, policies, installed modules, and configuration +packages. + +Examples: + +- apply for a permit +- submit documents for an existing case +- request an appointment +- send a secure postbox message +- report an issue +- book a resource +- start an internal workflow + +## Contract + +A service entry should describe: + +- service key and label +- owning module or configuration package +- audience and role/function requirements +- required installed/enabled modules +- required capabilities +- form, workflow, postbox, task, or external connector entry point +- policy and availability blockers +- user-facing explanation and required documents +- audit and evidence expectations +- version and effective interval +- legal or organizational basis, deadlines, fees, remedies, and service-level + expectations +- responsible organization/function, mandate/jurisdiction, result/decision, + publication, and records bindings + +The portal should request service contributions through core-mediated +capability and UI contribution contracts. It must not import domain module +internals. + +The first implementation may consume module-contributed service definitions. +Create a separate `govoplan-services` repository only when definitions require +independent persistence/lifecycle and are consumed outside Portal by at least +one other procedure or publication surface. Extraction must keep stable service +keys and compatibility for existing Portal links. + +Service visibility must consume access semantics through kernel capabilities: + +- `access.semanticDirectory` resolves the actor's identity, account, + organization-unit function assignments, delegations, and role mappings. +- `access.explanation` provides the explanation shown when a service is + available or blocked because of a missing function, role, right, or policy. + +Service entries should support function requirements directly, not only role +requirements. A function requirement may apply to one organization unit or to +that unit and all subunits, matching the access assignment scope. + +## UX Rule + +The directory should explain unavailable services when the reason is useful: +missing role, disabled module, tenant policy, missing connector, maintenance +mode, or unavailable external provider. It should hide only services that are +irrelevant or intentionally undiscoverable by policy. + +## Implemented Headless Slice + +`portal.service_directory` consumes the optional `services.definitions` +capability. It returns only tenant-scoped definitions and distinguishes +`available`, `unavailable`, and `hidden` states. Draft, retired, +outside-effective-time, and audience-inapplicable services are hidden. A +suspended service or missing required module/capability remains discoverable +with stable reason codes and its configured explanation reference. + +The definition provider remains responsible for access and policy filtering. +Portal cannot widen its result and returns an empty directory when no provider +is installed. No service definition is persisted in Portal. + +Tenant/package specializations are derived before presentation through Core's +restrictive Service rule. They carry their parent version and may narrow +audience, channels, effective time, and publication or add prerequisites, +required evidence, legal bases, and bindings. They cannot silently loosen the +system/package definition. + +Policy, Mandate, connector, maintenance, and configuration requirements are +evaluated through the optional `services.availability` capability. Module and +capability requirements are checked against the active registry, and audience +requirements against the supplied actor projection. Unknown requirements fail +closed. Each requirement declares whether failure remains visible with an +explanation or makes the entry undiscoverable.