Module Index
Data Model Version: 11.0
Modules: 7 (5 domain + 2 cross-cutting)
Total tables: 55
Schema organization: Each module occupies its own PostgreSQL schema (Decision 113). Cross-module FKs retained with schema-qualified references (Decision 114).
Module Map
The data model decomposes into seven modules: five domain modules organized in a strict dependency chain, and two cross-cutting modules that observe all domain modules without occupying a position within that chain. Dependencies among domain modules flow strictly downward — each module depends only on modules earlier in the chain; cross-cutting modules impose no structural constraints on the domain modules they observe.
The domain modules, from foundational to derived: identity (5 tables) establishes who actors are and how they authenticate; organization (8 tables) governs the containers, memberships, and permission structures within which actors operate; entitlements (13 tables) bridges commercial transactions to resource capabilities and materializes entitlements; billing (20 tables) manages financial identity, the product catalog, and the full commercial lifecycle; cooperative (2 tables, early development) observes billing outcomes to record cooperative value contributions without participating in billing execution.
The two cross-cutting modules span the domain chain without occupying a position within it. audit (5 tables) is a one-directional observation system: it receives event and actor references from all modules but is depended upon by none. integration (2 tables) provides shared inbound-webhook and transactional-outbox infrastructure consumed by domain processes across the chain.
Module Directory
| Module |
Schema |
Type |
Tables |
Question |
Entry Point |
| identity |
identity |
Domain |
5 |
Who is this actor, and how do they authenticate? |
README |
| organization |
organization |
Domain |
8 |
What containers exist, and who can access them? |
README |
| entitlements |
entitlements |
Domain |
13 |
What capabilities are available, and who provisioned them? |
README |
| billing |
billing |
Domain |
20 |
Who pays, what do they pay for? |
README |
| cooperative |
cooperative |
Domain |
2 |
What value has this member contributed? [early dev] |
README |
| audit |
audit |
Cross-cutting |
5 |
What happened, when, and by whom? |
README |
| integration |
integration |
Cross-cutting |
2 |
How does the platform exchange data with external systems? |
README |
Cross-Module Dependency Summary
The dependency direction runs from consumer to provider: a module that holds a foreign key into another module is the consumer; the module whose primary key is referenced is the provider. Each row below names the key interface columns and an approximate FK count.
| Provider Schema |
Consumer Schema |
Key Interface |
FK Count |
identity |
organization |
identity.persons.person_id |
14+ columns |
identity |
billing |
identity.persons.person_id |
10+ columns |
identity |
audit |
identity.persons.person_id |
4 columns |
organization |
entitlements |
organization.organizations.org_id, organization.workspaces.workspace_id |
3 columns |
organization |
billing |
organization.organizations.org_id |
3 columns |
organization |
audit |
organization.organizations.org_id, organization.service_accounts.service_account_id |
3 columns |
billing |
entitlements |
billing.billing_accounts, billing.subscriptions, billing.purchases, billing.products, billing.prices |
7 columns |
billing |
cooperative |
billing.billing_accounts, billing.payments, billing.invoices, billing.products |
4 columns |
entitlements |
organization |
entitlements.resource_pools.pool_id |
1 column |
entitlements |
billing |
entitlements.usage_events.event_id, entitlements.entitlement_sets.set_id |
3 columns |
Complete Table-to-Module Index
identity (5 tables)
| Table |
Purpose |
users |
Authentication identity (Keycloak sync) |
persons |
Human/business/legal identity |
personal_access_tokens |
Programmatic credentials for persons |
retention_holds |
Legal retention obligations on person PII |
person_merges |
Duplicate person resolution tracking |
organization (8 tables)
| Table |
Purpose |
organizations |
Governance containers (personal, team, enterprise) |
org_members |
Organization membership records |
roles |
Permission bundle definitions |
role_assignments |
Scoped permission grants to actors |
workspaces |
Resource isolation boundaries within organizations |
service_accounts |
Non-human API actors owned by organizations |
service_account_keys |
API key credentials for service accounts |
invitations |
Organization join invitation lifecycle |
entitlements (13 tables)
| Table |
Purpose |
resource_pools |
Capability containers bridging billing and resources |
pool_provisions |
Access mechanism records linking billing to pools |
grants |
Non-commercial administrative access provisioning |
entitlement_sets |
Named, reusable collections of entitlement rules |
entitlement_set_rules |
Set-to-entitlement mapping (boolean, limit, quota, credit rules) |
boolean_entitlements |
Binary feature flags on pools |
numeric_entitlements |
Numeric limits and quotas on pools |
pool_assignments |
Workspace-to-pool capability delivery |
pool_ondemand_config |
On-demand billing configuration per pool |
usage_events |
Universal consumption records |
numeric_entitlement_usage |
Running usage totals against entitlement limits |
numeric_entitlement_contributions |
Per-provision contributions to entitlement limits |
resource_keys |
Shared resource namespace reference table |
billing (20 tables)
| Table |
Purpose |
billing_accounts |
Financial identity: the entity that pays |
products |
Catalog entries: what the cooperative sells |
prices |
Commercial terms: amount, currency, schedule |
subscriptions |
Recurring billing agreements |
subscription_items |
Line items binding price to quantity |
subscription_changes |
Immutable audit trail of subscription modifications |
purchases |
One-time completed transactions |
invoices |
Finalized billing documents |
invoice_line_items |
Atomic units of invoice composition |
payments |
Money received from billing accounts |
payment_methods |
Stored payment instrument projections |
refunds |
Partial or full return of payment funds |
disputes |
Chargeback and dispute resolution records |
coupons |
Coupon rule definitions |
promotion_codes |
Customer-facing redemption keys |
discounts |
Active discount applications on billing relationships |
pending_charges |
Mutable pre-invoice financial obligations |
pending_charge_usage_events |
Join table: usage events to pending charges |
credit_grants |
Prepaid or promotional credit allocations |
credit_transactions |
Immutable append-only credit ledger |
cooperative (2 tables) — early development
| Table |
Purpose |
patrons |
Cooperative identity projection of billing accounts |
patronage_events |
Atomic cooperative value contribution records |
audit (5 tables)
| Table |
Purpose |
audit_logs |
Append-only event store for all system actions |
audit_retention_policies |
Configurable retention rules per tier |
audit_legal_holds |
Legal preservation obligations on audit data |
audit_archive_manifest |
Archive operation tracking |
audit_outbox |
Transactional outbox for audit event delivery |
integration (2 tables)
| Table |
Purpose |
webhook_events |
Idempotent inbound webhook capture |
integration_outbox |
Transactional outbox for outbound integration actions |
Navigation
Each module contains five files:
| File |
Content |
README.md |
Overview, table list, quick links |
model.md |
Table descriptions and field definitions (projected from data-model.md) |
architecture.md |
Architectural deep-dive (synthesized from documents/doc-*) |
companion.md |
Module-scoped decisions and open issues (references companion.md) |
interfaces.md |
Cross-module interface documentation |
For structural conventions governing all modules, see CONVENTIONS.md.
For the consolidated, searchable reference, see data-model.md (master reference) and companion.md (master companion).
