Skip to main content

Resource Hierarchy

Purpose​

Defines hierarchical resource ownership and multi-tenancy boundaries through groups.

Core Concept​

Groups are the fundamental organizational units that provide hierarchical ownership and multi-tenancy boundaries for all resources. Every resource in the system belongs to exactly one group, while groups themselves can own other groups, forming tree structures that model real-world organizational relationships.

Key Implementation Points​

  • Universal Ownership: Every resource has exactly one owner group
  • Hierarchical Structure: Groups form tree relationships through ownership
  • Read Inheritance: Parent groups can read descendant resources
  • Write Restriction: Only direct owners can modify resources
  • Multi-tenancy Isolation: Complete separation between organizational hierarchies

Essential Example​

A trading firm demonstrates universal user integration:

  • Executives: Regular users with broad read access
  • Traders: Regular users with trading permissions in specific groups
  • Risk Systems: API users with read-only monitoring access
  • Order Management: API users with automated trading capabilities

Both user types follow identical ownership rules and role assignments within the same hierarchical structure.

Ownership Model​

Each resource maintains an owner field pointing to its direct parent group, with the system internally tracking complete hierarchical paths for efficient access control:

Universal Ownership​

Every resource in Mesh has an owner group, including users, accounts, orders, and instruments:

Access Control Patterns​

Read Operations: Access resources owned by executing group OR any descendant groups.

Write Operations: Access only resources directly owned by executing group.

Integration​

The resource hierarchy system integrates with other architecture components:

API Reference​

Group Service API Reference - Complete API documentation for group management operations

Detailed Examples​

Multi-Tenant Brokerage Platform​

This example demonstrates how groups represent legal entities at every level of the hierarchy. Each group corresponds to a real-world legal entity (individual, corporation, trust, etc.) that undergoes KYC/compliance verification by its parent group.

Legal Entity Hierarchy:

  • Mesh Platform: The root legal entity providing the platform infrastructure
  • Broker Companies: Legal entities (corporations) that are KYC'd by Mesh and provide brokerage services
  • Client Entities: Legal entities (individuals, companies, trusts) that are KYC'd by their respective brokers

Key Legal Entity Relationships:

Compliance Chain:

  • Mesh Platform ← KYC'd by regulators/auditors ← Broker A & B ← KYC'd by Mesh ← Client Entities ← KYC'd by their brokers

Entity Types Supported:

  • Natural Persons: Individual traders and investors (CLIENT_A1)
  • Corporations: Investment companies and fund managers (CLIENT_A2)
  • Trusts & Foundations: Estate planning and wealth management entities (CLIENT_B1)
  • Financial Institutions: Broker-dealers and registered investment advisors (BROKER_A, BROKER_B)

Access Scenarios:

Broker A Admin executing ListAccounts (READ method):

  • ✅ Can see Account A1-Main (descendant: CLIENT_A1)
  • ✅ Can see Account A2-Trading (descendant: CLIENT_A2)
  • ❌ Cannot see Account B1-Settlement (different broker)

John Smith (Regular User) executing CreateOrder via Web Interface (WRITE method):

  • ✅ Can create orders owned by CLIENT_A1 (his legal entity group)
  • ❌ Cannot create orders owned by CLIENT_A2 (different client)
  • ❌ Cannot create orders owned by BROKER_A (not direct ownership)
  • Access Method: Logs in via username/password, same authorization rules apply

John's Trading Bot (API User) executing CreateOrder via API (WRITE method):

  • ✅ Can create orders owned by CLIENT_A1 (same ownership as regular user)
  • ❌ Cannot create orders owned by CLIENT_A2 (different client)
  • ❌ Cannot create orders owned by BROKER_A (not direct ownership)
  • Access Method: Authenticates via API key, identical permissions to regular user

Sarah Johnson (Regular User) executing GetAccount via Mobile App (READ method):

  • ✅ Can view CLIENT_A2 corporate accounts (her group's resources)
  • ✅ Can view parent group accounts (hierarchical READ access)
  • ❌ Cannot view CLIENT_A1 individual accounts (different client branch)
  • Cross-Platform: Same permissions whether using web dashboard, mobile app, or desktop client

Corporate Risk System (API User) executing ListOrders via API (READ method):

  • ✅ Can read all CLIENT_A2 orders for risk analysis
  • ✅ Can read parent group data for consolidated reporting
  • ❌ Cannot read CLIENT_A1 orders (different ownership branch)
  • Automation: Enables automated risk monitoring with same permission model

Investment Bank with Fund Structures​

This example shows how complex financial institutions organize multiple fund structures, departments, and trading desks within a single institutional hierarchy. Each level represents distinct legal entities with their own compliance requirements and operational structures.

Multi-Level Organizational Structure:

Investment Bank Level (GOLDMAN_INTL):

  • Primary Legal Entity: Licensed investment bank with regulatory oversight
  • Direct Children: Fund structures and trading desks
  • Access Rights: Can read all descendant fund and desk activities (hierarchical READ access)
  • Compliance Role: Consolidated reporting and regulatory compliance for all subsidiaries

Fund Level (ALPHA_FUND, BETA_FUND):

  • Legal Structure: Separate legal entities (LP, REIT) with independent governance
  • Fund Departments: Internal divisions for research, risk management, operations
  • Fund Accounts: Master accounts holding pooled investor capital
  • Access Rights: Full control over fund-specific resources, limited access to bank-level resources

Department Level (ALPHA_RESEARCH, BOND_DESK, etc.):

  • Operational Units: Functional departments within larger entities
  • Specialized Accounts: Department-specific trading and operational accounts
  • Trading Activity: Orders and positions managed at department level
  • Access Rights: Direct ownership of department resources only

Access Control Scenarios:

Goldman Sachs Bank Admin executing ListAccounts (READ method):

  • ✅ Can see all fund accounts (ALPHA_MASTER_ACC, BETA_PROPERTY_ACC)
  • ✅ Can see all desk accounts (BOND_TRADING_ACC, FOREX_TRADING_ACC, METALS_TRADING_ACC)
  • ✅ Can see all department accounts (ALPHA_RESEARCH_ACC)
  • Use Case: Consolidated risk monitoring and regulatory reporting across all entities

Bond Trader (Regular User) executing CreateOrder via Trading Terminal (WRITE method):

  • ✅ Can create orders owned by BOND_DESK (his department group)
  • ❌ Cannot create orders owned by FOREX_DESK (different desk)
  • ❌ Cannot create orders owned by ALPHA_FUND (different entity level)
  • Authentication: SSO/Active Directory with role-based terminal access
  • Interface: Desktop trading terminal with real-time market data

Bond Algo System (API User) executing CreateOrder via API (WRITE method):

  • ✅ Can create orders owned by BOND_DESK (same permissions as regular trader)
  • ❌ Cannot create orders owned by FOREX_DESK (same restrictions apply)
  • ❌ Cannot create orders owned by ALPHA_FUND (entity separation maintained)
  • Authentication: API key with identical authorization scope as regular users
  • Integration: Automated algorithmic trading with same business rules

FX Analyst (Regular User) executing GetAccount via Risk Dashboard (READ method):

  • ✅ Can view FOREX_TRADING_ACC (his desk's account)
  • ✅ Can view parent bank accounts (hierarchical READ access)
  • ❌ Cannot view BOND_TRADING_ACC (different desk, sibling level)
  • Access Method: Web-based risk dashboard with real-time position monitoring
  • Cross-Platform: Same permissions via mobile app or web interface

Metals Desk Head (Regular User) executing UpdateAccount via Management Console (WRITE method):

  • ✅ Can update METALS_TRADING_ACC (directly owned by his desk)
  • ❌ Cannot update ALPHA_MASTER_ACC (fund-owned account, different entity)
  • ❌ Cannot update BOND_TRADING_ACC (different desk, sibling relationship)
  • Authentication: Smart card + PIN for high-privilege operations
  • Use Case: Desk-level account management with enhanced security requirements

Compliance and Risk Benefits:

  • Regulatory Segregation: Each fund maintains separate compliance and reporting
  • Risk Isolation: Department failures don't impact other organizational units
  • Operational Efficiency: Specialized access patterns for different business functions
  • Consolidated Oversight: Bank-level visibility for enterprise risk management