# System architecture

Executive summary
**Ripple Custody separates interaction services, asynchronous workflows, and isolated signing boundaries.** Users, applications, and services submit requests through the interaction layer. The platform accepts mutation requests for asynchronous processing, runs the relevant workflow state machine, evaluates policy, persists operational state, and uses protected signing components only through narrow interfaces.

- **Mutation requests use intents**: Administrative changes, account and vault changes, endpoint updates, transaction orders, and compliance operations enter the governed workflow as intents.
- **API intake is asynchronous**: Intent proposal, approval, and rejection calls return `202 Accepted` when the request is accepted for processing. The workflow then continues through queued SAGA-style state transitions.
- **Sensitive operations run in protected boundaries**: The notary evaluates policy and protects trusted state. The vault independently verifies notary attestations before signing blockchain transactions.
- **Private keys stay protected**: User keys, notary keys, vault keys, Gateway system-signing keys where enabled, and blockchain signing keys stay outside general application services.
- **Operational dependencies are explicit**: PostgreSQL, AMQP, blockchain nodes, certificates, secrets, KMS/HSM/MPC backends, and identity providers provide the operating foundation.


Why this matters
Architecture decisions in Ripple Custody directly affect asset safety, recovery, auditability, and operational resilience. Use this page to understand the main components, trust boundaries, runtime flows, and design questions before you plan deployment, governance, key management, or integrations.

## Architectural principles

| Principle | What it means |
|  --- | --- |
| Governed by default | Domain, user, policy, vault, account, endpoint, transaction order, and compliance mutation operations use the intent workflow. |
| Asynchronous request-response | API calls that start governed work accept the request, return a request ID, and let the workflow state machine complete the work asynchronously. |
| Narrow protected boundary | Policy evaluation, trusted-state attestation, and raw blockchain transaction signing happen only inside protected notary and vault boundaries. |
| Isolated key material | KMS, HSM, or MPC systems perform sensitive key operations. General application services do not receive private keys. |
| Verifiable state | Database records, queued work, and service outputs are not trusted by placement alone. Trusted state and signing operations are checked with cryptographic controls. |
| Explicit dependencies | Infrastructure services are part of the runtime system boundary, but deployment topics cover how those services are hosted and operated. |


## Logical architecture

The platform is easier to reason about as five cooperating areas:

- **Interaction and identity**: Web UI, API clients, service callers, GraphQL, API Gateway, identity provider, and notifications.
- **Workflow and accounting**: AMQP-backed workflow state machines, Approval/Notary Bridge, Ledger Accounting, and Event Processing.
- **Protected trust boundary**: Notary, vault, cold vault bridge, KMS Connect, and KMS/HSM/MPC backends.
- **Blockchain integration**: Ledger APIs, adapters, processors, blockchain indexing services, and blockchain nodes.
- **Infrastructure dependencies**: PostgreSQL, AMQP broker, certificates, secrets, container registry, blockchain nodes, and external providers.


A useful mental model is "user space" and "kernel space." Most platform services run in user space: they authenticate users, accept API calls, queue work, display data, and coordinate workflows. Sensitive security operations run in kernel space: policy evaluation and trusted-state attestation in the notary, and raw blockchain transaction signing in the vault. The interface between the two areas is intentionally narrow and cryptographically checked.


```mermaid
flowchart TB
    subgraph callers["Users, apps, and service callers"]
        ui["Web UI"]
        apiClients["API clients"]
        serviceCallers["Service callers"]
        authSign["Auth and Sign app"]
    end

    subgraph interaction["Interaction and identity"]
        gateway["API Gateway"]
        graphql["GraphQL"]
        idp["OIDC / Keycloak / external IdP"]
        notify["Notifications and core extensions"]
    end

    subgraph workflow["Workflow and accounting"]
        amqp["AMQP broker"]
        workflows["Intent workflow state machines"]
        bridge["Approval / Notary Bridge"]
        accounting["Ledger Accounting"]
        eventProcessing["Event Processing"]
    end

    subgraph data["State and queues"]
        postgres[("PostgreSQL")]
    end

    subgraph protected["Protected trust boundary"]
        notary["Notary / policy evaluation"]
        notaryKms["Notary KMS Connect"]
        vault["Vault"]
        vaultBridge["Vault Bridge / Cold Bridge"]
        vaultKms["Vault KMS Connect"]
        kms["KMS / HSM / MPC"]
    end

    subgraph blockchain["Blockchain integration"]
        indexing["Blockchain indexing services"]
        ledgerApis["Ledger APIs and adapters"]
        nodes["Blockchain nodes"]
    end

    subgraph external["External integrations"]
        compliance["Compliance providers"]
        webhooks["Webhook receivers"]
    end

    ui --> gateway
    ui --> graphql
    authSign --> idp
    apiClients --> gateway
    serviceCallers --> gateway
    gateway --> idp
    graphql --> gateway
    notify --> ui
    gateway --> amqp
    amqp --> workflows
    workflows --> bridge
    bridge <--> notary
    notary <--> notaryKms
    notaryKms <--> kms
    workflows --> accounting
    workflows --> eventProcessing
    accounting --> postgres
    eventProcessing --> postgres
    gateway <--> vault
    vault <--> vaultKms
    vaultKms <--> kms
    vaultBridge <--> vault
    accounting <--> indexing
    indexing <--> ledgerApis
    ledgerApis <--> nodes
    accounting <--> compliance
    eventProcessing --> webhooks
```

## Trust and responsibility boundaries

Ripple Custody uses a zero-trust model. In this context, "trusted" does not mean "important." It means a component is part of the cryptographic boundary that prevents unauthorized trusted-state changes or unauthorized transaction signing.

| Boundary | Includes | Role | Design question |
|  --- | --- | --- | --- |
| Client and interaction boundary | Web UI, API clients, service callers, API Gateway, GraphQL, identity provider, notification services | Authenticates callers, accepts requests, exposes data, and routes work. These services do not make a state mutation trusted by themselves. | Which users, service callers, tokens, certificates, and ingress paths are allowed? |
| Workflow and accounting boundary | AMQP workflows, Approval/Notary Bridge, Ledger Accounting, Event Processing | Runs workflow state machines, coordinates approvals, accounts for balances, persists operational state, and processes events. | Which components must be singleton, horizontally scaled, or monitored for backlog? |
| Protected trust boundary | Notary, vault, KMS Connect, KMS/HSM/MPC, Vault Bridge or Cold Bridge | Evaluates policies, protects trusted state, validates signatures, prevents state rewind, and signs blockchain transactions only after vault verification of notary attestation. | Where do notary, vault, and KMS run, and how are they isolated from workflow and interaction services? |
| Infrastructure dependencies | PostgreSQL, AMQP broker, blockchain nodes, secrets, certificates, registry, network routes | Provides persistence, messaging, ledger access, and operational security. | Which dependencies must be available for each runtime flow? |
| External integration boundary | Compliance providers, webhook receivers, third-party node providers, corporate proxies | Extends the platform to screening, event delivery, or ledger connectivity outside the platform. | What happens when an external provider is unavailable, slow, or misconfigured? |


For the detailed security model, see [Security model](/products/custody/overview/security-model). For HA, DR, and ownership categories, see [Resilience planning](/products/custody/deployment/planning/resilience).

## Runtime flows

### Governed state mutation

Most administrative and operational changes use the same intent lifecycle: submit, accept for asynchronous processing, evaluate policy, collect approvals where required, execute the relevant workflow transition, and record auditable state.


```mermaid
sequenceDiagram
    participant Caller as User or service caller
    participant API as API Gateway
    participant AMQP as AMQP broker
    participant Workflow as Workflow state machine
    participant Notary as Notary / policy evaluation
    participant KMS as Notary KMS
    participant Accounting as Ledger Accounting
    participant DB as PostgreSQL

    Caller->>API: Submit signed intent
    API->>API: Validate JWT and request shape
    API-->>Caller: 202 Accepted with requestId
    API->>AMQP: Queue workflow task
    AMQP-->>Workflow: Start intent workflow
    Workflow->>Notary: Evaluate policy and trusted state
    Notary->>Notary: Verify signatures, Merkle state, and ARF
    Notary->>KMS: Sign root or attestation
    KMS-->>Notary: Return signature
    Notary-->>Workflow: Return decision and signed trusted-state result
    Workflow->>Accounting: Continue workflow and persist result
    Accounting->>DB: Write operational state and audit records
    Caller->>API: Poll request or intent state
```

User-signed intents include a user author and a client-side signature. API-only system-signed proposals omit the user author and client-side payload signature; the Gateway signs them internally only when system-signed intent processing, trusted public key registration, and matching `SystemSigned` policies are in place. For the request structures, see [Intent request structure](/products/custody/governance/intents/intent-request-structure).

### Outgoing transaction

Outgoing blockchain transactions add an attestation, signing, and broadcast phase after governance approval. The notary does not push a signing order to the vault. The vault independently polls for work, verifies the notary attestation and request data, builds the ledger-specific transaction, and asks its KMS backend for the protected signing operation.


```mermaid
sequenceDiagram
    participant Caller as User or service caller
    participant API as API Gateway
    participant AMQP as AMQP broker
    participant Bridge as Approval / Notary Bridge
    participant Notary
    participant NotaryKMS as Notary KMS
    participant Vault
    participant VaultKMS as Vault KMS
    participant Accounting as Ledger Accounting
    participant Node as Blockchain node
    participant Indexing as Blockchain indexing services

    Caller->>API: Submit transaction intent
    API-->>Caller: 202 Accepted with requestId
    API->>AMQP: Publish workflow task
    Bridge->>AMQP: Consume workflow task
    Notary->>Bridge: Poll for signed request and approvals
    Bridge-->>Notary: Return request data
    Notary->>Notary: Verify signatures, evaluate policy, update Merkle state
    Notary->>NotaryKMS: Sign attestation
    NotaryKMS-->>Notary: Return signature
    Notary-->>Bridge: Return attested operation
    Bridge->>AMQP: Publish attested result
    Vault->>API: Poll for attested operation
    API-->>Vault: Return operation and notary attestation
    Vault->>Vault: Verify attestation, Merkle proof, and request
    Vault->>VaultKMS: Request protected transaction signature
    VaultKMS-->>Vault: Return signature only
    Vault-->>API: Submit signed blockchain transaction
    API->>Accounting: Queue broadcast and tracking
    Accounting->>Node: Broadcast signed transaction
    Indexing->>Node: Observe ledger state
    Accounting->>Indexing: Pull status or events
    Indexing-->>Accounting: Return detection and confirmations
```

Hot vaults perform the vault signing steps online. Cold vaults replace the online vault polling and upload steps with an operator-mediated air-gapped flow. For status details, see [Transaction status](/products/custody/transactions/processing).

### Incoming and indexed activity

Incoming transfers and on-chain status updates start from blockchain observation rather than user initiation.


```mermaid
flowchart LR
    node["Blockchain node"] --> indexing["Blockchain indexing services"]
    indexing --> indexedData["Indexed ledger data"]
    accounting["Ledger Accounting"] -->|"Pulls indexed activity"| indexedData
    indexedData -->|"Returns ledger events"| accounting
    accounting --> database[("PostgreSQL")]
    accounting --> events["Event Processing"]
    events --> eventApi["Events API"]
    events --> webhook["Webhook delivery"]
    eventApi --> integrator["Customer reconciliation systems"]
    webhook --> integrator
```

Indexing services identify ledger activity relevant to custody accounts and normalize chain-specific data. Ledger Accounting pulls indexed events and persists the resulting operational state. Product-level Events API and webhook delivery expose platform events to customer systems. For details, see [Unified Indexer Service](/products/custody/overview/architecture/unified-indexer-service).

## Component summary

| Component | Primary role | Trust and state model | Runtime shape | More detail |
|  --- | --- | --- | --- | --- |
| Web UI | Back-office interface for operators and administrators. | Interaction layer; stateless. | Multiple replicas. | [Use the UI](/products/custody/get-started/use-the-ui) |
| Auth and Sign app | Stores user signing material and signs UI authentication or intent operations. | Client-side user key holder. | User device application. | [Register and log in with the UI](/products/custody/identity-and-access/authentication/ui-authentication) |
| API Gateway | Public API entry point for clients and components; validates JWTs and request shape. | Interaction layer; stateless. | Multiple replicas. | [Use the API](/products/custody/get-started/use-the-api) |
| GraphQL | Data layer for Web UI v2. | Interaction layer; stateless. | Multiple replicas. | [Resilience planning](/products/custody/deployment/planning/resilience) |
| Identity provider | Issues JWTs for UI, API, and service callers. | Security dependency; configuration-sensitive. | Keycloak or external OIDC provider. | [Authentication](/products/custody/identity-and-access/authentication/overview) |
| Notification server and core extensions | Delivers WebSocket and email/user-invitation notifications. | Interaction layer; stateless. | Multiple replicas where enabled. | [Notifications configuration](/products/custody/deployment/reference/notifications) |
| Intent workflow state machines | Drive asynchronous SAGA-style processing for proposals, approvals, transaction orders, and other mutation operations. | Workflow layer; stores operational progress through Ledger Accounting and PostgreSQL. | Depends on workflow and queue topology. | [Manage intents and approvals](/products/custody/governance/intents/manage-intents-and-approvals) |
| Approval / Notary Bridge | Moves workflow messages between AMQP-backed services and the notary boundary. | Bridge into protected trust boundary; stateless. | Singleton. | [Notary configuration](/products/custody/deployment/reference/kms-notary) |
| Notary | Evaluates policies, validates trusted state, signs Merkle roots and trusted-state attestations, and maintains anti-rewind protection. | Protected trust boundary; stateful through ARF and append-only trusted-state data. The notary does not write platform state directly to PostgreSQL. | Singleton. | [Data integrity and governance](/products/custody/overview/security/data-integrity-and-audit-trail) |
| Vault | Verifies notary attestations, derives account keys, builds ledger-specific transactions, and signs blockchain transactions through KMS/HSM/MPC. | Protected trust boundary; stateless at runtime. | Two or more replicas for hot vaults; cold vaults use an air-gapped pattern. | [Manage vaults](/products/custody/identity-and-access/vault-management/manage-vaults) |
| Vault Bridge / Cold Bridge | Supports air-gapped cold vault signing workflows. | Secure signing support component. | One per cold vault environment. | [Cold vaults](/products/custody/identity-and-access/vault-management/cold-vaults) |
| KMS Connect | Connects notary, vault, or Gateway-dedicated system-signing components to a selected KMS backend. | Key-management adapter; private keys remain protected by backend controls. | Sidecar or connected service depending on integration. | [KMS integration](/products/custody/deployment/integrate-kms/overview) |
| Ledger Accounting | Tracks balances, transaction state, ledger-specific processing, compliance-related accounting, and persisted workflow outcomes. | Workflow and accounting layer; operational state in PostgreSQL. | Singleton. | [Transactions and transfers](/products/custody/transactions/overview) |
| Blockchain indexing services | Monitor blockchain nodes, normalize ledger activity, and expose indexed data that Ledger Accounting consumes. | Blockchain integration; state stored in PostgreSQL or component-specific tables. | One per ledger/network pattern; UIS isolates ledger/network components. | [Unified Indexer Service](/products/custody/overview/architecture/unified-indexer-service) |
| Event Processing | Consumes AMQP messages and performs asynchronous work such as event updates and webhook delivery. | Workflow layer; stateless. | One or more replicas depending on queue setup. | [Events and webhooks](/products/custody/operations-and-maintenance/events-and-webhooks) |
| AMQP broker | Queues requests and asynchronous tasks. | Infrastructure dependency; stateful queues. | Highly available RabbitMQ or compatible AMQP v0.9 broker. | [Message queue planning](/products/custody/deployment/planning/messaging) |
| PostgreSQL | Stores platform state, operational records, indexer state, and wrapped key material where applicable. | Infrastructure dependency; stateful. Trusted-state integrity is verified cryptographically. | Production HA database. | [Database planning](/products/custody/deployment/planning/database) |
| KMS / HSM / MPC | Protects cryptographic keys and performs signing or key-generation operations. | Cryptographic dependency. | HSM HA cluster, cloud HSM, or MPC network. | [Key management planning](/products/custody/deployment/planning/key-management) |
| Blockchain nodes | Provide ledger RPC access for broadcast, status checks, fee data, and indexing. | Customer-managed or third-party dependency. | Redundant node endpoints recommended. | [Blockchain node planning](/products/custody/deployment/planning/blockchain-nodes) |
| Compliance services and adapter | Run transaction-screening and Travel Rule compliance workflows through configured providers. | Optional integration layer. | Enabled when transaction screening or Travel Rule integrations are required. | [Compliance](/products/custody/compliance) |


## Related topics

| Topic | Description |
|  --- | --- |
| [Security model](/products/custody/overview/security-model) | Zero-trust model, key management, secure communication, and data integrity. |
| [Governance model](/products/custody/overview/governance-model) | Domains, policies, intents, approvals, and genesis design. |
| [Data integrity and governance](/products/custody/overview/security/data-integrity-and-audit-trail) | Trusted entities, Merkle tree, ARF, and signature verification. |
| [Secure communication](/products/custody/overview/security/secure-communication) | TLS, JWTs, mTLS, application-layer signatures, and dependency connections. |
| [Deployment overview](/products/custody/deployment/overview) | Planning, installation, configuration, and verification sequence. |
| [Resilience planning](/products/custody/deployment/planning/resilience) | Component ownership, state, HA, and DR model. |