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.

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.

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

SET app.current_tenant_id = 'tenant-uuid';          -- existing (tenant RLS)
SET app.current_party_id  = 'party-uuid';           -- new (user's party)
SET app.visible_party_ids = '{uuid1,uuid2,...}';     -- new (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 stored as the app.visible_party_ids session variable. 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 gains party awareness alongside tenant awareness:

class context {
public:
    explicit context(sqlgen::ConnectionPool<connection_type> connection_pool,
                     sqlgen::postgres::Credentials credentials,
                     utility::uuid::tenant_id tenant_id);

    const utility::uuid::tenant_id& tenant_id() const;

    // Create a new context with a different tenant (shares connection pool)
    context with_tenant(utility::uuid::tenant_id tenant_id) const;

    // Create a new context with tenant + party (shares connection pool)
    context with_party(utility::uuid::tenant_id tenant_id,
                       boost::uuids::uuid party_id,
                       std::vector<boost::uuids::uuid> visible_party_ids) const;

private:
    tenant_aware_pool<connection_type> connection_pool_;   // existing
    sqlgen::postgres::Credentials credentials_;
};

The pool wrapper sets all session variables on connection acquisition:

template <class Connection>
class tenant_aware_pool {
public:
    expected<AcquiredConnection, sqlgen::Error> acquire() {
        auto conn = pool_.acquire();
        if (!conn) {
            return sqlgen::error(conn.error());
        }

        // Set tenant context (existing)
        (*conn)->exec(fmt::format(
            "SET app.current_tenant_id = '{}'",
            tenant_id_.to_string()));

        // Set party context (new)
        if (party_id_) {
            (*conn)->exec(fmt::format(
                "SET app.current_party_id = '{}'",
                boost::uuids::to_string(*party_id_)));

            (*conn)->exec(fmt::format(
                "SET app.visible_party_ids = '{{{}}}'",
                format_uuid_array(visible_party_ids_)));
        }

        return conn;
    }

private:
    sqlgen::ConnectionPool<Connection> pool_;
    utility::uuid::tenant_id tenant_id_;
    std::optional<boost::uuids::uuid> party_id_;           // new
    std::vector<boost::uuids::uuid> visible_party_ids_;     // new
};

Key properties:

• Party context is optional (not all operations require party scope).
• When set, both tenant and party session variables are configured.
• The visible_party_ids array is formatted as a PostgreSQL array literal.

Each authenticated session stores party context alongside tenant context:

struct session_data {
    boost::uuids::uuid id;
    boost::uuids::uuid account_id;
    utility::uuid::tenant_id tenant_id;
    boost::uuids::uuid party_id;                            // new
    std::vector<boost::uuids::uuid> visible_party_ids;      // new
    std::string username;
    std::chrono::system_clock::time_point created_at;
    std::chrono::system_clock::time_point last_activity;
};

Party binding follows the same principles as tenant binding:

• Resolved at login time (after party selection).
• Immutable for the session lifetime.
• Used for all subsequent requests in that session.

┌──────────────────────┐
│  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        │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Create session with  │
│ tenant + party +     │
│ visible set          │
└──────────────────────┘

The make_request_context() method gains party awareness:

database::context make_request_context(
    const comms::service::session_data& session) {
    return ctx_.with_party(
        session.tenant_id,
        session.party_id,
        session.visible_party_ids);
}

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; a QMessageBox::warning is also shown 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 Qt client uses ClientManager::isSystemParty() to check if the active party is the system party.

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 ~1.6 KB per session.