withastro/flue

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.