# oven-sh/bun architecture

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

- Interactive diagram: https://gitdiagram.com/oven-sh/bun
- Repository: https://github.com/oven-sh/bun

## Overview

Bun is a single-executable JavaScript/TypeScript toolkit: its principal user workflow is invoking `bun` to run an app or script, with built-in package management, bundling, and testing as major companion capabilities. The graph combines README-documented product flows with source-indexed implementation areas. Several capabilities are documented but their runtime wiring was not sampled, so those links are cited to the README rather than presented as source-verified calls.

Main entry points: [`src/jsc/GarbageCollectionController.rs`](https://github.com/oven-sh/bun/blob/main/src/jsc/GarbageCollectionController.rs) (JS runtime), [`src/bun.js.rs`](https://github.com/oven-sh/bun/blob/main/src/bun.js.rs) (Bun executable), [`src/bundler/bundle_v2.rs`](https://github.com/oven-sh/bun/blob/main/src/bundler/bundle_v2.rs) (Bundler), [`packages/bun-uws/src/HttpContext.h`](https://github.com/oven-sh/bun/blob/main/packages/bun-uws/src/HttpContext.h) (HTTP handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and runtime"]
  node_bun["Bun executable<br/>[bun.js.rs]"]
  node_runtime["JS runtime"]
  node_config["Runtime config<br/>[bunfig.rs]"]
end

subgraph group_language["Language processing"]
  node_ast["AST and syntax<br/>[e.rs]"]
  node_resolver["Module resolution<br/>[lib.rs]"]
  node_transpiler["Transpilation<br/>[transpiler.rs]"]
end

subgraph group_tooling["Developer tools"]
  node_bundler["Bundler<br/>[bundle_v2.rs]"]
  node_test["Test runner"]
  node_package_cli["Package commands"]
  node_installer["Package installer<br/>[PackageManager.rs]"]
end

subgraph group_services["Runtime services"]
  node_server["HTTP server<br/>[App.h]"]
  node_http_context["HTTP handling<br/>[HttpContext.h]"]
  node_http_response["HTTP responses<br/>[HttpResponse.h]"]
  node_websocket["WebSockets<br/>[WebSocket.h]"]
  node_fetch["HTTP client<br/>[ClientSession.rs]"]
  node_streams["Web streams"]
  node_sys["System calls<br/>[lib.rs]"]
end

node_developer(("Developer"))

node_developer -->|"invokes"| node_bun
node_bun -->|"runs scripts"| node_runtime
node_bun -->|"dispatches commands"| node_package_cli
node_package_cli -.->|"installs packages"| node_installer
node_bun -->|"bundles apps"| node_bundler
node_bun -->|"runs tests"| node_test
node_runtime -.->|"uses configuration"| node_config
node_runtime -.->|"processes source"| node_ast
node_ast -.->|"resolves imports"| node_resolver
node_bundler -.->|"transforms syntax"| node_ast
node_bundler -.->|"resolves modules"| node_resolver
node_bundler -.->|"transpiles modules"| node_transpiler
node_runtime -->|"offers server API"| node_server
node_server -->|"registers routes"| node_http_context
node_http_context -->|"writes responses"| node_http_response
node_http_context -.->|"upgrades connections"| node_websocket
node_runtime -->|"provides fetch"| node_fetch
node_runtime -->|"provides streams"| node_streams
node_runtime -.->|"uses system calls"| node_sys

click node_bun "https://github.com/oven-sh/bun/blob/main/src/bun.js.rs"
click node_runtime "https://github.com/oven-sh/bun/blob/main/src/jsc/GarbageCollectionController.rs"
click node_config "https://github.com/oven-sh/bun/blob/main/src/bunfig/bunfig.rs"
click node_ast "https://github.com/oven-sh/bun/blob/main/src/ast/e.rs"
click node_resolver "https://github.com/oven-sh/bun/blob/main/src/resolver/lib.rs"
click node_transpiler "https://github.com/oven-sh/bun/blob/main/src/bundler/transpiler.rs"
click node_bundler "https://github.com/oven-sh/bun/blob/main/src/bundler/bundle_v2.rs"
click node_test "https://github.com/oven-sh/bun/tree/main/src/runtime"
click node_package_cli "https://github.com/oven-sh/bun/blob/main/src/runtime/cli/package_manager_command.rs"
click node_installer "https://github.com/oven-sh/bun/blob/main/src/install/PackageManager.rs"
click node_server "https://github.com/oven-sh/bun/blob/main/packages/bun-uws/src/App.h"
click node_http_context "https://github.com/oven-sh/bun/blob/main/packages/bun-uws/src/HttpContext.h"
click node_http_response "https://github.com/oven-sh/bun/blob/main/packages/bun-uws/src/HttpResponse.h"
click node_websocket "https://github.com/oven-sh/bun/blob/main/packages/bun-uws/src/WebSocket.h"
click node_fetch "https://github.com/oven-sh/bun/blob/main/src/http/h2_client/ClientSession.rs"
click node_streams "https://github.com/oven-sh/bun/blob/main/src/jsc/bindings/webcore/streams/JSReadableByteStreamController.cpp"
click node_sys "https://github.com/oven-sh/bun/blob/main/src/sys/lib.rs"

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_bun,node_runtime,node_config toneBlue
class node_ast,node_resolver,node_transpiler toneAmber
class node_bundler,node_test,node_package_cli,node_installer toneMint
class node_server,node_http_context,node_http_response,node_websocket,node_fetch,node_streams,node_sys toneRose
class node_developer toneIndigo
```

## Components

### CLI and runtime

- [Bun executable](https://github.com/oven-sh/bun/blob/main/src/bun.js.rs): `src/bun.js.rs`
- [JS runtime](https://github.com/oven-sh/bun/blob/main/src/jsc/GarbageCollectionController.rs): `src/jsc/GarbageCollectionController.rs`
- [Runtime config](https://github.com/oven-sh/bun/blob/main/src/bunfig/bunfig.rs): `src/bunfig/bunfig.rs`

### Language processing

- [AST and syntax](https://github.com/oven-sh/bun/blob/main/src/ast/e.rs): `src/ast/e.rs`
- [Module resolution](https://github.com/oven-sh/bun/blob/main/src/resolver/lib.rs): `src/resolver/lib.rs`
- [Transpilation](https://github.com/oven-sh/bun/blob/main/src/bundler/transpiler.rs): `src/bundler/transpiler.rs`

### Developer tools

- [Bundler](https://github.com/oven-sh/bun/blob/main/src/bundler/bundle_v2.rs): `src/bundler/bundle_v2.rs`
- [Test runner](https://github.com/oven-sh/bun/tree/main/src/runtime): `src/runtime`
- [Package commands](https://github.com/oven-sh/bun/blob/main/src/runtime/cli/package_manager_command.rs): `src/runtime/cli/package_manager_command.rs`
- [Package installer](https://github.com/oven-sh/bun/blob/main/src/install/PackageManager.rs): `src/install/PackageManager.rs`

### Runtime services

- [HTTP server](https://github.com/oven-sh/bun/blob/main/packages/bun-uws/src/App.h): `packages/bun-uws/src/App.h`
- [HTTP handling](https://github.com/oven-sh/bun/blob/main/packages/bun-uws/src/HttpContext.h): `packages/bun-uws/src/HttpContext.h`
- [HTTP responses](https://github.com/oven-sh/bun/blob/main/packages/bun-uws/src/HttpResponse.h): `packages/bun-uws/src/HttpResponse.h`
- [WebSockets](https://github.com/oven-sh/bun/blob/main/packages/bun-uws/src/WebSocket.h): `packages/bun-uws/src/WebSocket.h`
- [HTTP client](https://github.com/oven-sh/bun/blob/main/src/http/h2_client/ClientSession.rs): `src/http/h2_client/ClientSession.rs`
- [Web streams](https://github.com/oven-sh/bun/blob/main/src/jsc/bindings/webcore/streams/JSReadableByteStreamController.cpp): `src/jsc/bindings/webcore/streams/JSReadableByteStreamController.cpp`
- [System calls](https://github.com/oven-sh/bun/blob/main/src/sys/lib.rs): `src/sys/lib.rs`

### Other components

- **Developer**

## Connections

- Developer → Bun executable: invokes (evidence: `README.md`)
- Bun executable → JS runtime: runs scripts (evidence: `README.md`)
- Bun executable → Package commands: dispatches commands (evidence: `README.md`)
- Package commands → Package installer: installs packages (evidence: `README.md`)
- Bun executable → Bundler: bundles apps (evidence: `README.md`)
- Bun executable → Test runner: runs tests (evidence: `README.md`)
- JS runtime → Runtime config: uses configuration
- JS runtime → AST and syntax: processes source
- AST and syntax → Module resolution: resolves imports
- Bundler → AST and syntax: transforms syntax
- Bundler → Module resolution: resolves modules
- Bundler → Transpilation: transpiles modules
- JS runtime → HTTP server: offers server API (evidence: `README.md`)
- HTTP server → HTTP handling: registers routes (evidence: `packages/bun-uws/src/App.h`)
- HTTP handling → HTTP responses: writes responses (evidence: `packages/bun-uws/src/HttpContext.h`)
- HTTP handling → WebSockets: upgrades connections (evidence: `packages/bun-uws/src/HttpContext.h`)
- JS runtime → HTTP client: provides fetch (evidence: `README.md`)
- JS runtime → Web streams: provides streams (evidence: `README.md`)
- JS runtime → System calls: uses system calls