Multi-Party Architecture

Parties within a tenant form an arbitrarily nested tree. The tree structure represents a corporate group's organisational hierarchy:

                   ┌────────────────────┐
                   │   System Party     │  (party 0, auto-created)
                   │   type: system     │
                   └────────┬───────────┘
                            │
                   ┌────────┴───────────┐
                   │   ACME Group       │  (root operational party)
                   │   type: operational│
                   └────────┬───────────┘
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
┌────────┴─────────┐  ┌─────┴────────────┐  ┌──┴───────────────┐
│ ACME Europe      │  │ ACME Americas    │  │ ACME Asia-Pac    │
│ type: operational│  │ type: operational│  │ type: operational│
└────────┬─────────┘  └──────────────────┘  └──────────────────┘
         │
┌────────┴─────────┐
│ ACME London      │
│ type: operational│
└──────────────────┘

Each party has a type that determines its role within the tenant.

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.
• Owns party-scoped data that is administrative rather than business in nature.
• In tenant 0 (system tenant), it is the only party.

The system party is analogous to the system tenant: it is an infrastructure construct, not a business entity. It serves a similar role to the max UUID system tenant but at the party level.

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: counterparty relationships, books, portfolios, trades.

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

┌──────────────────────────────────────────────────────────────┐
│                     Tenant: ACME Corp                        │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │          Shared Reference Data (tenant-scoped)         │  │
│  │   Currencies: USD, EUR, GBP, JPY                       │  │
│  │   Countries: US, GB, DE, JP, FR                        │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  Party A can use: USD, EUR, GBP   (via junction table)       │
│  Party B can use: USD, JPY        (via junction table)       │
│  Party C can use: EUR, GBP        (via junction table)       │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Entities in this category:

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.

The two categories above are the ones inside a tenant, and they are not the whole ownership model. The installation owns the deployment's own facts — the services roster, the hosts and wrapper nodes, the grid and node samples, the telemetry logs, the message-bus samples and the database row. Those rows carry no tenant's data and belong to no party, so neither a tenant's isolation nor a party's should narrow them: they want the policy shape that admits the installation's own rows to every session, with the permission deciding who may call the read. Naming the owner is the first step of designing a table, and the three owners and their shapes are stated in Tenant ownership and the information flow.

Counterparties are modelled as a two-tier structure that separates identity (factual, shared) from relationship (party-specific, isolated).

Operational data owned by a specific party. Each party maintains its own records independently.

Entities in this category:

Note: Counterparty identity (LEI, legal name, hierarchy) is tenant-scoped shared reference data; only the party-specific relationship overlay is party-scoped. See the section above for details.

Every transaction a request opens sets three values, local to that transaction:

select set_config('app.current_tenant_id', $1, true),  -- tenant RLS
       set_config('app.current_party_id',  $2, true),  -- the user's party
       set_config('app.visible_party_ids', $3, true);  -- the subtree set

The visible_party_ids array contains the user's party plus all its descendants, computed at login via a recursive CTE.

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

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;

The result is signed into the access token as the visible_party_ids claim, and each transaction of a request sets it as app.visible_party_ids. For the system party, this query returns all parties in the tenant.

Party-scoped tables use a restrictive RLS policy (ANDed with the permissive tenant policy). The policy is strict: when no party context is set, ores_iam_visible_party_ids_fn() returns NULL, so x = ANY(NULL) evaluates to NULL (falsy) and no rows are visible. There is no null pass-through. Users must have a party assigned.

CREATE POLICY party_isolation ON ores_refdata_books_tbl
  AS RESTRICTIVE
  FOR ALL USING (
    party_id = ANY(ores_iam_visible_party_ids_fn())
  )
  WITH CHECK (
    party_id = ANY(ores_iam_visible_party_ids_fn())
  );

This covers all visibility scenarios:

┌──────────────────────────────┬──────────────────────────────────────┐
│ User's Party                 │ Visible Data                         │
├──────────────────────────────┼──────────────────────────────────────┤
│ System party                 │ All parties in tenant                │
│ ACME Group (root operational)│ All operational parties              │
│ ACME Europe (mid-level)      │ ACME Europe + ACME London            │
│ ACME London (leaf)           │ ACME London only                     │
└──────────────────────────────┴──────────────────────────────────────┘

Tenant and party RLS are enforced simultaneously. A query on a party-scoped table is filtered by both:

-- Effective filter on any party-scoped table:
WHERE tenant_id = current_setting('app.current_tenant_id')::uuid     -- tenant RLS
  AND party_id = ANY(current_setting('app.visible_party_ids')::uuid[])  -- party RLS

This provides defence in depth: even if party RLS were misconfigured, tenant RLS prevents cross-tenant data access.

The database context carries the party alongside the tenant:

class context {
public:
    const utility::uuid::tenant_id& tenant_id() const;
    std::optional<boost::uuids::uuid> party_id() const;
    const std::vector<boost::uuids::uuid>& visible_party_ids() const;

    context with_tenant(utility::uuid::tenant_id tenant_id, std::string actor) const;
    context with_party(utility::uuid::tenant_id tenant_id,
                       boost::uuids::uuid party_id,
                       std::vector<boost::uuids::uuid> visible_party_ids,
                       std::string actor) const;
};

Key properties:

• Party context is optional: not all operations need party scope.
• Every copy shares the one pool, so a party-scoped context costs no connection of its own.

pq::transaction sends the context's settings with begin, in one pipeline with the first statement. A context with a party sets app.current_party_id and app.visible_party_ids; a context without one sets them empty, which the party policies read as no party context (see the RLS policy pattern above). The settings are local to the transaction, so the next transaction on the same pooled connection starts with no party. The visible parties travel as one array parameter.

The access token carries the party alongside the tenant: the party_id claim names the active party, and the visible_party_ids claim lists that party and its descendants.

Party binding follows the same principles as tenant binding:

• Resolved at login time, after party selection.
• Signed into the token, so a request cannot change it.
• Used for every request that carries the token.

┌──────────────────────┐
│  Login Request       │
│  user@hostname       │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Resolve tenant       │   (existing)
│ from hostname        │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Authenticate user    │   (existing)
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Lookup parties from  │   (new)
│ account_parties      │
└──────────┬───────────┘
           │
    ┌──────┴──────┐
    │ 1 party     │ N parties
    ▼             ▼
┌─────────┐  ┌───────────────┐
│ Auto-   │  │ Return party  │
│ select  │  │ list to client│
└────┬────┘  └───────┬───────┘
     │               │
     │          ┌────┴────────┐
     │          │ Client shows│
     │          │ party picker│
     │          └────┬────────┘
     │               │
     └───────┬───────┘
             │
             ▼
┌──────────────────────┐
│ Compute visible      │   (new)
│ party set via        │
│ recursive CTE        │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Sign a token with    │
│ tenant + party +     │
│ visible set          │
└──────────────────────┘

ores::service::service::make_request_context() narrows the service's base context to the token's tenant and party:

return base_ctx
    .with_party(*tid_result, party_id, std::move(visible_ids),
                claims->username.value_or(""))
    .with_roles(claims->roles);

A token with no party gives a tenant-only context.

The active party context is displayed as a styled chip label in the application status bar so the user always knows their active party. Rules:

The party chip is always visible when connected. A red-background warning chip is shown when no party context is available; the removed desktop client also showed a modal warning at login to alert the user to the misconfiguration. With strict RLS enforcement, a missing party context means all books, portfolios, and trades are hidden — not just a cosmetic warning.

The current party category is supplied by the server in the party_summary struct (see party_summary::party_category below).

The login_response always includes the selected party in available_parties regardless of whether there is one party or many:

• Single party: selected_party_id is set; available_parties contains the one party with its name and category. The client reads the name from available_parties.front().
• Multiple parties: selected_party_id is nil; available_parties lists all parties. The client shows a picker; after selection the server binds the session via select_party_request.
• Zero parties: login is rejected server-side.

Party info is fetched using ores_refdata_get_party_info_fn to avoid inline SQL in C++ handler code.

When a user's visible set spans multiple parties, table views adapt:

The party column shows the owning party for each record. A filter dropdown allows scoping the view to a specific party or subtree.

When viewing data across multiple parties, some records may appear to be duplicates (e.g. both Party A and Party B have a relationship with "Deutsche Bank"). These are distinct relationship records with independent lifecycles – different KYC status, credit limits, and trading agreements. The party column disambiguates them. The underlying counterparty identity (LEI, legal name) is shared and appears only once.

For aggregated views (group-level risk, consolidated P&L), intercompany positions between parties in the same group require special handling (elimination) which is a reporting concern, not a data isolation concern.

For realistic hierarchies (up to a few hundred parties per tenant), the performance impact is negligible.

For a tenant with 100 parties, visible_party_ids adds about 1.6 KB to each request's context.