# ktorio/ktor architecture

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

- Interactive diagram: https://gitdiagram.com/ktorio/ktor
- Repository: https://github.com/ktorio/ktor

## Overview

Ktor is a Kotlin asynchronous framework for building HTTP services and clients. The documented server workflow is application setup and feature installation, request routing and handling, then a response served by an embedded or container engine. The tree also shows client engines, networking, WebSockets/SSE, sessions, and a test host as distinct capabilities. Several connections beyond the README workflow are uncertain because most implementation files were not sampled; those links are omitted or marked unverified rather than inferred from names alone.

Main entry points: [`ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClient.kt`](https://github.com/ktorio/ktor/blob/main/ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClient.kt) (HTTP client), [`ktor-server/ktor-server-core/common/src/io/ktor/server/engine/BaseApplicationEngine.kt`](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/BaseApplicationEngine.kt) (Base engine), [`ktor-server/ktor-server-core/common/src/io/ktor/server/application/Application.kt`](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/application/Application.kt) (Application), [`ktor-server/ktor-server-core/common/src/io/ktor/server/engine/EnginePipeline.kt`](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/EnginePipeline.kt) (Engine pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server runtime"]
  node_application["Application<br/>[Application.kt]"]
  node_embedded["Embedded server<br/>[EmbeddedServer.kt]"]
  node_engine["Engine API"]
  node_baseengine["Base engine"]
  node_enginepipeline["Engine pipeline<br/>[EnginePipeline.kt]"]
  node_netty["Netty host"]
  node_servlet["Servlet host"]
  node_routing["Routing"]
  node_request["Request handling<br/>[PipelineRequest.kt]"]
  node_response["Response handling"]
end

subgraph group_protocol["HTTP and networking"]
  node_status["HTTP statuses<br/>[HttpStatusCode.kt]"]
  node_headers["HTTP headers<br/>[HttpHeaders.kt]"]
  node_network["Network sockets<br/>[SocketEngine.kt]"]
  node_pipeline["Coroutine pipeline<br/>[PipelineContext.kt]"]
end

subgraph group_client["Client runtime"]
  node_client["HTTP client<br/>[HttpClient.kt]"]
  node_clientengines["Client engines<br/>[CIOEngine.kt]"]
  node_clientplugins["Client plugins"]
end

subgraph group_extensions["Protocols and extensions"]
  node_websocket["WebSockets<br/>[WebSockets.kt]"]
  node_sse["Server-sent events<br/>[SSE.kt]"]
  node_sessions["Sessions<br/>[SessionStorage.kt]"]
end

subgraph group_testing["Testing"]
  node_testhost["Test application host"]
end

node_developer(("Application developer"))

node_developer -->|"configures"| node_embedded
node_embedded -->|"creates"| node_application
node_embedded -.->|"starts"| node_engine
node_developer -->|"installs routes"| node_routing
node_routing -.->|"handles requests"| node_request
node_request -.->|"produces response"| node_response
node_response -->|"returns result"| node_developer
node_engine -.->|"implemented by"| node_baseengine
node_baseengine -->|"configures"| node_enginepipeline
node_netty -->|"hosts"| node_application
node_netty -->|"uses"| node_enginepipeline
node_servlet -->|"hosts"| node_application
node_servlet -->|"uses"| node_enginepipeline
node_baseengine -->|"selects fallback"| node_status
node_baseengine -->|"checks host header"| node_headers
node_enginepipeline -.->|"uses execution model"| node_pipeline
node_developer -.->|"makes HTTP calls"| node_client
node_client -.->|"dispatches requests"| node_clientengines
node_client -.->|"installs plugins"| node_clientplugins
node_client -.->|"opens sessions"| node_websocket
node_client -.->|"opens streams"| node_sse
node_application -.->|"can install"| node_sessions
node_developer -->|"tests application"| node_testhost

click node_application "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/application/Application.kt"
click node_embedded "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/EmbeddedServer.kt"
click node_engine "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/ApplicationEngine.kt"
click node_baseengine "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/BaseApplicationEngine.kt"
click node_enginepipeline "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/EnginePipeline.kt"
click node_netty "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-netty/jvm/src/io/ktor/server/netty/NettyApplicationEngine.kt"
click node_servlet "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-servlet/jvm/src/io/ktor/server/servlet/ServletApplicationEngine.kt"
click node_routing "https://github.com/ktorio/ktor/tree/main/ktor-server/ktor-server-core/common/src/io/ktor/server/routing"
click node_request "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/request/PipelineRequest.kt"
click node_response "https://github.com/ktorio/ktor/tree/main/ktor-server/ktor-server-core/common/src/io/ktor/server/response"
click node_status "https://github.com/ktorio/ktor/blob/main/ktor-http/common/src/io/ktor/http/HttpStatusCode.kt"
click node_headers "https://github.com/ktorio/ktor/blob/main/ktor-http/common/src/io/ktor/http/HttpHeaders.kt"
click node_network "https://github.com/ktorio/ktor/blob/main/ktor-network/common/src/io/ktor/network/sockets/SocketEngine.kt"
click node_client "https://github.com/ktorio/ktor/blob/main/ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClient.kt"
click node_clientengines "https://github.com/ktorio/ktor/blob/main/ktor-client/ktor-client-cio/common/src/io/ktor/client/engine/cio/CIOEngine.kt"
click node_clientplugins "https://github.com/ktorio/ktor/tree/main/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins"
click node_websocket "https://github.com/ktorio/ktor/blob/main/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/websocket/WebSockets.kt"
click node_sse "https://github.com/ktorio/ktor/blob/main/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/sse/SSE.kt"
click node_sessions "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/SessionStorage.kt"
click node_testhost "https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-test-host/common/src/io/ktor/server/testing/TestApplicationEngine.kt"
click node_pipeline "https://github.com/ktorio/ktor/blob/main/ktor-utils/common/src/io/ktor/util/pipeline/PipelineContext.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_application,node_embedded,node_engine,node_baseengine,node_enginepipeline,node_netty,node_servlet,node_routing,node_request,node_response toneBlue
class node_status,node_headers,node_network,node_pipeline toneAmber
class node_client,node_clientengines,node_clientplugins toneMint
class node_websocket,node_sse,node_sessions toneRose
class node_testhost,node_developer toneIndigo
```

## Components

### Server runtime

- [Application](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/application/Application.kt): `ktor-server/ktor-server-core/common/src/io/ktor/server/application/Application.kt`
- [Embedded server](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/EmbeddedServer.kt): `ktor-server/ktor-server-core/common/src/io/ktor/server/engine/EmbeddedServer.kt`
- [Engine API](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/ApplicationEngine.kt): `ktor-server/ktor-server-core/common/src/io/ktor/server/engine/ApplicationEngine.kt`
- [Base engine](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/BaseApplicationEngine.kt): `ktor-server/ktor-server-core/common/src/io/ktor/server/engine/BaseApplicationEngine.kt`
- [Engine pipeline](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/engine/EnginePipeline.kt): `ktor-server/ktor-server-core/common/src/io/ktor/server/engine/EnginePipeline.kt`
- [Netty host](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-netty/jvm/src/io/ktor/server/netty/NettyApplicationEngine.kt): `ktor-server/ktor-server-netty/jvm/src/io/ktor/server/netty/NettyApplicationEngine.kt`
- [Servlet host](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-servlet/jvm/src/io/ktor/server/servlet/ServletApplicationEngine.kt): `ktor-server/ktor-server-servlet/jvm/src/io/ktor/server/servlet/ServletApplicationEngine.kt`
- [Routing](https://github.com/ktorio/ktor/tree/main/ktor-server/ktor-server-core/common/src/io/ktor/server/routing): `ktor-server/ktor-server-core/common/src/io/ktor/server/routing`
- [Request handling](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-core/common/src/io/ktor/server/request/PipelineRequest.kt): `ktor-server/ktor-server-core/common/src/io/ktor/server/request/PipelineRequest.kt`
- [Response handling](https://github.com/ktorio/ktor/tree/main/ktor-server/ktor-server-core/common/src/io/ktor/server/response): `ktor-server/ktor-server-core/common/src/io/ktor/server/response`

### HTTP and networking

- [HTTP statuses](https://github.com/ktorio/ktor/blob/main/ktor-http/common/src/io/ktor/http/HttpStatusCode.kt): `ktor-http/common/src/io/ktor/http/HttpStatusCode.kt`
- [HTTP headers](https://github.com/ktorio/ktor/blob/main/ktor-http/common/src/io/ktor/http/HttpHeaders.kt): `ktor-http/common/src/io/ktor/http/HttpHeaders.kt`
- [Network sockets](https://github.com/ktorio/ktor/blob/main/ktor-network/common/src/io/ktor/network/sockets/SocketEngine.kt): `ktor-network/common/src/io/ktor/network/sockets/SocketEngine.kt`
- [Coroutine pipeline](https://github.com/ktorio/ktor/blob/main/ktor-utils/common/src/io/ktor/util/pipeline/PipelineContext.kt): `ktor-utils/common/src/io/ktor/util/pipeline/PipelineContext.kt`

### Client runtime

- [HTTP client](https://github.com/ktorio/ktor/blob/main/ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClient.kt): `ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClient.kt`
- [Client engines](https://github.com/ktorio/ktor/blob/main/ktor-client/ktor-client-cio/common/src/io/ktor/client/engine/cio/CIOEngine.kt): `ktor-client/ktor-client-cio/common/src/io/ktor/client/engine/cio/CIOEngine.kt`
- [Client plugins](https://github.com/ktorio/ktor/tree/main/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins): `ktor-client/ktor-client-core/common/src/io/ktor/client/plugins`

### Protocols and extensions

- [WebSockets](https://github.com/ktorio/ktor/blob/main/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/websocket/WebSockets.kt): `ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/websocket/WebSockets.kt`
- [Server-sent events](https://github.com/ktorio/ktor/blob/main/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/sse/SSE.kt): `ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/sse/SSE.kt`
- [Sessions](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/SessionStorage.kt): `ktor-server/ktor-server-plugins/ktor-server-sessions/common/src/io/ktor/server/sessions/SessionStorage.kt`

### Testing

- [Test application host](https://github.com/ktorio/ktor/blob/main/ktor-server/ktor-server-test-host/common/src/io/ktor/server/testing/TestApplicationEngine.kt): `ktor-server/ktor-server-test-host/common/src/io/ktor/server/testing/TestApplicationEngine.kt`

### Other components

- **Application developer**

## Connections

- Application developer → Embedded server: configures
- Embedded server → Application: creates
- Embedded server → Engine API: starts
- Application developer → Routing: installs routes
- Routing → Request handling: handles requests
- Request handling → Response handling: produces response
- Response handling → Application developer: returns result
- Engine API → Base engine: implemented by (evidence: `ktor-server/ktor-server-core/common/src/io/ktor/server/engine/BaseApplicationEngine.kt`)
- Base engine → Engine pipeline: configures (evidence: `ktor-server/ktor-server-core/common/src/io/ktor/server/engine/BaseApplicationEngine.kt`)
- Netty host → Application: hosts (evidence: `ktor-server/ktor-server-netty/jvm/src/io/ktor/server/netty/NettyApplicationEngine.kt`)
- Netty host → Engine pipeline: uses (evidence: `ktor-server/ktor-server-netty/jvm/src/io/ktor/server/netty/NettyApplicationEngine.kt`)
- Servlet host → Application: hosts (evidence: `ktor-server/ktor-server-servlet/jvm/src/io/ktor/server/servlet/ServletApplicationEngine.kt`)
- Servlet host → Engine pipeline: uses (evidence: `ktor-server/ktor-server-servlet/jvm/src/io/ktor/server/servlet/ServletApplicationEngine.kt`)
- Base engine → HTTP statuses: selects fallback (evidence: `ktor-server/ktor-server-core/common/src/io/ktor/server/engine/BaseApplicationEngine.kt`)
- Base engine → HTTP headers: checks host header (evidence: `ktor-server/ktor-server-core/common/src/io/ktor/server/engine/BaseApplicationEngine.kt`)
- Engine pipeline → Coroutine pipeline: uses execution model
- Application developer → HTTP client: makes HTTP calls
- HTTP client → Client engines: dispatches requests
- HTTP client → Client plugins: installs plugins
- HTTP client → WebSockets: opens sessions
- HTTP client → Server-sent events: opens streams
- Application → Sessions: can install
- Application developer → Test application host: tests application
