# khayaai/openfireblocks architecture

> Architecture diagram of the GitHub repository khayaai/openfireblocks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khayaai/openfireblocks
- Repository: https://github.com/khayaai/openfireblocks

## Overview

OpenFireblocks is a multi-tenant Ethereum settlement platform. Tenant clients authenticate with API keys and submit synchronous signing requests or durable settlements; the gateway applies policy and risk checks, delegates signing, records transaction and audit data, and can broadcast to Ethereum. Settlements use Temporal workflows for approval, retries, broadcast, and monitoring. Admins manage tenants and inspect usage; Prometheus metrics expose operational and business activity. The README documents Vault-backed keys, immutable audit, and OPA, but their runtime wiring is not fully visible in the excerpts, so those links are omitted or marked unverified.

Main entry points: [`services/api-gateway/src/sign/sign.service.ts`](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/sign/sign.service.ts) (Sign orchestration), [`services/api-gateway/src/sign/sign.controller.ts`](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/sign/sign.controller.ts) (Signing API), [`services/mpc-signer/signer.go`](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/mpc-signer/signer.go) (MPC signer), [`services/api-gateway/src/main.ts`](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/main.ts) (API gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway and tenants"]
  node_api["API gateway<br/>[main.ts]"]
  node_auth["API-key auth<br/>[api-key.guard.ts]"]
  node_tenants["Tenant management"]
  node_adminroutes["Admin routes"]
  node_signroute["Signing API<br/>[sign.controller.ts]"]
end

subgraph group_signing["Signing and controls"]
  node_sign["Sign orchestration<br/>[sign.service.ts]"]
  node_policy["Policy checks<br/>[policy.service.ts]"]
  node_risk["Risk controls<br/>[risk.service.ts]"]
  node_signer["MPC signer<br/>[signer.go]"]
  node_tss["TSS core<br/>[tss.go]"]
  node_eth["Ethereum RPC"]
  node_prepare["Transaction preparation<br/>[prepare.service.ts]"]
  node_policyengine["OPA policy service<br/>[main.go]"]
end

subgraph group_settlement["Settlement orchestration"]
  node_settleroute["Settlement API"]
  node_temporal["Temporal client"]
  node_worker["Workflow worker<br/>[main.go]"]
  node_workflow["Settlement workflow"]
  node_activities["Workflow activities<br/>[activities.go]"]
end

subgraph group_state["Persistence and observability"]
  node_postgres[("PostgreSQL transactions")]
  node_audit[("Audit trail<br/>[audit.service.ts]")]
  node_metrics["Prometheus metrics<br/>[metrics.service.ts]"]
end

subgraph group_clients["Client SDKs"]
  node_sdkjs["JavaScript SDK<br/>[index.ts]"]
  node_sdkgo["Go SDK<br/>[client.go]"]
  node_sdkpy["Python SDK<br/>[client.py]"]
end

node_client(("Tenant client"))
node_admin(("Platform admin"))
node_vault[("Vault key store")]
node_immudb[("immudb audit store")]
node_ethereum(("Ethereum network"))

node_client -.->|"uses"| node_sdkjs
node_client -.->|"uses"| node_sdkgo
node_client -.->|"uses"| node_sdkpy
node_sdkjs -.->|"calls API"| node_api
node_sdkgo -.->|"calls API"| node_api
node_sdkpy -.->|"calls API"| node_api
node_admin -->|"manages tenants"| node_adminroutes
node_adminroutes -->|"manages"| node_tenants
node_client -->|"submits request"| node_signroute
node_signroute -->|"guards routes"| node_auth
node_auth -->|"resolves key"| node_tenants
node_signroute -->|"delegates signing"| node_sign
node_sign -->|"evaluates policy"| node_policy
node_sign -->|"checks velocity"| node_risk
node_sign -->|"requests signature"| node_signer
node_sign -->|"saves transaction"| node_postgres
node_sign -->|"records events"| node_audit
node_sign -->|"broadcasts signed tx"| node_eth
node_signroute -->|"prepares request"| node_prepare
node_prepare -->|"gets network data"| node_eth
node_eth -.->|"submits transaction"| node_ethereum
node_signroute -->|"reads transactions"| node_postgres
node_signroute -->|"reads audit trail"| node_audit
node_signer -->|"uses core"| node_tss
node_signer -.->|"loads keys"| node_vault
node_signer -.->|"writes audit"| node_immudb
node_settleroute -->|"guards routes"| node_auth
node_settleroute -->|"starts workflow"| node_temporal
node_temporal -.->|"dispatches workflow"| node_worker
node_worker -->|"runs"| node_workflow
node_workflow -->|"executes activities"| node_activities
node_api -.->|"exposes metrics"| node_metrics
node_policy -.->|"evaluates remotely"| node_policyengine

click node_api "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/main.ts"
click node_auth "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/auth/api-key.guard.ts"
click node_tenants "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/customers/customer.service.ts"
click node_adminroutes "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/customers/customer.controller.ts"
click node_signroute "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/sign/sign.controller.ts"
click node_settleroute "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/settlements/settlements.controller.ts"
click node_sign "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/sign/sign.service.ts"
click node_policy "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/policies/policy.service.ts"
click node_risk "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/risk/risk.service.ts"
click node_signer "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/mpc-signer/signer.go"
click node_tss "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/mpc-signer/tss/tss.go"
click node_eth "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/blockchain/ethereum.service.ts"
click node_prepare "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/blockchain/prepare.service.ts"
click node_temporal "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/settlements/temporal.service.ts"
click node_worker "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/temporal-worker/main.go"
click node_workflow "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/temporal-worker/workflows/transaction_settlement.go"
click node_activities "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/temporal-worker/activities/activities.go"
click node_postgres "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/database/postgres.service.ts"
click node_audit "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/database/audit.service.ts"
click node_metrics "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/monitoring/metrics.service.ts"
click node_policyengine "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/policy-service/main.go"
click node_sdkjs "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/sdks/sdk-js/src/index.ts"
click node_sdkgo "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/sdks/sdk-go/client.go"
click node_sdkpy "https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/sdks/sdk-python/openfireblocks/client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_auth,node_tenants,node_adminroutes,node_signroute,node_client toneBlue
class node_sign,node_policy,node_risk,node_signer,node_tss,node_eth,node_prepare,node_policyengine,node_vault,node_immudb toneAmber
class node_settleroute,node_temporal,node_worker,node_workflow,node_activities toneMint
class node_postgres,node_audit,node_metrics toneRose
class node_sdkjs,node_sdkgo,node_sdkpy,node_admin,node_ethereum toneIndigo
```

## Components

### Gateway and tenants

- [API gateway](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/main.ts): `services/api-gateway/src/main.ts`
- [API-key auth](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/auth/api-key.guard.ts): `services/api-gateway/src/auth/api-key.guard.ts`
- [Tenant management](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/customers/customer.service.ts): `services/api-gateway/src/customers/customer.service.ts`
- [Admin routes](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/customers/customer.controller.ts): `services/api-gateway/src/customers/customer.controller.ts`
- [Signing API](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/sign/sign.controller.ts): `services/api-gateway/src/sign/sign.controller.ts`

### Signing and controls

- [Sign orchestration](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/sign/sign.service.ts): `services/api-gateway/src/sign/sign.service.ts`
- [Policy checks](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/policies/policy.service.ts): `services/api-gateway/src/policies/policy.service.ts`
- [Risk controls](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/risk/risk.service.ts): `services/api-gateway/src/risk/risk.service.ts`
- [MPC signer](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/mpc-signer/signer.go): `services/mpc-signer/signer.go`
- [TSS core](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/mpc-signer/tss/tss.go): `services/mpc-signer/tss/tss.go`
- [Ethereum RPC](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/blockchain/ethereum.service.ts): `services/api-gateway/src/blockchain/ethereum.service.ts`
- [Transaction preparation](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/blockchain/prepare.service.ts): `services/api-gateway/src/blockchain/prepare.service.ts`
- [OPA policy service](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/policy-service/main.go): `services/policy-service/main.go`

### Settlement orchestration

- [Settlement API](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/settlements/settlements.controller.ts): `services/api-gateway/src/settlements/settlements.controller.ts`
- [Temporal client](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/settlements/temporal.service.ts): `services/api-gateway/src/settlements/temporal.service.ts`
- [Workflow worker](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/temporal-worker/main.go): `services/temporal-worker/main.go`
- [Settlement workflow](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/temporal-worker/workflows/transaction_settlement.go): `services/temporal-worker/workflows/transaction_settlement.go`
- [Workflow activities](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/temporal-worker/activities/activities.go): `services/temporal-worker/activities/activities.go`

### Persistence and observability

- [PostgreSQL transactions](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/database/postgres.service.ts): `services/api-gateway/src/database/postgres.service.ts`
- [Audit trail](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/database/audit.service.ts): `services/api-gateway/src/database/audit.service.ts`
- [Prometheus metrics](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/services/api-gateway/src/monitoring/metrics.service.ts): `services/api-gateway/src/monitoring/metrics.service.ts`

### Client SDKs

- [JavaScript SDK](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/sdks/sdk-js/src/index.ts): `sdks/sdk-js/src/index.ts`
- [Go SDK](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/sdks/sdk-go/client.go): `sdks/sdk-go/client.go`
- [Python SDK](https://github.com/khayaai/openfireblocks/blob/claude/openfireblocks-mvp-plan-hvr6p1/sdks/sdk-python/openfireblocks/client.py): `sdks/sdk-python/openfireblocks/client.py`

### Other components

- **Tenant client**
- **Platform admin**
- **Vault key store**
- **immudb audit store**
- **Ethereum network**

## Connections

- Tenant client → JavaScript SDK: uses
- Tenant client → Go SDK: uses
- Tenant client → Python SDK: uses
- JavaScript SDK → API gateway: calls API
- Go SDK → API gateway: calls API
- Python SDK → API gateway: calls API
- Platform admin → Admin routes: manages tenants (evidence: `services/api-gateway/src/customers/customer.controller.ts`)
- Admin routes → Tenant management: manages (evidence: `services/api-gateway/src/customers/customer.controller.ts`)
- Tenant client → Signing API: submits request (evidence: `services/api-gateway/src/sign/sign.controller.ts`)
- Signing API → API-key auth: guards routes (evidence: `services/api-gateway/src/sign/sign.controller.ts`)
- API-key auth → Tenant management: resolves key (evidence: `services/api-gateway/src/auth/api-key.guard.ts`)
- Signing API → Sign orchestration: delegates signing (evidence: `services/api-gateway/src/sign/sign.controller.ts`)
- Sign orchestration → Policy checks: evaluates policy (evidence: `services/api-gateway/src/sign/sign.service.ts`)
- Sign orchestration → Risk controls: checks velocity (evidence: `services/api-gateway/src/sign/sign.service.ts`)
- Sign orchestration → MPC signer: requests signature (evidence: `services/api-gateway/src/sign/sign.service.ts`)
- Sign orchestration → PostgreSQL transactions: saves transaction (evidence: `services/api-gateway/src/sign/sign.service.ts`)
- Sign orchestration → Audit trail: records events (evidence: `services/api-gateway/src/sign/sign.service.ts`)
- Sign orchestration → Ethereum RPC: broadcasts signed tx (evidence: `services/api-gateway/src/sign/sign.service.ts`)
- Signing API → Transaction preparation: prepares request (evidence: `services/api-gateway/src/sign/sign.controller.ts`)
- Transaction preparation → Ethereum RPC: gets network data (evidence: `services/api-gateway/src/blockchain/prepare.service.ts`)
- Ethereum RPC → Ethereum network: submits transaction
- Signing API → PostgreSQL transactions: reads transactions (evidence: `services/api-gateway/src/sign/sign.controller.ts`)
- Signing API → Audit trail: reads audit trail (evidence: `services/api-gateway/src/sign/sign.controller.ts`)
- MPC signer → TSS core: uses core
- MPC signer → Vault key store: loads keys
- MPC signer → immudb audit store: writes audit
- Settlement API → API-key auth: guards routes (evidence: `services/api-gateway/src/settlements/settlements.controller.ts`)
- Settlement API → Temporal client: starts workflow (evidence: `services/api-gateway/src/settlements/settlements.controller.ts`)
- Temporal client → Workflow worker: dispatches workflow
- Workflow worker → Settlement workflow: runs (evidence: `services/temporal-worker/main.go`)
- Settlement workflow → Workflow activities: executes activities (evidence: `services/temporal-worker/workflows/transaction_settlement.go`)
- API gateway → Prometheus metrics: exposes metrics
- Policy checks → OPA policy service: evaluates remotely
