govoplan-organizations/docs/ORGANIZATION_MODEL.md

Organization Model

The organization model answers where responsibility lives.

Layers

• Tenant: the administrative space.
• Organization unit type: an abstract type such as faculty, institute, committee, department, team, service desk, or legal entity.
• Organization structure: a named way to look at the institution. Several structures may exist in parallel, for example employer hierarchy, academic structure, committees, memberships, or classifications.
• Relation type: the permitted edge between units inside a structure.
• Organization unit: a concrete department, office, committee, service desk, school, institute, or other unit.
• Function: a named responsibility in an organization unit, such as clerk, reviewer, approver, committee secretary, intake desk, or resource manager.

A function says what responsibility exists and where. It does not by itself prove that the institution or function is legally or organizationally competent for a subject, territory, population, decision type, signature, or period. That effective mandate/jurisdiction belongs to a separate shared Mandates contract. Organizations retains only stable references needed to explain how a mandate attaches to a unit or function.

Governance And Templates

Concrete organization models are tenant-owned. Units, structures, relation types, relations, function types, and functions are never shared as one live global hierarchy across tenants.

The system may provide versioned organization-model templates. A tenant explicitly instantiates one template version and receives tenant-owned concrete records. The template reference and version are provenance, not a live parent model:

• tenants may run different template versions;
• a template update never silently mutates a tenant hierarchy;
• upgrading is an explicit diff and migration with preview, conflict reporting, and recorded provenance;
• system policy may constrain permitted unit, relation, structure, and function types;
• tenant administrators customize concrete records only within the effective policy.

This avoids ambiguous inheritance when institutions model responsibility differently. Template catalogue, instantiation, and explicit upgrades are available through the Organizations API and administration surface. The existing organization tables remain the canonical tenant-local state.

An upgrade starts by persisting a three-way comparison of the source template, the current tenant-owned model, and a newer published template version. The preview distinguishes compatible additions and changes from local divergence, destructive remapping, and invalid references. Local-only changes are retained; conflicts require an explicit keep, replace, or bounded mapping decision. The apply operation rejects stale source, target, or local state and records a new instantiation plus platform event. Cancelling a preview records the outcome but does not change tenant data. Consumers of organization references must respond to the applied event; Organizations does not rewrite another module's records.

Boundary With Identity And IDM

This module does not own login accounts, identity lifecycle, account linking, or identity-to-function assignments. govoplan-identity owns the identity/account directory. govoplan-idm records that an identity currently holds an organizational function and may constrain that link to one account.

Resolving accounts to identities, choosing candidate identities for an organization assignment, and importing those mappings from external directories belongs to govoplan-idm, not to organizations.

Boundary With Access

An IDM function assignment does not grant rights on its own. govoplan-access maps organization and IDM facts to roles, rights, permission decisions, delegation enforcement, and explain responses.

This separation keeps the institution model stable even when authorization policy changes.

Access Projection Migration

govoplan-access now prefers organizations.directory for organization units and function definitions when the Organizations module is installed. It uses govoplan-idm for identity-to-function assignment facts and Access-owned external function-role mappings to turn accepted function facts into rights.

The legacy Access tables access_organization_units, access_functions, and access_function_assignments remain readable as compatibility/projection tables during rollout. They are no longer the target model for new module integrations.

Rollout plan:

• keep direct Access function/organization reads as a fallback when Organizations or IDM are not installed;
• backfill Organizations units/functions from the Access projection for existing installations that enable the Organizations module later;
• move new identity-to-function assignment workflows to IDM rather than adding assignment ownership to Organizations;
• use Access external function-role mappings for authorization and check that the referenced Organizations function is still active before granting derived permissions;
• retire Access-owned organization/function tables only after a release-level migration/backfill and rollback plan exists.

The close-out condition is that Access role resolution works with canonical Organizations plus IDM installed and still works through projection fallback for transition deployments.

Directory Contracts

organizations.directory remains the small compatibility contract for direct unit and function lookup. It deliberately retains the legacy parent_id projection needed by existing Access and IDM integrations.

organizations.hierarchyDirectory is the structure-aware contract for new consumers. It provides:

• tenant-scoped unit-type and function-type references;
• function resolution by type and an explicit set of units;
• unit resolution by type, optionally bounded to one named structure;
• batched ancestor, descendant, and path resolution with a required structure, optional relation-type filter, and bounded depth;
• the exact structure, relation type, and relation edge for every path step;
• explicit missing, inactive, unreachable, invalid-filter, cycle, and depth-limit state.

An edge is traversed from source_unit_id to target_unit_id for descendant lookups and in reverse for ancestor lookups. Consumers must select a structure; the provider never treats parent_id or one arbitrary structure as the institution's universal hierarchy.

Committed changes emit versioned organizations.<resource>.<action>.v1 platform events for units, functions, their types, structures, relation types, and relation edges. The event payload contains schema version 1, tenant and resource references, status, changed fields, and routing-relevant IDs so directory consumers can invalidate derived addresses without importing this module's models.

UI Boundary

The organization workspace at /organizations is the primary module UI for modelling the meta-model, concrete units, structures, and function definitions. Admin-only organization controls are still owned by this module, but are contributed to the platform admin shell through the admin.sections WebUI capability.

The admin contribution must not duplicate the organization editor. It is for governance and policy settings: whether tenant admins may customize the meta-model, whether model changes require recorded change requests, and how audit detail and retention behave for organization changes.

Boundary With IDM

govoplan-idm may import organization-unit and organization-function definitions from external directories. It should write those definitions through organization capabilities or APIs after preview, approval, and rollback planning. IDM owns identity-to-function assignments and bridge views that combine identity and organization facts, such as identity candidates for function assignments.