# heade/airbyte architecture

> Architecture diagram of the GitHub repository heade/airbyte, 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/heade/airbyte
- Repository: https://github.com/heade/airbyte

## Overview

Airbyte is a self-hosted data integration platform. Users configure a source, destination, and connection in the web app; the platform schedules a sync, runs source and destination connectors, and transfers records with state for incremental replication. The map highlights the UI, orchestration, connector runtime, and persistence layers, plus optional normalization and analytics. Some subsystem links are documented at product level or strongly implied by the architecture but not shown in sampled callers; these are marked dashed and uncited.

Main entry points: [`airbyte-workers/src/main/java/io/airbyte/workers/DefaultReplicationWorker.java`](https://github.com/heade/airbyte/blob/master/airbyte-workers/src/main/java/io/airbyte/workers/DefaultReplicationWorker.java) (Replication Worker), [`airbyte-server/src/main/java/io/airbyte/server/handlers`](https://github.com/heade/airbyte/tree/master/airbyte-server/src/main/java/io/airbyte/server/handlers) (Server Handlers), [`airbyte-scheduler/client/src/main/java/io/airbyte/scheduler/client/DefaultSynchronousSchedulerClient.java`](https://github.com/heade/airbyte/blob/master/airbyte-scheduler/client/src/main/java/io/airbyte/scheduler/client/DefaultSynchronousSchedulerClient.java) (Scheduler Client), [`airbyte-integrations/connectors`](https://github.com/heade/airbyte/tree/master/airbyte-integrations/connectors) (Destination Connectors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Configuration UI"]
  node_webapp["Web Application<br/>[App.tsx]"]
  node_routes["UI Routes<br/>[routes.tsx]"]
end

subgraph group_control["Control Plane"]
  node_server["Server Handlers"]
  node_scheduler["Scheduler Client"]
  node_temporal["Temporal Jobs"]
end

subgraph group_runtime["Connector Runtime"]
  node_worker["Replication Worker"]
  node_workerutils["Worker Utilities<br/>[WorkerUtils.java]"]
  node_entrypoint["Connector Entrypoint<br/>[entrypoint.py]"]
  node_sourcecdk["Source CDK"]
  node_sources["Source Connectors"]
  node_destinations["Destination Connectors"]
end

subgraph group_data["Data Handling"]
  node_protocol["Airbyte Protocol"]
  node_normalization["Schema Normalization"]
end

subgraph group_support["Persistence And Services"]
  node_config["Config Repository"]
  node_jobdb[("Job Persistence")]
  node_tracking["Usage Tracking"]
end

node_user(("Airbyte User"))
node_warehouse[("Warehouse Or Other Destination")]
node_sourceapp[("Source Application Or Database")]

node_user -->|"configures sync"| node_webapp
node_webapp -->|"renders routes"| node_routes
node_routes -.->|"requests platform"| node_server
node_server -.->|"reads configuration"| node_config
node_server -.->|"submits jobs"| node_scheduler
node_scheduler -->|"submits workflows"| node_temporal
node_temporal -.->|"runs sync"| node_worker
node_worker -.->|"uses utilities"| node_workerutils
node_worker -->|"reads source stream"| node_sourcecdk
node_worker -->|"sends records"| node_destinations
node_sources -->|"launches through"| node_entrypoint
node_entrypoint -->|"invokes source"| node_sourcecdk
node_sourceapp -.->|"provides records"| node_sources
node_sourcecdk -.->|"reads data"| node_sourceapp
node_destinations -.->|"writes records"| node_warehouse
node_worker -->|"transfers messages"| node_protocol
node_destinations -.->|"may normalize"| node_normalization
node_scheduler -.->|"tracks jobs"| node_jobdb
node_server -.->|"may report usage"| node_tracking

click node_webapp "https://github.com/heade/airbyte/blob/master/airbyte-webapp/src/App.tsx"
click node_routes "https://github.com/heade/airbyte/blob/master/airbyte-webapp/src/pages/routes.tsx"
click node_server "https://github.com/heade/airbyte/tree/master/airbyte-server/src/main/java/io/airbyte/server/handlers"
click node_config "https://github.com/heade/airbyte/blob/master/airbyte-config/persistence/src/main/java/io/airbyte/config/persistence/ConfigRepository.java"
click node_scheduler "https://github.com/heade/airbyte/blob/master/airbyte-scheduler/client/src/main/java/io/airbyte/scheduler/client/DefaultSynchronousSchedulerClient.java"
click node_temporal "https://github.com/heade/airbyte/blob/master/airbyte-workers/src/main/java/io/airbyte/workers/temporal/TemporalClient.java"
click node_worker "https://github.com/heade/airbyte/blob/master/airbyte-workers/src/main/java/io/airbyte/workers/DefaultReplicationWorker.java"
click node_workerutils "https://github.com/heade/airbyte/blob/master/airbyte-workers/src/main/java/io/airbyte/workers/WorkerUtils.java"
click node_entrypoint "https://github.com/heade/airbyte/blob/master/airbyte-cdk/python/airbyte_cdk/entrypoint.py"
click node_sourcecdk "https://github.com/heade/airbyte/tree/master/airbyte-cdk/python/airbyte_cdk/sources"
click node_sources "https://github.com/heade/airbyte/tree/master/airbyte-integrations/connectors"
click node_destinations "https://github.com/heade/airbyte/tree/master/airbyte-integrations/connectors"
click node_protocol "https://github.com/heade/airbyte/blob/master/airbyte-cdk/python/airbyte_cdk/models/airbyte_protocol.py"
click node_normalization "https://github.com/heade/airbyte/tree/master/airbyte-integrations/bases/base-normalization/normalization"
click node_jobdb "https://github.com/heade/airbyte/blob/master/airbyte-scheduler/persistence/src/main/java/io/airbyte/scheduler/persistence/JobPersistence.java"
click node_tracking "https://github.com/heade/airbyte/blob/master/airbyte-analytics/src/main/java/io/airbyte/analytics/TrackingClientSingleton.java"

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_webapp,node_routes,node_user toneBlue
class node_server,node_scheduler,node_temporal,node_warehouse,node_sourceapp toneAmber
class node_worker,node_workerutils,node_entrypoint,node_sourcecdk,node_sources,node_destinations toneMint
class node_protocol,node_normalization toneRose
class node_config,node_jobdb,node_tracking toneIndigo
```

## Components

### Configuration UI

- [Web Application](https://github.com/heade/airbyte/blob/master/airbyte-webapp/src/App.tsx): `airbyte-webapp/src/App.tsx`
- [UI Routes](https://github.com/heade/airbyte/blob/master/airbyte-webapp/src/pages/routes.tsx): `airbyte-webapp/src/pages/routes.tsx`

### Control Plane

- [Server Handlers](https://github.com/heade/airbyte/tree/master/airbyte-server/src/main/java/io/airbyte/server/handlers): `airbyte-server/src/main/java/io/airbyte/server/handlers`
- [Scheduler Client](https://github.com/heade/airbyte/blob/master/airbyte-scheduler/client/src/main/java/io/airbyte/scheduler/client/DefaultSynchronousSchedulerClient.java): `airbyte-scheduler/client/src/main/java/io/airbyte/scheduler/client/DefaultSynchronousSchedulerClient.java`
- [Temporal Jobs](https://github.com/heade/airbyte/blob/master/airbyte-workers/src/main/java/io/airbyte/workers/temporal/TemporalClient.java): `airbyte-workers/src/main/java/io/airbyte/workers/temporal/TemporalClient.java`

### Connector Runtime

- [Replication Worker](https://github.com/heade/airbyte/blob/master/airbyte-workers/src/main/java/io/airbyte/workers/DefaultReplicationWorker.java): `airbyte-workers/src/main/java/io/airbyte/workers/DefaultReplicationWorker.java`
- [Worker Utilities](https://github.com/heade/airbyte/blob/master/airbyte-workers/src/main/java/io/airbyte/workers/WorkerUtils.java): `airbyte-workers/src/main/java/io/airbyte/workers/WorkerUtils.java`
- [Connector Entrypoint](https://github.com/heade/airbyte/blob/master/airbyte-cdk/python/airbyte_cdk/entrypoint.py): `airbyte-cdk/python/airbyte_cdk/entrypoint.py`
- [Source CDK](https://github.com/heade/airbyte/tree/master/airbyte-cdk/python/airbyte_cdk/sources): `airbyte-cdk/python/airbyte_cdk/sources`
- [Source Connectors](https://github.com/heade/airbyte/tree/master/airbyte-integrations/connectors): `airbyte-integrations/connectors`
- [Destination Connectors](https://github.com/heade/airbyte/tree/master/airbyte-integrations/connectors): `airbyte-integrations/connectors`

### Data Handling

- [Airbyte Protocol](https://github.com/heade/airbyte/blob/master/airbyte-cdk/python/airbyte_cdk/models/airbyte_protocol.py): `airbyte-cdk/python/airbyte_cdk/models/airbyte_protocol.py`
- [Schema Normalization](https://github.com/heade/airbyte/tree/master/airbyte-integrations/bases/base-normalization/normalization): `airbyte-integrations/bases/base-normalization/normalization`

### Persistence And Services

- [Config Repository](https://github.com/heade/airbyte/blob/master/airbyte-config/persistence/src/main/java/io/airbyte/config/persistence/ConfigRepository.java): `airbyte-config/persistence/src/main/java/io/airbyte/config/persistence/ConfigRepository.java`
- [Job Persistence](https://github.com/heade/airbyte/blob/master/airbyte-scheduler/persistence/src/main/java/io/airbyte/scheduler/persistence/JobPersistence.java): `airbyte-scheduler/persistence/src/main/java/io/airbyte/scheduler/persistence/JobPersistence.java`
- [Usage Tracking](https://github.com/heade/airbyte/blob/master/airbyte-analytics/src/main/java/io/airbyte/analytics/TrackingClientSingleton.java): `airbyte-analytics/src/main/java/io/airbyte/analytics/TrackingClientSingleton.java`

### Other components

- **Airbyte User**
- **Warehouse Or Other Destination**
- **Source Application Or Database**

## Connections

- Airbyte User → Web Application: configures sync (evidence: `README.md`)
- Web Application → UI Routes: renders routes (evidence: `airbyte-webapp/src/App.tsx`)
- UI Routes → Server Handlers: requests platform
- Server Handlers → Config Repository: reads configuration (evidence: `airbyte-server/src/main/java/io/airbyte/server/handlers/SchedulerHandler.java`)
- Server Handlers → Scheduler Client: submits jobs
- Scheduler Client → Temporal Jobs: submits workflows (evidence: `airbyte-scheduler/client/src/main/java/io/airbyte/scheduler/client/DefaultSynchronousSchedulerClient.java`)
- Temporal Jobs → Replication Worker: runs sync
- Replication Worker → Worker Utilities: uses utilities (evidence: `airbyte-workers/src/main/java/io/airbyte/workers/DefaultReplicationWorker.java`)
- Replication Worker → Source CDK: reads source stream (evidence: `airbyte-workers/src/main/java/io/airbyte/workers/DefaultReplicationWorker.java`)
- Replication Worker → Destination Connectors: sends records (evidence: `airbyte-workers/src/main/java/io/airbyte/workers/DefaultReplicationWorker.java`)
- Source Connectors → Connector Entrypoint: launches through (evidence: `airbyte-integrations/connectors/source-amazon-seller-partner/main.py`)
- Connector Entrypoint → Source CDK: invokes source (evidence: `airbyte-cdk/python/airbyte_cdk/entrypoint.py`)
- Source Application Or Database → Source Connectors: provides records
- Source CDK → Source Application Or Database: reads data
- Destination Connectors → Warehouse Or Other Destination: writes records
- Replication Worker → Airbyte Protocol: transfers messages (evidence: `airbyte-workers/src/main/java/io/airbyte/workers/DefaultReplicationWorker.java`)
- Destination Connectors → Schema Normalization: may normalize
- Scheduler Client → Job Persistence: tracks jobs
- Server Handlers → Usage Tracking: may report usage
