# airbnb/viaduct architecture

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

- Interactive diagram: https://gitdiagram.com/airbnb/viaduct
- Repository: https://github.com/airbnb/viaduct
- Video tour (about a minute): https://gitdiagram.com/airbnb/viaduct/video

## Overview

Viaduct is a GraphQL data-access engine that brings a unified schema and hosted business logic behind one request interface. A client operation enters the engine, is planned and executed, and field resolvers supply the data used to build the response. Tenant code can re-enter the engine with queries or mutations, composing hosted logic; Java and remote-resolver bridges extend that execution model. The tree and excerpts support the engine, context, selection-set, registry, and bridge components shown here. Some registry and execution wiring is inferred from module roles rather than sampled implementation.

Main entry points: [`core/tenant/runtime/src/main/kotlin/viaduct/tenant/runtime/context/EngineExecutionContextWrapper.kt`](https://github.com/airbnb/viaduct/blob/main/core/tenant/runtime/src/main/kotlin/viaduct/tenant/runtime/context/EngineExecutionContextWrapper.kt) (Tenant context), [`core/engine/wiring/src/main/kotlin/viaduct/engine/EngineImpl.kt`](https://github.com/airbnb/viaduct/blob/main/core/engine/wiring/src/main/kotlin/viaduct/engine/EngineImpl.kt) (Engine entry), [`core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/ViaductExecutionStrategy.kt`](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/ViaductExecutionStrategy.kt) (Execution strategy), [`core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/EngineExecutionContextImpl.kt`](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/EngineExecutionContextImpl.kt) (Execution context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_schema["Schema and API"]
  node_registry["Engine registry<br/>[EngineRegistry.kt]"]
  node_engine_api["Engine API<br/>[Engine.kt]"]
  node_selection_api["Selection sets"]
end

subgraph group_execution["Query execution"]
  node_engine["Engine entry<br/>[EngineImpl.kt]"]
  node_query_plan["Query planning"]
  node_execution_strategy["Execution strategy"]
  node_selection_runtime["Selection processing"]
  node_resolver_dispatch["Resolver dispatch"]
  node_resolver_fetch["Resolver fetch"]
  node_result["Execution result"]
end

subgraph group_tenant["Tenant integration"]
  node_tenant_context["Tenant context"]
  node_execution_context["Execution context"]
  node_tenant_logic["Hosted resolver logic"]
end

subgraph group_extensions["Instrumentation and bridges"]
  node_instrumentation["Resolver instrumentation"]
  node_java_bridge["Java API bridge"]
  node_remote_context["Remote resolver context"]
end

node_client(("GraphQL client"))
node_remote_service["Remote callback service"]

node_client -->|"submits operation"| node_engine
node_registry -->|"creates engine"| node_engine
node_engine -->|"builds plan"| node_query_plan
node_engine -->|"executes operation"| node_execution_strategy
node_query_plan -->|"plans selections"| node_selection_runtime
node_execution_strategy -->|"dispatches fields"| node_resolver_dispatch
node_resolver_dispatch -->|"fetches resolver"| node_resolver_fetch
node_resolver_fetch -->|"invokes resolver"| node_tenant_logic
node_execution_strategy -->|"completes response"| node_result
node_tenant_context -->|"uses context"| node_execution_context
node_tenant_context -->|"constructs selections"| node_selection_api
node_tenant_context -->|"resolves subqueries"| node_engine_api
node_tenant_logic -.->|"issues subquery"| node_tenant_context
node_instrumentation -->|"wraps execution"| node_execution_context
node_java_bridge -->|"delegates API calls"| node_execution_context
node_remote_context -.->|"executes remotely"| node_remote_service

click node_registry "https://github.com/airbnb/viaduct/blob/main/core/service/runtime/src/main/kotlin/viaduct/service/runtime/EngineRegistry.kt"
click node_engine_api "https://github.com/airbnb/viaduct/blob/main/core/engine/api/src/main/kotlin/viaduct/engine/api/Engine.kt"
click node_selection_api "https://github.com/airbnb/viaduct/blob/main/core/engine/api/src/main/kotlin/viaduct/engine/api/EngineSelectionSet.kt"
click node_engine "https://github.com/airbnb/viaduct/blob/main/core/engine/wiring/src/main/kotlin/viaduct/engine/EngineImpl.kt"
click node_query_plan "https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/QueryPlanFactory.kt"
click node_execution_strategy "https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/ViaductExecutionStrategy.kt"
click node_selection_runtime "https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/select/EngineSelectionSetImpl.kt"
click node_resolver_dispatch "https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/FieldResolverDispatcherImpl.kt"
click node_resolver_fetch "https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/ResolverDataFetcher.kt"
click node_result "https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/result/ObjectEngineResult.kt"
click node_tenant_context "https://github.com/airbnb/viaduct/blob/main/core/tenant/runtime/src/main/kotlin/viaduct/tenant/runtime/context/EngineExecutionContextWrapper.kt"
click node_execution_context "https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/EngineExecutionContextImpl.kt"
click node_instrumentation "https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/instrumentation/resolver/InstrumentedEngineExecutionContext.kt"
click node_java_bridge "https://github.com/airbnb/viaduct/blob/main/core/x/javaapi/runtime/src/main/kotlin/viaduct/java/runtime/bridge/JavaEngineContextDelegate.kt"
click node_remote_context "https://github.com/airbnb/viaduct/blob/main/core/x/remoteresolvers/lib/src/main/kotlin/viaduct/remote/RemoteEngineExecutionContext.kt"

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_registry,node_engine_api,node_selection_api,node_client toneBlue
class node_engine,node_query_plan,node_execution_strategy,node_selection_runtime,node_resolver_dispatch,node_resolver_fetch,node_result toneAmber
class node_tenant_context,node_execution_context,node_tenant_logic toneMint
class node_instrumentation,node_java_bridge,node_remote_context toneRose
class node_remote_service toneIndigo
```

## Components

### Schema and API

- [Engine registry](https://github.com/airbnb/viaduct/blob/main/core/service/runtime/src/main/kotlin/viaduct/service/runtime/EngineRegistry.kt): `core/service/runtime/src/main/kotlin/viaduct/service/runtime/EngineRegistry.kt`
- [Engine API](https://github.com/airbnb/viaduct/blob/main/core/engine/api/src/main/kotlin/viaduct/engine/api/Engine.kt): `core/engine/api/src/main/kotlin/viaduct/engine/api/Engine.kt`
- [Selection sets](https://github.com/airbnb/viaduct/blob/main/core/engine/api/src/main/kotlin/viaduct/engine/api/EngineSelectionSet.kt): `core/engine/api/src/main/kotlin/viaduct/engine/api/EngineSelectionSet.kt`

### Query execution

- [Engine entry](https://github.com/airbnb/viaduct/blob/main/core/engine/wiring/src/main/kotlin/viaduct/engine/EngineImpl.kt): `core/engine/wiring/src/main/kotlin/viaduct/engine/EngineImpl.kt`
- [Query planning](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/QueryPlanFactory.kt): `core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/QueryPlanFactory.kt`
- [Execution strategy](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/ViaductExecutionStrategy.kt): `core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/ViaductExecutionStrategy.kt`
- [Selection processing](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/select/EngineSelectionSetImpl.kt): `core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/select/EngineSelectionSetImpl.kt`
- [Resolver dispatch](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/FieldResolverDispatcherImpl.kt): `core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/FieldResolverDispatcherImpl.kt`
- [Resolver fetch](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/ResolverDataFetcher.kt): `core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/execution/ResolverDataFetcher.kt`
- [Execution result](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/result/ObjectEngineResult.kt): `core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/result/ObjectEngineResult.kt`

### Tenant integration

- [Tenant context](https://github.com/airbnb/viaduct/blob/main/core/tenant/runtime/src/main/kotlin/viaduct/tenant/runtime/context/EngineExecutionContextWrapper.kt): `core/tenant/runtime/src/main/kotlin/viaduct/tenant/runtime/context/EngineExecutionContextWrapper.kt`
- [Execution context](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/EngineExecutionContextImpl.kt): `core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/EngineExecutionContextImpl.kt`
- **Hosted resolver logic**

### Instrumentation and bridges

- [Resolver instrumentation](https://github.com/airbnb/viaduct/blob/main/core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/instrumentation/resolver/InstrumentedEngineExecutionContext.kt): `core/engine/runtime/src/main/kotlin/viaduct/engine/runtime/instrumentation/resolver/InstrumentedEngineExecutionContext.kt`
- [Java API bridge](https://github.com/airbnb/viaduct/blob/main/core/x/javaapi/runtime/src/main/kotlin/viaduct/java/runtime/bridge/JavaEngineContextDelegate.kt): `core/x/javaapi/runtime/src/main/kotlin/viaduct/java/runtime/bridge/JavaEngineContextDelegate.kt`
- [Remote resolver context](https://github.com/airbnb/viaduct/blob/main/core/x/remoteresolvers/lib/src/main/kotlin/viaduct/remote/RemoteEngineExecutionContext.kt): `core/x/remoteresolvers/lib/src/main/kotlin/viaduct/remote/RemoteEngineExecutionContext.kt`

### Other components

- **GraphQL client**
- **Remote callback service**

## Connections

- GraphQL client → Engine entry: submits operation
- Engine registry → Engine entry: creates engine
- Engine entry → Query planning: builds plan
- Engine entry → Execution strategy: executes operation
- Query planning → Selection processing: plans selections
- Execution strategy → Resolver dispatch: dispatches fields
- Resolver dispatch → Resolver fetch: fetches resolver
- Resolver fetch → Hosted resolver logic: invokes resolver
- Execution strategy → Execution result: completes response
- Tenant context → Execution context: uses context
- Tenant context → Selection sets: constructs selections
- Tenant context → Engine API: resolves subqueries
- Hosted resolver logic → Tenant context: issues subquery
- Resolver instrumentation → Execution context: wraps execution
- Java API bridge → Execution context: delegates API calls
- Remote resolver context → Remote callback service: executes remotely