# withastro/flue architecture

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

- Interactive diagram: https://gitdiagram.com/withastro/flue
- Repository: https://github.com/withastro/flue

## Overview

1. This is a TypeScript monorepo for an agent-harness framework, not a single app. The center of gravity is `packages/runtime`, with surrounding packages for deployment targets, integrations, persistence, UI helpers, and examples. `apps/docs` and `apps/www` are the public documentation/marketing surfaces.

2. The main product layer is `@flue/runtime`. It defines agents, sessions, workflows, tools, skills, sandboxes, routing, durable execution, event streaming, and persistence contracts. Architecturally, this is the engine that turns an incoming request or event into a long-lived agent run, records progress, and rehydrates state after restarts.

3. Runtime execution is split by environment. `packages/runtime/src/node` provides local Node.js execution, while `packages/runtime/src/cloudflare` adds Cloudflare Workers-specific coordination, registry, gateway, sandbox, and model/provider plumbing. The repo is built to support both local development and hosted execution with the same conceptual API.

4. Agent flow is: external input enters through an HTTP route or channel webhook, runtime resolves the agent definition, then the agent executes with instructions, tools, skills, and a sandbox. During the run, the runtime emits events, stores run/session state, and can stream chunks/results back to callers. Durable execution is a first-class boundary, so accepted work survives process interruption.

5. `packages/sdk` is the consumer-facing client layer for invoking deployed agents and workflows over HTTP/streaming. It is separate from the runtime so external applications can call Flue deployments without embedding the harness itself.

6. `packages/cli` is the local orchestration and build boundary. It provides the `flue` binary, config loading, build/dev commands, blueprint generation, and Cloudflare/Node-specific build plugins. In practice, the CLI is how projects are initialized, run locally, and packaged for deployment.

7. Integrations are organized as small, focused packages under `packages/*` for channels and external services. Channel packages such as Slack, Discord, GitHub, Teams, Telegram, WhatsApp, Twilio, Zendesk, Intercom, Linear, Notion, Stripe, Shopify, Resend, Google Chat, and Salesforce Marketing Cloud expose verified webhook/event entry points and service-specific route helpers.

8. Persistence is abstracted behind adapter packages. There are dedicated packages for Postgres, MongoDB, MySQL, Redis, LibSQL, and SQLite-compatible backends, each mapping runtime concepts like runs, sessions, event streams, submissions, and chunks onto the underlying store. This lets the same agent model run with different durability and deployment constraints.

9. `packages/react` is a separate UI-state integration layer for React applications. It provides hooks, reducers, session/workflow state, and a provider so a frontend can observe and control agent or workflow runs without owning the runtime itself.

10. The `apps/docs` site is the canonical architecture and reference surface. It mirrors the product structure: guides, CLI docs, SDK docs, API references, ecosystem pages, and per-channel/per-database/per-deploy documentation. `apps/www` is the marketing and landing site, with blog and example pages.

11. The `examples/` directory is effectively an architecture catalog. Each example demonstrates one integration pattern or deployment topology: agent-only, chat SDK, channel webhooks, sandbox usage, workflow composition, observability, React UI, and external service connectors. These are the best place to see end-to-end data flow through the framework.

12. Repository automation exists alongside the product code. `.github` contains contributor approval and PR redirect workflows, while `.flue`, `.agents`, and `.opencode` hold repo-specific automation and documentation-agent assets. These do not shape runtime behavior, but they support maintenance and content generation across the monorepo.

13. Build and verification are monorepo-wide and strongly package-scoped. Most packages have their own `tsdown` config and Vitest suites, with workerd-specific test variants where Cloudflare behavior matters. That split reflects the repo’s main boundary: shared abstractions in TypeScript, with environment-specific behavior isolated per target.

Main entry points: [`packages/runtime/src/runtime/run-store.ts`](https://github.com/withastro/flue/blob/main/packages/runtime/src/runtime/run-store.ts) (Run state), [`packages/runtime/src/index.ts`](https://github.com/withastro/flue/blob/main/packages/runtime/src/index.ts) (Runtime), [`packages/runtime/src/routing.ts`](https://github.com/withastro/flue/blob/main/packages/runtime/src/routing.ts) (Routing), [`packages/sdk/src/client.ts`](https://github.com/withastro/flue/blob/main/packages/sdk/src/client.ts) (SDK client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Runtime engine"]
  node_runtime_index["Runtime<br/>engine entry<br/>[index.ts]"]
  node_runtime_dispatch["Dispatch<br/>execution flow<br/>[dispatch.ts]"]
  node_runtime_handle_agent["Agent run<br/>[handle-agent.ts]"]
  node_runtime_streams["Streaming<br/>event stream"]
  node_runtime_store[("Run state<br/>durability core<br/>[run-store.ts]")]
  node_runtime_routing["Routing<br/>[routing.ts]"]
end

subgraph group_targets["Execution targets"]
  node_node_runtime["Node runtime<br/>node target<br/>[index.ts]"]
  node_cf_runtime["Cloudflare runtime<br/>cloudflare target<br/>[index.ts]"]
end

subgraph group_ecosystem["Integrations"]
  node_slack_channel["Slack<br/>channel routes<br/>[routes.ts]"]
  node_github_channel["GitHub<br/>webhook channel<br/>[webhook.ts]"]
  node_google_chat_channel["Google Chat<br/>channel routes<br/>[routes.ts]"]
end

subgraph group_storage["Persistence"]
  node_postgres_adapter[("Postgres<br/>sql adapter")]
  node_redis_adapter[("Redis<br/>kv adapter<br/>[redis-adapter.ts]")]
  node_mongodb_adapter[("MongoDB<br/>document adapter<br/>[mongodb-adapter.ts]")]
end

subgraph group_surfaces["Surfaces and examples"]
  node_sdk_client["SDK client<br/>http client<br/>[client.ts]"]
  node_cli_bin["Flue CLI<br/>orchestration CLI<br/>[flue.ts]"]
  node_cli_build["Build flow<br/>build pipeline<br/>[build.ts]"]
  node_react_provider["React provider<br/>ui state<br/>[provider.ts]"]
  node_docs_site["Docs site<br/>documentation app<br/>[index.astro]"]
  node_www_site["Marketing site<br/>web app<br/>[index.astro]"]
  node_example_app["Examples<br/>example catalog<br/>[app.ts]"]
end

node_runtime_index -->|"orchestrates"| node_runtime_dispatch
node_runtime_dispatch -->|"starts runs"| node_runtime_handle_agent
node_runtime_dispatch -->|"routes input"| node_runtime_routing
node_runtime_handle_agent -->|"emits"| node_runtime_streams
node_runtime_handle_agent -->|"persists"| node_runtime_store
node_runtime_routing -->|"webhooks"| node_slack_channel
node_runtime_routing -->|"webhooks"| node_github_channel
node_runtime_routing -->|"webhooks"| node_google_chat_channel
node_node_runtime -->|"uses"| node_runtime_index
node_cf_runtime -->|"uses"| node_runtime_index
node_cf_runtime -->|"hosts"| node_runtime_store
node_sdk_client -->|"consumes"| node_runtime_streams
node_cli_bin -->|"delegates"| node_cli_build
node_cli_build -->|"builds for"| node_node_runtime
node_cli_build -->|"builds for"| node_cf_runtime
node_react_provider -->|"wraps"| node_sdk_client
node_docs_site -->|"documents"| node_runtime_index
node_docs_site -->|"documents"| node_sdk_client
node_www_site -->|"points to"| node_docs_site
node_example_app -->|"demonstrates"| node_runtime_index
node_example_app -->|"demonstrates"| node_sdk_client
node_runtime_store -->|"adapts to"| node_postgres_adapter
node_runtime_store -->|"adapts to"| node_redis_adapter
node_runtime_store -->|"adapts to"| node_mongodb_adapter

click node_runtime_index "https://github.com/withastro/flue/blob/main/packages/runtime/src/index.ts"
click node_runtime_dispatch "https://github.com/withastro/flue/blob/main/packages/runtime/src/runtime/dispatch.ts"
click node_runtime_handle_agent "https://github.com/withastro/flue/blob/main/packages/runtime/src/runtime/handle-agent.ts"
click node_runtime_streams "https://github.com/withastro/flue/blob/main/packages/runtime/src/runtime/handle-stream-routes.ts"
click node_runtime_store "https://github.com/withastro/flue/blob/main/packages/runtime/src/runtime/run-store.ts"
click node_runtime_routing "https://github.com/withastro/flue/blob/main/packages/runtime/src/routing.ts"
click node_node_runtime "https://github.com/withastro/flue/blob/main/packages/runtime/src/node/index.ts"
click node_cf_runtime "https://github.com/withastro/flue/blob/main/packages/runtime/src/cloudflare/index.ts"
click node_sdk_client "https://github.com/withastro/flue/blob/main/packages/sdk/src/client.ts"
click node_cli_bin "https://github.com/withastro/flue/blob/main/packages/cli/bin/flue.ts"
click node_cli_build "https://github.com/withastro/flue/blob/main/packages/cli/src/lib/build.ts"
click node_react_provider "https://github.com/withastro/flue/blob/main/packages/react/src/provider.ts"
click node_docs_site "https://github.com/withastro/flue/blob/main/apps/docs/src/pages/index.astro"
click node_www_site "https://github.com/withastro/flue/blob/main/apps/www/src/pages/index.astro"
click node_example_app "https://github.com/withastro/flue/blob/main/examples/hello-world/src/app.ts"
click node_postgres_adapter "https://github.com/withastro/flue/blob/main/packages/postgres/src/postgres-adapter.ts"
click node_redis_adapter "https://github.com/withastro/flue/blob/main/packages/redis/src/redis-adapter.ts"
click node_mongodb_adapter "https://github.com/withastro/flue/blob/main/packages/mongodb/src/mongodb-adapter.ts"
click node_slack_channel "https://github.com/withastro/flue/blob/main/packages/slack/src/routes.ts"
click node_github_channel "https://github.com/withastro/flue/blob/main/packages/github/src/webhook.ts"
click node_google_chat_channel "https://github.com/withastro/flue/blob/main/packages/google-chat/src/routes.ts"

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_runtime_index,node_runtime_dispatch,node_runtime_handle_agent,node_runtime_streams,node_runtime_store,node_runtime_routing toneBlue
class node_node_runtime,node_cf_runtime toneAmber
class node_slack_channel,node_github_channel,node_google_chat_channel toneMint
class node_postgres_adapter,node_redis_adapter,node_mongodb_adapter toneRose
class node_sdk_client,node_cli_bin,node_cli_build,node_react_provider,node_docs_site,node_www_site,node_example_app toneIndigo
```

## Components

### Runtime engine

Shared agent harness, execution flow, routing, and durable state management.

- [Runtime](https://github.com/withastro/flue/blob/main/packages/runtime/src/index.ts): engine entry · Main runtime surface that ties together agents, tools, routing, streaming, and persistence contracts. · `packages/runtime/src/index.ts`
- [Dispatch](https://github.com/withastro/flue/blob/main/packages/runtime/src/runtime/dispatch.ts): execution flow · Core request-to-run orchestration and event dispatch pipeline. · `packages/runtime/src/runtime/dispatch.ts`
- [Agent run](https://github.com/withastro/flue/blob/main/packages/runtime/src/runtime/handle-agent.ts): agent runner · Resolves and executes agent definitions, instructions, tools, skills, and sandboxed work. · `packages/runtime/src/runtime/handle-agent.ts`
- [Streaming](https://github.com/withastro/flue/blob/main/packages/runtime/src/runtime/handle-stream-routes.ts): event stream · Streaming routes and chunk/result emission back to callers. · `packages/runtime/src/runtime/handle-stream-routes.ts`
- [Run state](https://github.com/withastro/flue/blob/main/packages/runtime/src/runtime/run-store.ts): durability core · Run/session persistence and rehydration primitives used for durable execution. · `packages/runtime/src/runtime/run-store.ts`
- [Routing](https://github.com/withastro/flue/blob/main/packages/runtime/src/routing.ts): request routing · Maps incoming inputs and channels onto the right agent or workflow entrypoint. · `packages/runtime/src/routing.ts`

### Execution targets

Environment-specific runtime implementations for Node.js and Cloudflare.

- [Node runtime](https://github.com/withastro/flue/blob/main/packages/runtime/src/node/index.ts): node target · Local Node.js execution and coordination layer. · `packages/runtime/src/node/index.ts`
- [Cloudflare runtime](https://github.com/withastro/flue/blob/main/packages/runtime/src/cloudflare/index.ts): cloudflare target · Cloudflare Workers coordination, registry, gateway, sandbox, and model/provider plumbing. · `packages/runtime/src/cloudflare/index.ts`

### Integrations

Channel and service packages that expose webhook or route entry points.

- [Slack](https://github.com/withastro/flue/blob/main/packages/slack/src/routes.ts): channel routes · Webhook and route helpers for Slack event entry points. · `packages/slack/src/routes.ts`
- [GitHub](https://github.com/withastro/flue/blob/main/packages/github/src/webhook.ts): webhook channel · Webhook entry points for GitHub events. · `packages/github/src/webhook.ts`
- [Google Chat](https://github.com/withastro/flue/blob/main/packages/google-chat/src/routes.ts): channel routes · Route and auth helpers for Google Chat integrations. · `packages/google-chat/src/routes.ts`

### Persistence

Adapter packages that map runtime state onto different backing stores.

- [Postgres](https://github.com/withastro/flue/blob/main/packages/postgres/src/postgres-adapter.ts): sql adapter · Persistence adapter for relational durable storage. · `packages/postgres/src/postgres-adapter.ts`
- [Redis](https://github.com/withastro/flue/blob/main/packages/redis/src/redis-adapter.ts): kv adapter · Persistence adapter for fast state and event-related storage. · `packages/redis/src/redis-adapter.ts`
- [MongoDB](https://github.com/withastro/flue/blob/main/packages/mongodb/src/mongodb-adapter.ts): document adapter · Persistence adapter for document-oriented durable storage. · `packages/mongodb/src/mongodb-adapter.ts`

### Surfaces and examples

Consumer SDK, React bindings, docs, marketing site, and example topologies.

- [SDK client](https://github.com/withastro/flue/blob/main/packages/sdk/src/client.ts): http client · Consumer-facing client for invoking deployed agents and workflows over HTTP and streaming. · `packages/sdk/src/client.ts`
- [Flue CLI](https://github.com/withastro/flue/blob/main/packages/cli/bin/flue.ts): orchestration CLI · Binary entrypoint for local orchestration, dev, build, and deployment packaging. · `packages/cli/bin/flue.ts`
- [Build flow](https://github.com/withastro/flue/blob/main/packages/cli/src/lib/build.ts): build pipeline · Build/dev orchestration, config loading, and target-specific build plugins. · `packages/cli/src/lib/build.ts`
- [React provider](https://github.com/withastro/flue/blob/main/packages/react/src/provider.ts): ui state · Provider and hooks for observing and controlling runs from React apps. · `packages/react/src/provider.ts`
- [Docs site](https://github.com/withastro/flue/blob/main/apps/docs/src/pages/index.astro): documentation app · Canonical reference surface for guides, API docs, ecosystem pages, and concepts. · `apps/docs/src/pages/index.astro`
- [Marketing site](https://github.com/withastro/flue/blob/main/apps/www/src/pages/index.astro): web app · Public landing, blog, and product marketing surface. · `apps/www/src/pages/index.astro`
- [Examples](https://github.com/withastro/flue/blob/main/examples/hello-world/src/app.ts): example catalog · Representative end-to-end examples covering agents, channels, workflows, sandboxes, and UI integration. · `examples/hello-world/src/app.ts`

## Connections

- Runtime → Dispatch: orchestrates · The entry surface composes the dispatch pipeline.
- Dispatch → Agent run: starts runs · Dispatch resolves an agent and begins execution.
- Dispatch → Routing: routes input · Incoming requests and channel events are routed to the proper handler.
- Agent run → Streaming: emits · Agent execution publishes streaming chunks and results.
- Agent run → Run state: persists · Runs and session progress are durably recorded for later rehydration.
- Routing → Slack: webhooks · Channel packages provide verified entry points into the runtime.
- Routing → GitHub: webhooks · Channel packages provide verified entry points into the runtime.
- Routing → Google Chat: webhooks · Channel packages provide verified entry points into the runtime.
- Node runtime → Runtime: uses · Node target reuses the shared runtime concepts and APIs.
- Cloudflare runtime → Runtime: uses · Cloudflare target reuses the shared runtime concepts and APIs.
- Cloudflare runtime → Run state: hosts · Cloudflare-specific coordination includes durable execution pieces.
- SDK client → Streaming: consumes · The SDK invokes and streams results from deployed runtime instances.
- Flue CLI → Build flow: delegates · The binary entrypoint drives local orchestration and packaging commands.
- Build flow → Node runtime: builds for · CLI produces Node-oriented dev/build flows and plugins.
- Build flow → Cloudflare runtime: builds for · CLI produces Cloudflare-oriented dev/build flows and plugins.
- React provider → SDK client: wraps · React bindings sit on top of the client-facing invocation model.
- Docs site → Runtime: documents · Docs mirror the product architecture and runtime concepts.
- Docs site → SDK client: documents · Docs cover the public SDK and streaming APIs.
- Marketing site → Docs site: points to · Marketing surface leads into the canonical documentation.
- Examples → Runtime: demonstrates · Examples show the runtime in real agent and workflow setups.
- Examples → SDK client: demonstrates · Some examples exercise the external client path.
- Run state → Postgres: adapts to · Runtime persistence can be backed by Postgres.
- Run state → Redis: adapts to · Runtime persistence can be backed by Redis.
- Run state → MongoDB: adapts to · Runtime persistence can be backed by MongoDB.