Party-Level Isolation and Tenant Types Design

• Enforce party-level data isolation at the database level using PostgreSQL RLS.
• Define tenant types that gate available features and operational controls.
• Define party types that distinguish administrative from business entities.
• Support arbitrarily nested party hierarchies with subtree-scoped visibility.
• Decouple tenant provisioning (system operation) from party setup (business operation).

• A user logged in at a leaf party cannot see data belonging to sibling or ancestor parties.
• A user logged in at an intermediate party sees their own data plus all descendant party data.
• The system party within each tenant has full visibility over all parties.
• Evaluation tenants allow relaxed operations (GLEIF onboarding, bulk import); production tenants enforce strict controls.

The system tenant (tenant 0, max UUID) is the platform-level tenant that owns shared governance data: the tenant registry, system-wide permissions, and reference datasets in the data librarian. There is exactly one system tenant per deployment. Users logged into the system tenant are super administrators with cross-tenant visibility.

Production tenants represent real customer organisations with isolated business operations. These tenants enforce strict operational controls:

• Four-eyes authorisation for sensitive operations (counterparty onboarding, party modifications).
• KYC-gated counterparty creation with supporting documentation.
• Data librarian operations restricted to safe, auditable actions.
• No bulk import of parties or counterparties from external datasets.

Evaluation tenants provide realistic, production-like environments for demonstrations, user acceptance testing, QA, and system evaluation. Controls are relaxed to allow rapid environment setup:

• GLEIF-based party creation available (importing root party and child parties from LEI data).
• Bulk counterparty import from LEI datasets via the data librarian.
• No four-eyes requirement for sensitive operations.
• Clearly labelled in the UI to prevent confusion with production tenants.

Evaluation tenants are suitable for pre-production testing, sales demos, training environments, and exploratory testing by QA teams.

Automation tenants are created and destroyed programmatically by test harnesses for unit, integration, and load testing. They are not intended for human interaction:

• Created with random UUIDs for isolation between test runs.
• No UI-driven workflows; all operations performed via test fixtures.
• Parallel test execution without interference.
• Ephemeral; typically torn down after test completion.

Every tenant has exactly one system party, created automatically during tenant provisioning. The system party:

• Is the administrative home for tenant admin accounts.
• Has full visibility over all parties in the tenant (equivalent to root in the hierarchy model).
• Owns any party-scoped data that is administrative rather than business in nature.
• In tenant 0, it is the only party and serves as the platform admin party.

The system party is analogous to the system tenant: it is an infrastructure construct, not a business entity.

Operational parties represent real business entities: legal entities, branches, desks, subsidiaries. They:

• Are created by users during normal business operations.
• Form an arbitrarily nested hierarchy via parent_party_id.
• Have tree-scoped visibility: a party can see its own data and all descendant party data.
• Own business data: counterparties, books, portfolios, trades.

The root operational party (parent_party_id = NULL among operational parties, or parent_party_id pointing to the system party) represents the top of the business hierarchy, typically the holding company or group entity.

Reference data defined once at the tenant level, sourced from standards bodies (ISO, FpML). All parties within the tenant share a common definition.

Party-level visibility is controlled through junction tables (e.g. party_currencies) that define which currencies a given party can see and use. The underlying currency definitions remain shared. This is a future enhancement.

Operational data owned by a specific party. Each party maintains its own records independently. Even when two parties deal with the same external legal entity, they each have separate records (different KYC status, credit limits, documentation).

Party-scoped tables have a party_id column and RLS policies that filter based on the session's visible party set.

At login, three values are set on the database session:

app.current_tenant_id   = '<tenant-uuid>'       -- existing
app.current_party_id    = '<party-uuid>'         -- new
app.visible_party_ids   = '{uuid1,uuid2,...}'    -- new

At login, after the user selects their party, the server computes the full set of visible party IDs using a recursive CTE:

WITH RECURSIVE party_tree AS (
    -- Start with the user's party
    SELECT id FROM ores_refdata_parties_tbl
    WHERE id = $user_party_id
      AND tenant_id = $tenant_id
      AND valid_to = ores_utility_infinity_timestamp_fn()

    UNION ALL

    -- Add all descendants
    SELECT p.id FROM ores_refdata_parties_tbl p
    JOIN party_tree pt ON p.parent_party_id = pt.id
    WHERE p.tenant_id = $tenant_id
      AND p.valid_to = ores_utility_infinity_timestamp_fn()
)
SELECT array_agg(id) FROM party_tree;

For the system party, the CTE returns all parties in the tenant, giving full visibility.

The visible set is computed once at login and is immutable for the session lifetime. If the party tree changes mid-session, the user must re-login to pick up new visibility.

Party-scoped tables use a single, simple RLS policy:

CREATE POLICY party_isolation ON ores_refdata_counterparties_tbl
  USING (
    party_id = ANY(current_setting('app.visible_party_ids')::uuid[])
  );

This covers all cases:

• System party user: visible set = all parties. Sees everything.
• Root operational party user: visible set = root + all descendants.
• Mid-level party user: visible set = their party + their subtree.
• Leaf party user: visible set = just their party.

For realistic hierarchies (up to a few hundred parties per tenant), the UUID array stays well within PostgreSQL session variable limits and the membership check is fast.

1. Client sends login_request with username@hostname.
2. Server resolves tenant from hostname.
3. Server authenticates user, creates session bound to tenant.
4. Client proceeds.

1. Client sends login_request with username@hostname.
2. Server resolves tenant from hostname.
3. Server authenticates user.
4. Server looks up user's parties from account_parties.
5. If one party: auto-select. If multiple: return party list to client.
6. Client displays party picker (if needed) and sends party selection.
7. Server computes visible_party_ids via recursive CTE.
8. Session is created with tenant ID + party ID + visible party set.
9. Client proceeds. Current party is displayed in the application window.

When a user's visible set spans multiple parties:

• Party-scoped table views gain a "Party" column showing the owning party.
• A party filter dropdown allows scoping the view to a specific subtree.
• Single-party users see the party column hidden (always the same value).

1. Tenant record in ores_iam_tenants_tbl.
2. System party (party 0) for the new tenant.
3. Copies of system-level permissions and roles from the system tenant.
4. One or more admin accounts (associated with the system party).

• Business parties (the "house"). This is a separate business operation.
• Reference data (currencies, countries). Published via the data librarian.
• Counterparties. Created per-party through appropriate workflows.

This separation ensures that tenant creation is a clean, predictable system operation, and business setup is done by the people who understand the business.

For evaluation tenants, an additional step is available after provisioning: importing operating parties from GLEIF/LEI data. This is a separate action, not part of provisioning itself, and is gated by the evaluation tenant type.