7.2 KiB
Organization & Access — Interfaces
Module: organization
Schema: organization
This document maps the cross-module interface surface of the organization module: what it provides to other modules, what it consumes from other modules, and the behavioral contracts that govern these dependencies.
Provided Interfaces
The organization module provides three primary keys consumed by downstream modules. As the governance spine of the data model, its provided surface is broad — nearly every entity in the entitlements and billing modules references an organization, and many reference workspaces or service accounts.
org_id (organizations.org_id)
| Consumer Module | FK Column(s) | Semantics |
|---|---|---|
entitlements |
resource_pools.org_id, pool_provisions.org_id |
Governance ownership of resource pools |
entitlements |
grants.granted_to_org_id |
Organization as grant recipient (exclusive arc). Grants moved from billing to entitlements (Decision 106). |
billing |
billing_accounts.org_id, products.org_id, subscriptions.org_id, purchases.org_id, invoices.org_id |
Billing ownership and financial relationships |
audit |
audit_log.org_id |
Organizational scoping of audit entries |
Cardinality: One organization to many downstream entities. Every resource pool, billing account, and related financial entity belongs to exactly one organization.
Stability: org_id is a UUIDv7 primary key. It remains stable through the organization's full lifecycle, including suspension and soft-deletion. Downstream modules can hold FK references to organizations in any status; the row is never physically deleted.
workspace_id (workspaces.workspace_id)
| Consumer Module | FK Column(s) | Semantics |
|---|---|---|
entitlements |
pool_assignments.workspace_id, usage_events.workspace_id |
Resource access and consumption scoping |
Cardinality: One workspace to many pool assignments and usage events. Workspaces draw capabilities from resource pools via pool assignments.
Stability: workspace_id remains stable through archival and soft-deletion. Archived workspaces retain their pool assignments and usage history; deleted workspaces are soft-deleted and their FK references remain valid.
service_account_id (service_accounts.service_account_id)
| Consumer Module | FK Column(s) | Semantics |
|---|---|---|
audit |
audit_log.actor_id (when actor_type = 'service_account') |
Actor attribution for non-human actions |
Cardinality: One service account to many audit log entries.
Stability: service_account_id remains stable through suspension and soft-deletion. Audit log entries referencing a deleted service account retain their FK integrity; the service account row is never physically removed.
Consumed Interfaces
persons from identity
The organization module is the largest consumer of the identity module's persons.person_id. References are distributed across the module:
| Table | FK Column(s) | Purpose |
|---|---|---|
organizations |
owner_person_id, suspended_by, deleted_by |
Ownership and governance actor attribution |
org_members |
person_id, suspended_by, removed_by |
Membership identity and governance actors |
invitations |
invitee_person_id, invited_by_person_id, resolved_person_id, revoked_by_person_id |
Invitation lifecycle actors |
workspaces |
created_by_person_id, archived_by, deleted_by |
Workspace governance actors |
role_assignments |
person_id, granted_by_person_id, revoked_by_person_id |
Assignment target and governance actors |
service_accounts |
created_by_person_id, suspended_by, deleted_by |
Service account governance actors |
service_account_keys |
revoked_by_person_id |
Key revocation attribution |
Total FK columns: 14+ references to persons.person_id across the module.
Why the dependency exists: The organization module governs organizational structure and access control, both of which are fundamentally about persons — who belongs, who acts, who is accountable. The identity module provides the stable person identity that the organization module attaches governance semantics to.
resource_pools from entitlements
| Table | FK Column(s) | Purpose |
|---|---|---|
role_assignments |
scope_pool_id |
Pool-scoped access control |
Why the dependency exists: The role_assignments table supports three scope types via exclusive arc: organization, workspace, and resource pool. Pool-scoped assignments allow fine-grained access control over resource pool management — for example, granting a billing administrator management permissions on a specific pool without granting workspace access. This is the only point where the organization module directly references an entitlements entity; the dependency is deliberate and narrowly scoped to this single FK column.
Interface Contracts
From identity to this module
Person stability guarantee. The identity module guarantees that persons.person_id remains stable through anonymization. When GDPR-motivated data redaction occurs, the person row is mutated (PII fields cleared or pseudonymized) rather than deleted. All organization module FK references to person_id remain valid after anonymization. This contract is essential: if person rows were deleted during anonymization, the organization module would lose ownership records, membership links, invitation provenance, and actor attribution across all governance-sensitive state changes.
From this module to entitlements
Organization stability guarantee. The organization module guarantees that organizations.org_id remains stable through suspension and soft-deletion. Resource pools belonging to a suspended or deleted organization retain their FK integrity. Pool operations may be blocked by application-level checks on organization status, but the FK reference is never invalidated by organizational lifecycle events.
Workspace stability guarantee. The organization module guarantees that workspaces.workspace_id remains stable through archival and soft-deletion. Pool assignments and usage events referencing archived or deleted workspaces retain their FK integrity. Application-level policy may prevent new pool assignments to archived workspaces, but existing references are never broken.
From this module to billing
Organization stability guarantee. Same guarantee as for entitlements: org_id remains stable through all lifecycle states. Billing accounts, subscriptions, purchases, grants, and invoices belonging to a suspended or deleted organization retain valid FK references.
From this module to audit
Actor identity stability guarantee. Both org_id and service_account_id remain stable through all lifecycle states. Audit log entries retain valid references to their organizational context and actor identity regardless of subsequent state changes. This is a necessary condition for audit log integrity: the audit trail must remain complete and referentially valid even when the entities it describes have been suspended, deleted, or anonymized.