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

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

The portal should request service contributions through core-mediated
capability and UI contribution contracts. It must not import domain module
internals.

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.