# finos/fdc3 architecture

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

- Interactive diagram: https://gitdiagram.com/finos/fdc3
- Repository: https://github.com/finos/fdc3

## Overview

FDC3 is an interoperability standard and TypeScript monorepo for financial desktop applications: apps share context, launch one another, and resolve intents through a Desktop Agent. This map focuses on the standard’s runtime-facing packages, the browser agent-connection path, the reference web agent, security extensions, and the workbench. The README documents the broader app-directory, context, intent, and bridging capabilities. Some subsystems are represented from documented purpose and tree paths; their internal wiring is not inferred where source excerpts do not establish it.

Main entry points: [`toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts`](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts) (Web agent server), [`toolbox/fdc3-for-web/fdc3-web-impl/src/ServerContext.ts`](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/ServerContext.ts) (Agent runtime state), [`packages/fdc3-get-agent/src/strategies/IdentityValidationHandler.ts`](https://github.com/finos/fdc3/blob/main/packages/fdc3-get-agent/src/strategies/IdentityValidationHandler.ts) (Identity validation), [`toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/IntentHandler.ts`](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/IntentHandler.ts) (Intent resolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_standard["Standard and types"]
  node_standard_api["Agent API<br/>[DesktopAgent.ts]"]
  node_context_types["Context types<br/>[index.ts]"]
  node_schema["Protocol schemas<br/>[index.ts]"]
end

subgraph group_client["Agent client"]
  node_agent_proxy["Agent proxy"]
  node_proxy_messaging["Proxy messaging<br/>[Messaging.ts]"]
  node_proxy_listeners["Listener registration"]
  node_get_agent["getAgent connector<br/>[getAgent.ts]"]
  node_hello["Handshake<br/>[HelloHandler.ts]"]
  node_identity["Identity validation"]
  node_mp_messaging["Message-port transport"]
end

subgraph group_server["Web agent"]
  node_web_server["Web agent server<br/>[BasicFDC3Server.ts]"]
  node_server_context["Agent runtime state<br/>[ServerContext.ts]"]
  node_directory["App directory"]
  node_broadcast["Context and channels"]
  node_intents["Intent resolution<br/>[IntentHandler.ts]"]
  node_open["App launch<br/>[OpenHandler.ts]"]
  node_heartbeat["Heartbeat"]
end

subgraph group_security["Security extensions"]
  node_signature["Signature verification"]
  node_metadata["Context metadata<br/>[MetadataHandler.ts]"]
  node_public_security["Public security"]
  node_secure_bridge["Secure remote handlers"]
end

subgraph group_tools["Workbench"]
  node_workbench["Workbench UI<br/>[App.tsx]"]
  node_workbench_api["FDC3 API adapter<br/>[Fdc3Api.ts]"]
  node_context_editor["Context editor<br/>[ContextCreate.tsx]"]
  node_context_store["Context state<br/>[ContextStore.ts]"]
end

node_apps(("FDC3 apps"))

node_apps -->|"use API"| node_standard_api
node_apps -->|"exchange context"| node_context_types
node_apps -.->|"coordinate through"| node_web_server
node_get_agent -.->|"connects via"| node_hello
node_hello -->|"creates connection"| node_mp_messaging
node_get_agent -.->|"validates identity"| node_identity
node_identity -.->|"uses transport"| node_mp_messaging
node_identity -->|"checks protocol messages"| node_schema
node_agent_proxy -.->|"uses messaging"| node_proxy_messaging
node_proxy_messaging -->|"registers listeners"| node_proxy_listeners
node_web_server -->|"uses runtime context"| node_server_context
node_web_server -->|"dispatches to"| node_broadcast
node_web_server -->|"dispatches to"| node_intents
node_web_server -->|"dispatches to"| node_open
node_web_server -->|"registers optionally"| node_heartbeat
node_web_server -->|"configures handlers"| node_directory
node_broadcast -->|"uses runtime context"| node_server_context
node_intents -->|"uses runtime context"| node_server_context
node_intents -->|"looks up apps"| node_directory
node_open -->|"opens apps"| node_server_context
node_open -->|"looks up apps"| node_directory
node_signature -->|"unpacks metadata"| node_metadata
node_signature -->|"verifies signatures"| node_public_security
node_secure_bridge -->|"wraps agent handlers"| node_standard_api
node_secure_bridge -->|"uses message types"| node_schema
node_workbench -->|"checks agent"| node_workbench_api
node_workbench -.->|"presents tools"| node_context_editor
node_context_editor -->|"updates context state"| node_context_store
node_context_editor -->|"uses agent adapter"| node_workbench_api
node_context_store -->|"uses agent adapter"| node_workbench_api

click node_standard_api "https://github.com/finos/fdc3/blob/main/packages/fdc3-standard/src/api/DesktopAgent.ts"
click node_context_types "https://github.com/finos/fdc3/blob/main/packages/fdc3-context/src/index.ts"
click node_schema "https://github.com/finos/fdc3/blob/main/packages/fdc3-schema/src/index.ts"
click node_agent_proxy "https://github.com/finos/fdc3/blob/main/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts"
click node_proxy_messaging "https://github.com/finos/fdc3/blob/main/packages/fdc3-agent-proxy/src/Messaging.ts"
click node_proxy_listeners "https://github.com/finos/fdc3/blob/main/packages/fdc3-agent-proxy/src/listeners/RegisterableListener.ts"
click node_get_agent "https://github.com/finos/fdc3/blob/main/packages/fdc3-get-agent/src/strategies/getAgent.ts"
click node_hello "https://github.com/finos/fdc3/blob/main/packages/fdc3-get-agent/src/strategies/HelloHandler.ts"
click node_identity "https://github.com/finos/fdc3/blob/main/packages/fdc3-get-agent/src/strategies/IdentityValidationHandler.ts"
click node_mp_messaging "https://github.com/finos/fdc3/blob/main/packages/fdc3-get-agent/src/messaging/MessagePortMessaging.ts"
click node_web_server "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts"
click node_server_context "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/ServerContext.ts"
click node_directory "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/directory/DirectoryInterface.ts"
click node_broadcast "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/BroadcastHandler.ts"
click node_intents "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/IntentHandler.ts"
click node_open "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/OpenHandler.ts"
click node_heartbeat "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/HeartbeatHandler.ts"
click node_signature "https://github.com/finos/fdc3/blob/main/packages/fdc3-security/src/signing/SignatureCheckingHandlerSupport.ts"
click node_metadata "https://github.com/finos/fdc3/blob/main/packages/fdc3-security/src/delegates/MetadataHandler.ts"
click node_public_security "https://github.com/finos/fdc3/blob/main/packages/fdc3-security/src/impl/PublicFDC3Security.ts"
click node_secure_bridge "https://github.com/finos/fdc3/blob/main/packages/fdc3-security/src/secure-boundary/ClientSideHandlersImpl.ts"
click node_workbench "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-workbench/src/App.tsx"
click node_workbench_api "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-workbench/src/utility/Fdc3Api.ts"
click node_context_editor "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-workbench/src/components/ContextCreate.tsx"
click node_context_store "https://github.com/finos/fdc3/blob/main/toolbox/fdc3-workbench/src/store/ContextStore.ts"

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_standard_api,node_context_types,node_schema toneBlue
class node_agent_proxy,node_proxy_messaging,node_proxy_listeners,node_get_agent,node_hello,node_identity,node_mp_messaging toneAmber
class node_web_server,node_server_context,node_directory,node_broadcast,node_intents,node_open,node_heartbeat toneMint
class node_signature,node_metadata,node_public_security,node_secure_bridge toneRose
class node_workbench,node_workbench_api,node_context_editor,node_context_store,node_apps toneIndigo
```

## Components

### Standard and types

- [Agent API](https://github.com/finos/fdc3/blob/main/packages/fdc3-standard/src/api/DesktopAgent.ts): `packages/fdc3-standard/src/api/DesktopAgent.ts`
- [Context types](https://github.com/finos/fdc3/blob/main/packages/fdc3-context/src/index.ts): `packages/fdc3-context/src/index.ts`
- [Protocol schemas](https://github.com/finos/fdc3/blob/main/packages/fdc3-schema/src/index.ts): `packages/fdc3-schema/src/index.ts`

### Agent client

- [Agent proxy](https://github.com/finos/fdc3/blob/main/packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts): `packages/fdc3-agent-proxy/src/DesktopAgentProxy.ts`
- [Proxy messaging](https://github.com/finos/fdc3/blob/main/packages/fdc3-agent-proxy/src/Messaging.ts): `packages/fdc3-agent-proxy/src/Messaging.ts`
- [Listener registration](https://github.com/finos/fdc3/blob/main/packages/fdc3-agent-proxy/src/listeners/RegisterableListener.ts): `packages/fdc3-agent-proxy/src/listeners/RegisterableListener.ts`
- [getAgent connector](https://github.com/finos/fdc3/blob/main/packages/fdc3-get-agent/src/strategies/getAgent.ts): `packages/fdc3-get-agent/src/strategies/getAgent.ts`
- [Handshake](https://github.com/finos/fdc3/blob/main/packages/fdc3-get-agent/src/strategies/HelloHandler.ts): `packages/fdc3-get-agent/src/strategies/HelloHandler.ts`
- [Identity validation](https://github.com/finos/fdc3/blob/main/packages/fdc3-get-agent/src/strategies/IdentityValidationHandler.ts): `packages/fdc3-get-agent/src/strategies/IdentityValidationHandler.ts`
- [Message-port transport](https://github.com/finos/fdc3/blob/main/packages/fdc3-get-agent/src/messaging/MessagePortMessaging.ts): `packages/fdc3-get-agent/src/messaging/MessagePortMessaging.ts`

### Web agent

- [Web agent server](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts): `toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts`
- [Agent runtime state](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/ServerContext.ts): `toolbox/fdc3-for-web/fdc3-web-impl/src/ServerContext.ts`
- [App directory](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/directory/DirectoryInterface.ts): `toolbox/fdc3-for-web/fdc3-web-impl/src/directory/DirectoryInterface.ts`
- [Context and channels](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/BroadcastHandler.ts): `toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/BroadcastHandler.ts`
- [Intent resolution](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/IntentHandler.ts): `toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/IntentHandler.ts`
- [App launch](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/OpenHandler.ts): `toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/OpenHandler.ts`
- [Heartbeat](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/HeartbeatHandler.ts): `toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/HeartbeatHandler.ts`

### Security extensions

- [Signature verification](https://github.com/finos/fdc3/blob/main/packages/fdc3-security/src/signing/SignatureCheckingHandlerSupport.ts): `packages/fdc3-security/src/signing/SignatureCheckingHandlerSupport.ts`
- [Context metadata](https://github.com/finos/fdc3/blob/main/packages/fdc3-security/src/delegates/MetadataHandler.ts): `packages/fdc3-security/src/delegates/MetadataHandler.ts`
- [Public security](https://github.com/finos/fdc3/blob/main/packages/fdc3-security/src/impl/PublicFDC3Security.ts): `packages/fdc3-security/src/impl/PublicFDC3Security.ts`
- [Secure remote handlers](https://github.com/finos/fdc3/blob/main/packages/fdc3-security/src/secure-boundary/ClientSideHandlersImpl.ts): `packages/fdc3-security/src/secure-boundary/ClientSideHandlersImpl.ts`

### Workbench

- [Workbench UI](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-workbench/src/App.tsx): `toolbox/fdc3-workbench/src/App.tsx`
- [FDC3 API adapter](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-workbench/src/utility/Fdc3Api.ts): `toolbox/fdc3-workbench/src/utility/Fdc3Api.ts`
- [Context editor](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-workbench/src/components/ContextCreate.tsx): `toolbox/fdc3-workbench/src/components/ContextCreate.tsx`
- [Context state](https://github.com/finos/fdc3/blob/main/toolbox/fdc3-workbench/src/store/ContextStore.ts): `toolbox/fdc3-workbench/src/store/ContextStore.ts`

### Other components

- **FDC3 apps**

## Connections

- FDC3 apps → Agent API: use API (evidence: `README.md`)
- FDC3 apps → Context types: exchange context (evidence: `README.md`)
- FDC3 apps → Web agent server: coordinate through
- getAgent connector → Handshake: connects via
- Handshake → Message-port transport: creates connection (evidence: `packages/fdc3-get-agent/src/strategies/HelloHandler.ts`)
- getAgent connector → Identity validation: validates identity
- Identity validation → Message-port transport: uses transport
- Identity validation → Protocol schemas: checks protocol messages (evidence: `packages/fdc3-get-agent/src/strategies/IdentityValidationHandler.ts`)
- Agent proxy → Proxy messaging: uses messaging
- Proxy messaging → Listener registration: registers listeners (evidence: `packages/fdc3-agent-proxy/src/Messaging.ts`)
- Web agent server → Agent runtime state: uses runtime context (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts`)
- Web agent server → Context and channels: dispatches to (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts`)
- Web agent server → Intent resolution: dispatches to (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts`)
- Web agent server → App launch: dispatches to (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts`)
- Web agent server → Heartbeat: registers optionally (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts`)
- Web agent server → App directory: configures handlers (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/BasicFDC3Server.ts`)
- Context and channels → Agent runtime state: uses runtime context (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/BroadcastHandler.ts`)
- Intent resolution → Agent runtime state: uses runtime context (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/IntentHandler.ts`)
- Intent resolution → App directory: looks up apps (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/IntentHandler.ts`)
- App launch → Agent runtime state: opens apps (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/OpenHandler.ts`)
- App launch → App directory: looks up apps (evidence: `toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/OpenHandler.ts`)
- Signature verification → Context metadata: unpacks metadata (evidence: `packages/fdc3-security/src/signing/SignatureCheckingHandlerSupport.ts`)
- Signature verification → Public security: verifies signatures (evidence: `packages/fdc3-security/src/signing/SignatureCheckingHandlerSupport.ts`)
- Secure remote handlers → Agent API: wraps agent handlers (evidence: `packages/fdc3-security/src/secure-boundary/ClientSideHandlersImpl.ts`)
- Secure remote handlers → Protocol schemas: uses message types (evidence: `packages/fdc3-security/src/secure-boundary/ClientSideHandlersImpl.ts`)
- Workbench UI → FDC3 API adapter: checks agent (evidence: `toolbox/fdc3-workbench/src/App.tsx`)
- Workbench UI → Context editor: presents tools
- Context editor → Context state: updates context state (evidence: `toolbox/fdc3-workbench/src/components/ContextCreate.tsx`)
- Context editor → FDC3 API adapter: uses agent adapter (evidence: `toolbox/fdc3-workbench/src/components/ContextCreate.tsx`)
- Context state → FDC3 API adapter: uses agent adapter (evidence: `toolbox/fdc3-workbench/src/store/ContextStore.ts`)