# smartcontractkit/chainlink architecture

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

- Interactive diagram: https://gitdiagram.com/smartcontractkit/chainlink
- Repository: https://github.com/smartcontractkit/chainlink

## Overview

1. **Repository shape and runtime boundaries**
   - This is a multi-module Go monorepo centered on the **Chainlink node**.
   - The main runtime lives under `core/`; supporting modules are `core/scripts` and `integration-tests`, with a separate `deployment/` tree for onchain/offchain provisioning.
   - The node is a long-running service backed by **Postgres**, configured by **TOML + environment variables**, and packaged for Docker.

2. **Node bootstrap and service composition**
   - `core/main.go` starts the application; `core/services/chainlink` is the main orchestration layer that assembles configuration, database access, keystores, relayers, web server, telemetry, and background services.
   - `core/services/service.go`, `multi.go`, `nurse.go`, and related packages show that the node is composed as many independently started/stopped services rather than a single monolith.
   - Shutdown and recovery are explicit concerns (`core/shutdown`, `core/recovery`).

3. **Primary control plane: Web API, UI, and CLI**
   - `core/web` exposes the HTTP API, GraphQL resolvers, controllers, auth, middleware, and the embedded operator UI assets.
   - `core/cmd` implements the CLI used for local and remote node administration; it talks to the same backend exposed by the web/API layer.
   - This is the operator-facing control plane for creating jobs, managing keys, viewing chains/logs/txs, and configuring node state.

4. **Persistence and schema management**
   - `core/store` owns the database schema, migrations, fixtures, and low-level store models.
   - Most operational state is persisted here: jobs, runs, keys, chains, transactions, logs, OCR state, workflow specs, telemetry-related tables, and many capability-specific records.
   - The architecture assumes Postgres as the durable system of record; many services have ORM-style layers under `core/services/*/orm.go`.

5. **Job execution pipeline**
   - `core/services/pipeline` is the general-purpose execution engine for task graphs: fetching inputs, evaluating tasks, scheduling runs, and producing outputs.
   - It includes task implementations for HTTP, JSON/CBOR parsing, crypto/encoding helpers, ETH calls/txs, math, and workflow-specific plumbing.
   - This layer is the main dataflow engine for traditional Chainlink jobs: external data enters here, is transformed by tasks, and may result in blockchain writes or adapter calls.

6. **Chain interactions, keys, and relayers**
   - `core/services/relay` contains chain-specific relayer implementations, especially EVM, plus dummy/adapter variants.
   - `core/services/keystore` and `core/services/p2p` manage signing keys, peer identity, and communication identity across protocols.
   - `core/services/ocr`, `ocr2`, `ocr3`, `vrf`, `functions`, `feeds`, `gateway`, and related packages are specialized protocol services that sit on top of the relay/keystore foundation.

7. **Capabilities and the CRE/workflow subsystem**
   - `core/capabilities` and `core/services/workflows` represent the newer **capabilities/workflows** architecture.
   - Capabilities cover triggers, executable/target modules, remote execution, confidential relay, vault access, web API, streams, compute, CCIP helpers, and test fakes.
   - `core/services/workflows` provides workflow engine, syncers, registries, artifacts, metering, sharding, secrets handling, and v2 execution paths; it is a distinct orchestration layer from the older job pipeline.

8. **Gateway and remote execution path**
   - `core/services/gateway` and `core/capabilities/remote` implement the gateway/dispatcher side of distributed capability execution.
   - These packages handle request routing, HTTP/WebSocket networking, request caching, response aggregation, and protocol handlers such as functions, vault, confidential relay, and web API capabilities.
   - The data flow here is: workflow or capability requests are dispatched over the gateway/network boundary to workers or peers, then aggregated back into node state.

9. **Protocol-specific subsystems**
   - The repo contains large protocol verticals: `ocr`, `ocr2`, `ocr3`, `vrf`, `ccip`, `llo`, `s4`, `ring`, `cron`, `blockhashstore`, `blockheaderfeeder`, `registrysyncer`, `feeds`, `functions`, `vault`, `standardcapabilities`, and `shardorchestrator`.
   - Each vertical usually includes delegates, validation, onchain readers/transmitters, telemetry, and tests.
   - For architecture diagrams, these are best drawn as specialized services fed by the shared runtime, keystore, pipeline/workflow engine, and Postgres.

10. **Telemetry, monitoring, and observability**
   - `core/services/telemetry`, `core/services/synchronization`, `core/services/headreporter`, `core/logger`, and related packages centralize metrics/logging/tracing/ingress.
   - The repo also includes protobuf-based telemetry schemas and ingestion clients, indicating explicit outbound telemetry streams in addition to logs and Prometheus-style metrics.
   - Observability is a first-class boundary: many services emit metrics, and some protocols batch and forward structured telemetry to external systems.

11. **Deployment and contract orchestration**
   - `deployment/` is a separate tooling and orchestration layer for provisioning contracts, jobs, registries, forwarders, and chain environments.
   - It covers CCIP, CRE, data feeds, vault, tokens, Keystone, and environment setup, with “changesets,” “operations,” “sequences,” and “views” around onchain state transitions.
   - This code does not run as the node runtime; it coordinates external blockchain state and node/job configuration.

12. **Scripts, test harnesses, and environment simulation**
   - `core/scripts`, `integration-tests`, and `system-tests` contain operator tooling, testnet harnesses, Docker/Kubernetes fixtures, smoke/regression/load tests, and environment builders.
   - These modules simulate or manage the external dependencies the node talks to: blockchains, gateways, mock services, job distributor, and test containers.
   - `tools/` and `plugins/` support local development, release tooling, plugin installation, and test automation.

13. **External dependencies and integration surfaces**
   - The node integrates with **Postgres**, blockchain nodes (especially EVM, but also Solana, Aptos, Sui, Tron, Starknet, Cosmos, TON), external adapters, gateways, and telemetry sinks.
   - Docker images and CI workflows indicate the repo is built and validated as a deployable node binary plus optional plugin image.
   - For an architecture diagram, the main external edges are: blockchain RPC/WebSocket endpoints, Postgres, operator browser/CLI, external adapters/services, and telemetry backends.

14. **Suggested high-level diagram framing**
   - Center the diagram on the **Chainlink node runtime**.
   - Around it, show: control plane (web UI/API/CLI), execution plane (pipeline/workflows/capabilities), chain-facing services (relayers/keystores/OCR/VRF/CCIP/etc.), persistence (Postgres/store), and observability.
   - Put `deployment/`, `integration-tests/`, `system-tests/`, and `core/scripts/` outside the runtime as orchestration and validation layers rather than live runtime components.

Main entry points: [`core/services/chainlink`](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/chainlink) (Chainlink app), [`core/capabilities`](https://github.com/smartcontractkit/chainlink/tree/develop/core/capabilities) (Capabilities), [`core/web`](https://github.com/smartcontractkit/chainlink/tree/develop/core/web) (Web API), [`core/services/keystore`](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/keystore) (Keystore)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Node Runtime"]
  node_node_main(("Main<br/>entrypoint<br/>[main.go]"))
  node_node_chainlink["Chainlink app<br/>orchestrator"]
  node_node_services["Service graph<br/>service-composition<br/>[service.go]"]
  node_node_shutdown["Shutdown<br/>lifecycle"]
  node_node_recovery["Recovery<br/>lifecycle"]
  node_node_pipeline["Pipeline<br/>task-engine"]
  node_node_telemetry["Telemetry<br/>observability"]
end

subgraph group_group_protocols["Protocol Services"]
  node_node_relay["Relayers<br/>chain-relay"]
  node_node_keystore["Keystore<br/>signing-keys"]
  node_node_ocr["OCR stack<br/>oracle-network"]
  node_node_vrf["VRF<br/>oracle-vertical"]
end

subgraph group_group_capabilities["Capabilities & Workflows"]
  node_node_gateway["Gateway<br/>remote-dispatch"]
  node_node_capabilities["Capabilities<br/>capability-registry"]
  node_node_workflows["Workflows<br/>workflow-engine"]
end

subgraph group_group_control["Control Plane"]
  node_node_web["Web API<br/>http/graphql"]
  node_node_cli["CLI"]
end

subgraph group_group_data["Persistence & Config"]
  node_node_store[("Store<br/>postgres-schema")]
  node_node_config["Config"]
end

subgraph group_group_ops["Ops & Validation"]
  node_node_deployment["Deployment<br/>provisioning"]
  node_node_tests["Tests<br/>harnesses"]
end

node_node_pg[("Postgres<br/>external-db")]

node_node_main -->|"boots"| node_node_chainlink
node_node_chainlink -->|"assembles"| node_node_services
node_node_chainlink -->|"loads"| node_node_config
node_node_chainlink -->|"uses"| node_node_store
node_node_chainlink -->|"serves"| node_node_web
node_node_chainlink -->|"runs"| node_node_pipeline
node_node_chainlink -->|"connects"| node_node_relay
node_node_chainlink -->|"signs with"| node_node_keystore
node_node_chainlink -->|"hosts"| node_node_ocr
node_node_chainlink -->|"hosts"| node_node_vrf
node_node_chainlink -->|"hosts"| node_node_gateway
node_node_chainlink -->|"loads"| node_node_capabilities
node_node_chainlink -->|"runs"| node_node_workflows
node_node_chainlink -->|"emits"| node_node_telemetry
node_node_chainlink -->|"stops via"| node_node_shutdown
node_node_chainlink -->|"recovers via"| node_node_recovery
node_node_web -.->|"shared backend"| node_node_cli
node_node_web -->|"reads/writes"| node_node_store
node_node_cli -.->|"calls"| node_node_web
node_node_pipeline -->|"persists"| node_node_pg
node_node_store -->|"backed by"| node_node_pg
node_node_workflows -->|"persists"| node_node_pg
node_node_gateway -->|"dispatches"| node_node_capabilities
node_node_gateway -.->|"feeds"| node_node_workflows
node_node_ocr -->|"uses"| node_node_relay
node_node_ocr -->|"signs with"| node_node_keystore
node_node_vrf -->|"signs with"| node_node_keystore
node_node_capabilities -->|"authenticates"| node_node_keystore
node_node_capabilities -->|"targets chains"| node_node_relay
node_node_telemetry -.->|"samples from"| node_node_pg
node_node_deployment -.->|"provisions"| node_node_chainlink
node_node_tests -.->|"validates"| node_node_chainlink
node_node_tests -.->|"simulates"| node_node_deployment

click node_node_main "https://github.com/smartcontractkit/chainlink/blob/develop/core/main.go"
click node_node_chainlink "https://github.com/smartcontractkit/chainlink/tree/develop/core/services/chainlink"
click node_node_services "https://github.com/smartcontractkit/chainlink/blob/develop/core/services/service.go"
click node_node_shutdown "https://github.com/smartcontractkit/chainlink/tree/develop/core/shutdown"
click node_node_recovery "https://github.com/smartcontractkit/chainlink/tree/develop/core/recovery"
click node_node_web "https://github.com/smartcontractkit/chainlink/tree/develop/core/web"
click node_node_cli "https://github.com/smartcontractkit/chainlink/tree/develop/core/cmd"
click node_node_store "https://github.com/smartcontractkit/chainlink/tree/develop/core/store"
click node_node_config "https://github.com/smartcontractkit/chainlink/tree/develop/core/config"
click node_node_pipeline "https://github.com/smartcontractkit/chainlink/tree/develop/core/services/pipeline"
click node_node_relay "https://github.com/smartcontractkit/chainlink/tree/develop/core/services/relay"
click node_node_keystore "https://github.com/smartcontractkit/chainlink/tree/develop/core/services/keystore"
click node_node_ocr "https://github.com/smartcontractkit/chainlink/tree/develop/core/services/ocr2"
click node_node_vrf "https://github.com/smartcontractkit/chainlink/tree/develop/core/services/vrf"
click node_node_gateway "https://github.com/smartcontractkit/chainlink/tree/develop/core/services/gateway"
click node_node_capabilities "https://github.com/smartcontractkit/chainlink/tree/develop/core/capabilities"
click node_node_workflows "https://github.com/smartcontractkit/chainlink/tree/develop/core/services/workflows"
click node_node_telemetry "https://github.com/smartcontractkit/chainlink/tree/develop/core/services/telemetry"
click node_node_deployment "https://github.com/smartcontractkit/chainlink/tree/develop/deployment"
click node_node_tests "https://github.com/smartcontractkit/chainlink/tree/develop/integration-tests"

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_node_main,node_node_chainlink,node_node_services,node_node_shutdown,node_node_recovery,node_node_pipeline,node_node_telemetry toneBlue
class node_node_relay,node_node_keystore,node_node_ocr,node_node_vrf toneAmber
class node_node_gateway,node_node_capabilities,node_node_workflows toneMint
class node_node_web,node_node_cli toneRose
class node_node_store,node_node_config toneIndigo
class node_node_deployment,node_node_tests toneTeal
class node_node_pg toneNeutral
```

## Components

### Node Runtime

Live Chainlink node process and core subsystems.

- [Main](https://github.com/smartcontractkit/chainlink/blob/develop/core/main.go): entrypoint · Starts the Chainlink node binary. · `core/main.go`
- [Chainlink app](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/chainlink): orchestrator · Assembles config, database, keys, relayers, web server, telemetry, and services. · `core/services/chainlink`
- [Service graph](https://github.com/smartcontractkit/chainlink/blob/develop/core/services/service.go): service-composition · Lifecycle orchestration for independently started/stopped services. · `core/services/service.go`
- [Shutdown](https://github.com/smartcontractkit/chainlink/tree/develop/core/shutdown): lifecycle · Explicit shutdown coordination. · `core/shutdown`
- [Recovery](https://github.com/smartcontractkit/chainlink/tree/develop/core/recovery): lifecycle · Crash/recovery handling and restart safety. · `core/recovery`
- [Pipeline](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/pipeline): task-engine · Traditional job execution engine for task graphs and run scheduling. · `core/services/pipeline`
- [Telemetry](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/telemetry): observability · Metrics, tracing, telemetry ingress, head reporting, and observability streams. · `core/services/telemetry`

### Protocol Services

Specialized chain-facing services and protocol verticals.

- [Relayers](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/relay): chain-relay · Chain-specific relayer implementations and write/read transport abstractions. · `core/services/relay`
- [Keystore](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/keystore): signing-keys · Chain, OCR, P2P, VRF, and workflow signing identity management. · `core/services/keystore`
- [OCR stack](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/ocr2): oracle-network · OCR, OCR2, OCR3, bootstrap, and protocol plugin implementations. · `core/services/ocr2`
- [VRF](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/vrf): oracle-vertical · VRF listeners, proof generation, and protocol-specific state. · `core/services/vrf`

### Capabilities & Workflows

CRE/workflow execution and remote capability paths.

- [Gateway](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/gateway): remote-dispatch · Request routing, network handlers, caching, and response aggregation for remote execution. · `core/services/gateway`
- [Capabilities](https://github.com/smartcontractkit/chainlink/tree/develop/core/capabilities): capability-registry · Capability registry, triggers, executables, targets, and protocol adapters. · `core/capabilities`
- [Workflows](https://github.com/smartcontractkit/chainlink/tree/develop/core/services/workflows): workflow-engine · Workflow engine, syncers, artifacts, metering, sharding, and v2 execution paths. · `core/services/workflows`

### Control Plane

Operator UI, API, and CLI surfaces.

- [Web API](https://github.com/smartcontractkit/chainlink/tree/develop/core/web): http/graphql · HTTP API, GraphQL, auth, middleware, controllers, and embedded operator UI. · `core/web`
- [CLI](https://github.com/smartcontractkit/chainlink/tree/develop/core/cmd): operator-cli · Node administration commands for local and remote control. · `core/cmd`

### Persistence & Config

Database, schema, config, and store layers.

- [Store](https://github.com/smartcontractkit/chainlink/tree/develop/core/store): postgres-schema · Database schema, migrations, fixtures, and low-level models. · `core/store`
- [Config](https://github.com/smartcontractkit/chainlink/tree/develop/core/config): toml-env-config · Node configuration parsing and environment/TOML binding. · `core/config`

### Ops & Validation

Deployment, scripts, and test harnesses.

- [Deployment](https://github.com/smartcontractkit/chainlink/tree/develop/deployment): provisioning · Onchain/offchain provisioning, changesets, and environment orchestration. · `deployment`
- [Tests](https://github.com/smartcontractkit/chainlink/tree/develop/integration-tests): harnesses · Integration, system, smoke, load, and environment simulation tooling. · `integration-tests`

### Other components

- **Postgres**: external-db · Durable system of record for jobs, runs, keys, chains, transactions, and workflow state.

## Connections

- Main → Chainlink app: boots · Entrypoint starts the node application.
- Chainlink app → Service graph: assembles · Builds the runtime from many independently managed services.
- Chainlink app → Config: loads · Reads TOML and environment-based configuration.
- Chainlink app → Store: uses · Initializes schema, migrations, and data access.
- Chainlink app → Web API: serves · Exposes operator HTTP and GraphQL control plane.
- Chainlink app → Pipeline: runs · Executes traditional job pipelines.
- Chainlink app → Relayers: connects · Creates chain relayers and transport adapters.
- Chainlink app → Keystore: signs with · Uses signing keys and node identity services.
- Chainlink app → OCR stack: hosts · Starts OCR-family protocol services and plugins.
- Chainlink app → VRF: hosts · Starts VRF protocol services.
- Chainlink app → Gateway: hosts · Runs gateway/dispatcher services for remote capabilities.
- Chainlink app → Capabilities: loads · Registers capability implementations and adapters.
- Chainlink app → Workflows: runs · Manages workflow engine and sync paths.
- Chainlink app → Telemetry: emits · Publishes metrics, traces, and telemetry.
- Chainlink app → Shutdown: stops via · Coordinates graceful shutdown.
- Chainlink app → Recovery: recovers via · Applies recovery and restart safety.
- Web API → CLI: shared backend · CLI and web API operate on the same node backend.
- Web API → Store: reads/writes · Operator actions are persisted in the store.
- CLI → Web API: calls · CLI drives the node through the operator API.
- Pipeline → Postgres: persists · Job runs and task state are stored in Postgres.
- Store → Postgres: backed by · Persistent system of record is Postgres.
- Workflows → Postgres: persists · Workflow specs, artifacts, secrets, and execution state are stored.
- Gateway → Capabilities: dispatches · Routes remote capability requests to executors and handlers.
- Gateway → Workflows: feeds · Workflow or capability requests originate from workflow runtime.
- OCR stack → Relayers: uses · OCR protocol execution depends on relayers for chain interaction.
- OCR stack → Keystore: signs with · OCR uses protocol keys and peer identity.
- VRF → Keystore: signs with · VRF uses dedicated signing material.
- Capabilities → Keystore: authenticates · Capabilities rely on node identity and signing keys.
- Capabilities → Relayers: targets chains · Some capabilities write to or read from blockchains.
- Telemetry → Postgres: samples from · Observability and ingestion can reference persisted state.
- Deployment → Chainlink app: provisions · Deployment orchestrates node configuration and jobs.
- Tests → Chainlink app: validates · Integration and system tests exercise the live node runtime.
- Tests → Deployment: simulates · Test harnesses model chain and environment setup.