ArctonArcton
Architecture

Architecture Overview

The layers of Arcton, what each one owns, and the decisions that shape the rest of the framework.

Arcton is built from four pieces with narrow responsibilities:

LayerOwnsKnows nothing about
Adapterstarting a server, native request ↔ Requestrouting, middleware
Routermapping a method and path to a handlerwhat a handler does
Pipelinerunning middleware, providers and validationhow a path matched
Response mappingturning a returned value into a Responsethe rest of the request

The pages in this section explain why each one is built the way it is. If you are looking for how to use them, start from Fundamentals instead.

One decision shapes most of the rest

Arcton resolves as much as it can when routes are registered, not when requests arrive.

  • A route stores its own finished middleware chain, captured at registration.
  • Mounting a module merges its route tree into the parent's, once.
  • Path scopes are resolved into per-route chains, so the router never learns that scopes exist.
  • Route conflicts are detected at registration and throw immediately.

At request time, what is left is: match a path, run a prepared chain, map a value. Nothing has to be recomputed, and nothing about the application's shape can change between requests.

This also keeps the type system honest. ctx is typed from the providers registered before a handler, and that is exactly the set that runs — because the types and the runtime read the same list, in the same order. See Pipeline.

Where the boundaries are

   @arcton/adapter-bun            @arcton/adapter-node
              └───────────┬───────────────┘
                          │  implements RuntimeAdapter
                  @arcton/contracts          ← the shared vocabulary
                          │  types only, no runtime code
                    @arcton/core             ← routing, pipeline, mapping
                          │
                     your application

@arcton/contracts holds no logic. It exists so the core and the adapters can depend on a shared description of a runtime without depending on each other, and so your own code can name those types. See Runtime abstraction.

Reading order

On this page