Concepts

Explanations of architecture, design decisions, and how things work under the hood.

Concept pages explain why Roost is built the way it is. They cover architecture, design trade-offs, and the thinking behind each package — reading material for when you want to deepen your understanding rather than look up a specific API.

Architecture

These pages explain how Roost's parts fit together and the broader decisions that shaped the framework.

Application Architecture — Request lifecycle, boot sequence, and the middleware pipeline
Service Container — Dependency injection, service providers, and the boot protocol
Edge Computing — Why Cloudflare Workers, the V8 isolate model, and what the binding system is
Laravel-Inspired Patterns — What Roost adopted, what it changed, and the DX philosophy
Testing Philosophy — Fakes over mocks, TestClient, and integration-first testing

Package Concepts

Each package has its own design rationale. These pages explain why each package is built the way it is.

@roostjs/core — Why a DI container for Workers, pipeline middleware design
@roostjs/cloudflare — Typed binding wrappers, name resolution, AIClient design
@roostjs/start — TanStack Start integration, the context bridge, SSR on Workers
@roostjs/auth — Why WorkOS, session storage on KV, organization model
@roostjs/orm — Active Record on D1, why not Prisma, migration design
@roostjs/ai — Class-based agents, the agentic loop, Workers AI and no API keys
@roostjs/mcp — What MCP is, server-side tool exposure, MCP vs AI tools
@roostjs/billing — Abstract billing interface, adapter pattern, webhook verification
@roostjs/queue — CF Queues model, job lifecycle, retry and backoff
@roostjs/cli — Code generation philosophy, scaffolding, convention enforcement
@roostjs/testing — TestClient, test application setup, connection to testing philosophy
@roostjs/schema — Fluent schema builder, JSON Schema output, shared AI and MCP schemas