# Hexagonal architecture

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [Foldkit 0.171.0 requires result Message schemas](/news).

Alistair Cockburn's [2005 article](https://alistair.cockburn.us/hexagonal-architecture/) calls the pattern "Ports and Adapters," with "Hexagonal Architecture" as its alternative name. Users, programs, tests, or batch scripts can drive the application. Tests can run without its eventual devices and databases.

A port is an interface for an application job.
A technology-specific adapter implements that interface for an outside system. The application need not know what is on the other side. The distinction is inside versus outside, not a prescribed number of sides.

## Rat-stack's stance

Joel Hooks:

> I think hexagonal and ports and adapters, generally speaking, is an extremely good fit and matches what we are kind of doing anyway inside of our effect layer. So if we were putting a name on the architecture or a principle from which we derive our own version of the architecture, hexagonal would be it. We are not zealots. However, we do recognize really good ideas when we see them.

Rat-stack's Effect layer follows the inside/outside boundary. We adapt that principle without requiring the whole architecture, its diagram, or particular folder names.

## How rat-stack does it

On the driving side, interfaces call the application.
[One capability, every surface](/lore/one-capability-every-surface) starts with a contract, binds a handler, and projects CLI, HTTP, MCP, RPC, and code mode. The [no-hand-rolled-surface rule](https://github.com/joelhooks/rat-stack/blob/main/scripts/oxlint-plugin-boundaries.ts) keeps interface construction in the projection package.

On the driven side, Effect `Context.Service` definitions provide ports for [subscriber intake (`SubscriberIntake`)](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/interest-intake.ts) and [confirmation (`SubscriberConfirm`)](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/interest-confirm-port.ts).
[Delivery Layers](https://github.com/joelhooks/rat-stack/blob/main/packages/subscriber-delivery/src/delivery.ts) implement those ports outside core.
[Worker wiring](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/worker.ts) supplies the production implementations.

Applications now use the agent-only `joinInterest` capability. The former browser submission routes return 410.
Browser email-link confirmation remains. [Interest signup](/systems/interest) documents the current flow.

Typed preparation for agent-assisted intake uses the same service boundary: [`IntakeTicket`, `AbuseScore`, and `IntakeEvents`](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/intake.ts), question and consent schemas, and test layers live in core. [Interest signup](/systems/interest) records the agent-only application path and email confirmation boundary.

## Boundaries fixed

Three leaks have been fixed:

- HTTP adapters lived beside ports in core. Intake and confirmation adapters now live in [`@rat-stack/subscriber-delivery`](https://github.com/joelhooks/rat-stack/tree/main/packages/subscriber-delivery/src), composed by `src/delivery.ts`.
- Two ports were named for the provider rather than the job. [`SubscriberIntake`](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/interest-intake.ts) and [`SubscriberConfirm`](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/interest-confirm-port.ts) name the jobs.
- No lint rule kept core free of adapters. [`no-core-adapters`](https://github.com/joelhooks/rat-stack/blob/main/scripts/oxlint-plugin-boundaries.ts) rejects HTTP-client and adapter/vendor imports from core, with [failing-case tests](https://github.com/joelhooks/rat-stack/blob/main/packages/core/test/boundaries-rule.test.ts).

[Cartridges](/lore/cartridges) adds rat-stack's own packaging and removal test, including infrastructure supplied through `Layer.provide`. [A Layer as constructor](/lore/layer-constructor-pattern) explains the construction mechanism.

## Sources

1. [Hexagonal architecture the original 2005 article](https://alistair.cockburn.us/hexagonal-architecture/)
   Alistair Cockburn. Original ports-and-adapters article; used for the inside/outside boundary. Accessed 2026-10-01.

2. [rat-stack/packages/core/src/interest-confirm-port.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/interest-confirm-port.ts)
   GitHub joelhooks/rat-stack. Confirmation port; used for the driven-side service boundary. Accessed 2026-10-01.

3. [rat-stack/packages/core/src/interest-intake.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/core/src/interest-intake.ts)
   GitHub joelhooks/rat-stack. Intake port; used for subscriber intake independent of its adapter. Accessed 2026-10-01.

4. [rat-stack/packages/subscriber-delivery/src/delivery.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/subscriber-delivery/src/delivery.ts)
   GitHub joelhooks/rat-stack. Delivery composition; used for the HTTP adapters outside core. Accessed 2026-10-01.

5. [rat-stack/apps/site/src/worker.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/apps/site/src/worker.ts)
   GitHub joelhooks/rat-stack. Worker composition; used for production adapter wiring. Accessed 2026-10-01.

## Lore on this page

- [One program can replace several tool calls](/lore/one-program-can-replace-several-tool-calls)
- [Double opt-in](/lore/double-opt-in)

## Linked from

- A clean playground → rat-stack does real work with packages that stay easy to add and remove. → [Read page](https://ratstack.sh/lore/a-clean-playground)

- add-a-feature-flag → Declare a typed feature flag, its scoped evidence ladder, approval roles, removal date, and durable ledger adapter. → [Read page](https://ratstack.sh/skills/add-a-feature-flag)

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- Alchemy Domain models a business as commands, aggregates, and events → Alchemy Domain is a domain-driven design framework for Effect whose one model runs in memory for tests and on Cloudflare Durable Objects in production. → [Read page](https://ratstack.sh/lore/alchemy-domain)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Code snippets quote a pinned source → Shipped design brief: pinned Git objects, typed diagnostics, and one build-only snippet model for both views. → [Read page](https://ratstack.sh/lore/code-snippets)

- durability → Keep a rat-stack app standing when a provider, pool, or dependency slows down or a worker dies. Use at any I/O boundary, connection pool, provider call, shared waiter, fan-out, flag, gate, or work that can outlive a request, or when asked "what happens when this is slow", "add a timeout", "make this durable", or "what survives a crash". → [Read page](https://ratstack.sh/skills/durability)

- Durability → Seven durable Effect patterns, each with its seam, its fence, and the incident that taught it. → [Read page](https://ratstack.sh/systems/durability)

- Durable timers need recovery → Persist scheduled intent when losing a worker must not lose its deadlines. → [Read page](https://ratstack.sh/lore/durable-timers-need-recovery)

- Effect keeps the surfaces on one contract → Schema owns values, projections build interfaces, and Layers supply implementations. → [Read page](https://ratstack.sh/lore/how-we-do-it-with-effect)

- Engine-neutral tokens keep adapters replaceable → The highlighter port exposes text, roles, and font styles rather than Shiki types. → [Read page](https://ratstack.sh/lore/engine-neutral-tokens-keep-adapters-replaceable)

- Feature flags → Typed feature flags with owners, removal dates, and stable subject rollouts. → [Read page](https://ratstack.sh/systems/flags)

- Flags climb on evidence → A flag ladder connects each rollout step to scoped measurements, approval, and a durable receipt. → [Read page](https://ratstack.sh/lore/flags-climb-on-evidence)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- HTTP success needs a status check and a decoder → Supply the client, check the response status, decode accepted data, and name failures at the adapter boundary. → [Read page](https://ratstack.sh/lore/http-responses-need-validation)

- Interest signup → Agent-only applications start email confirmation through interfaces owned by core and delivery implemented in a separate package. → [Read page](https://ratstack.sh/systems/interest)

- Learn mode presents concepts at useful depths → An agent presents source-derived concepts during real work and keeps learning events in a private local log. → [Read page](https://ratstack.sh/systems/learn)

- Learn the stack | rat-stack → Hands-on guides to Effect actions, XState lifecycles, and the seams between stack pieces. → [Read page](https://ratstack.sh/skills)

- learn-rat-stack → Trace a capability through Effect, XState, five projections, the CLI, and Alchemy. Try hosted search and read. → [Read page](https://ratstack.sh/skills/learn-rat-stack)

- Motion → @rat-stack/motion gives Foldkit apps Penner and CSS easings, tweens, fixed-step springs and interpolation, held in the Model and checked by properties. → [Read page](https://ratstack.sh/systems/motion)

- onboard-a-list → Analyze or migrate an email list. Measure sanitation rules, preserve stops, choose a cohort, and verify an authorized import or sending cutover. → [Read page](https://ratstack.sh/skills/onboard-a-list)

- One capability, every surface → A schema-typed contract and one handler feed every interface rat-stack keeps. → [Read page](https://ratstack.sh/lore/one-capability-every-surface)

- Pin the source and report drift separately → A pinned excerpt stays fixed while a separate diagnostic compares it with HEAD. → [Read page](https://ratstack.sh/lore/pinned-sources-can-report-drift)

- Private catalog → An authenticated Alchemy Domain model records observations and decisions, with a replayable D1 index for trends. → [Read page](https://ratstack.sh/systems/catalog)

- Queries need result bounds → Limit result cardinality before the driver materializes an oversized response. → [Read page](https://ratstack.sh/lore/queries-need-result-bounds)

- query-design → Design or review SQL reads, writes, scans, backfills, and slow database paths. Use before changing a store method or any loop that queries. Covers round-trip arithmetic, batching, keyset paging, index evidence, row budgets, PlanetScale Vitess limits, Hyperdrive connections, statement-count tests, and statement-template fences. → [Read page](https://ratstack.sh/skills/query-design)

- Rat Stack lore | rat-stack → Short, source-grounded notes on the ideas and decisions behind rat-stack. → [Read page](https://ratstack.sh/lore)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)

- Structure an Effect codebase by domain → Start with folders for application work, services and Layers in the same file, and startup code that supplies implementations. → [Read page](https://ratstack.sh/lore/structure-effect-by-domain)

- Turbo remote cache → A separate Worker stores streamed Turbo artifacts in R2, with team-scoped writer and reader credentials and lifecycle expiry. → [Read page](https://ratstack.sh/systems/turbo-cache)

## Unlinked mentions

- [A cartridge owns one job and its resources](https://ratstack.sh/lore/cartridges) → ts picks Better Auth’s D1 or Hyperdrive adapter.¶

- [A clean playground](https://ratstack.sh/lore/a-clean-playground) → One-line infrastructure removal remains unproven for that adapter.¶

- [add-a-feature-flag](https://ratstack.sh/skills/add-a-feature-flag) → The memory adapter supplies the same domain behavior for tests.¶

- [add-a-store](https://ratstack.sh/skills/add-a-store) → An adapter implements those operations for a storage provider.¶

- [Agent rules for rat-stack (AGENTS.md)](https://ratstack.sh/AGENTS.md) → defaults(eventFlags) to remove the adapter package.

- [Analytics](https://ratstack.sh/systems/analytics) → The packages/crash cartridge owns the CrashArchive port and its R2 adapter.

- [Build and run rat-stack (README.md)](https://ratstack.sh/README.md) → Role: Easing, tweens, springs and interpolation as dependency-free TypeScript, with an optional Foldkit adapter

- [Capabilities](https://ratstack.sh/systems/capabilities) → A downstream storage adapter owns its statement and row limits.¶

- [Code snippets quote a pinned source](https://ratstack.sh/lore/code-snippets) → The adapter maps svx to Markdown and txt to text; it accepts javascript explicitly.¶

- [durability](https://ratstack.sh/skills/durability) → Use: A Durable Object adapter behind an Effect service¶

- [Durability](https://ratstack.sh/systems/durability) → The default operator adapter commits position, receipt and projection marker in one Durable Object transaction.¶

- [Effect + Alchemy peer patterns](https://ratstack.sh/resources/same-version-repos) → It is a separately published Alchemy package with provider subpaths, so rat-stack can use it without forking an adapter.

- [Effect + Alchemy peers](https://ratstack.sh/resources/peers) → Why this tier: Active Oct 27; studied its SQLite-backed D1 test adapter.

- [Effect 4 study: September 2026](https://ratstack.sh/resources/effect-4-reference-projects) → Alchemy and its Better Auth adapter use beta.81.

- [Effect basics](https://ratstack.sh/lore/effect-basics) → The Worker returns a fetch Effect to its Alchemy Worker adapter:¶

- [Effect keeps the surfaces on one contract](https://ratstack.sh/lore/how-we-do-it-with-effect) → Hexagonal architecture names the adapter boundary.

- [Engine-neutral tokens keep adapters replaceable](https://ratstack.sh/lore/engine-neutral-tokens-keep-adapters-replaceable) → The proposed Shiki adapter keeps Shiki’s token type inside the adapter.

- [Feature flags](https://ratstack.sh/systems/flags) → The memory adapter supplies rules and writable values for tests.¶

- [Fence](https://ratstack.sh/systems/fence) → An adapter implements an application-owned interface for a specific provider.¶

- [Hosted agent interfaces](https://ratstack.sh/systems/agent-front-door) → Its asset adapter adds a delay to make cold reads overlap.

- [HTTP success needs a status check and a decoder](https://ratstack.sh/lore/http-responses-need-validation) → An adapter implements an application interface for a provider.¶

- [Interest signup](https://ratstack.sh/systems/interest) → packages/subscriber-delivery provides the adapter, the implementation that connects those interfaces to external delivery.

- [keep-or-cut](https://ratstack.sh/skills/keep-or-cut) → ts, and the HTTP adapter test¶

- [Layer composition makes dependencies explicit](https://ratstack.sh/lore/layers-make-dependencies-explicit) → The application chooses its workspace layout and adapter package boundaries.¶

- [Learn mode presents concepts at useful depths](https://ratstack.sh/systems/learn) → The command-line interface (CLI) and MCP tools use a local progress adapter, an implementation that connects learning operations to local files.

- [learn-alchemy](https://ratstack.sh/skills/learn-alchemy) → sh as a redirect, and port 1337 for dev.¶

- [Lint and type escape ledger (debt.md)](https://ratstack.sh/debt.md) → js Drizzle adapter exposes Promise-based queries.

- [One prompt serves people and agents](https://ratstack.sh/systems/prompts) → Core owns the PromptLibrary port, an interface for listing and reading prompts.¶

- [Purpose and boundaries of rat-stack (VISION.md)](https://ratstack.sh/VISION.md) → New code takes the rat-stack path: a shared contract, a job-shaped service port, a provider adapter outside core, and an outcome you can observe.

- [query-design](https://ratstack.sh/skills/query-design) → Follow add-a-store for job-shaped operations and adapter Layers.

- [rat-stack-mode](https://ratstack.sh/skills/rat-stack-mode) → md: choosing an adapter or testing its behavior.¶

- [Run Effect at the integration boundary](https://ratstack.sh/lore/run-effect-at-the-boundary) → The checked adapter exposes a small Promise API to a hypothetical foreign framework.

- [Scopes release resources when work ends](https://ratstack.sh/lore/scopes-own-resources) → The migration adapter opens a Postgres client inside Effect.tryPromise.

- [security-audit](https://ratstack.sh/skills/security-audit) → The Worker adapter is sandbox-worker-loader.ts.

- [ship](https://ratstack.sh/skills/ship) → Adapter: the implementation that connects the release procedure to a deployment provider.¶

- [Structure an Effect codebase by domain](https://ratstack.sh/lore/structure-effect-by-domain) → An adapter implements an interface for a platform or provider.¶

- [There is no ISR on Cloudflare](https://ratstack.sh/lore/there-is-no-isr-on-cloudflare) → There is no SvelteKit isr switch for the Cloudflare adapter.

- [Turbo remote cache](https://ratstack.sh/systems/turbo-cache) → The adapter adds no application capability or alternate agent route.¶

- [uncomplect](https://ratstack.sh/skills/uncomplect) → Adapter: An implementation of a port for a particular provider.¶

- [write-a-wiki-page](https://ratstack.sh/skills/write-a-wiki-page) → Real repair message: “\[CodeRepositoryConfigInvalid] Configure repositories as {id, adapter, location, linkTemplate?}.”¶
