Architecture Overview

Layers

Crate is organized into six layers, each with a single responsibility. A request flows top-down through these layers.

1. Public API (crate.http.router)

   crateSetup!RestApi, crateRouter.add(), crateRouter.prepare() — the functions you call in your application code. These are convenience wrappers that create and configure the layers below.

2. CrateRouter (crate.http.routing.crateRouter)

   Multi-policy orchestration and HTTP dispatch. Integrates with vibe.d’s URLRouter, manages an array of ITypeRouter instances, and routes incoming requests to the right operation. One CrateRouter per application, parameterized by policies.

3. TypeRouter (crate.http.routing.typeRouter)

   One instance per policy-model combination. Auto-generates CRUD operations by inspecting the Policy struct at compile time. Contains a BlankRouter internally via composition.

4. BlankRouter (crate.http.routing.blankRouter)

   Stores an array of IApiOperation and matches requests by method, path, and optional body. No model awareness — just a flat operation registry with a match() method.

5. IApiOperation (crate.http.operations.*)

   One per endpoint. GetListApiOperation, CreateItemApiOperation, etc. Each operation knows its rule (method, path, response format) and orchestrates: middleware pipeline, data access, response mappers, and serialization.

6. Data and Middleware

   Middleware Pipeline

   Query filters (@any, @get, @create, etc.) and request middleware that run before the operation accesses data.

   Response Mappers

   @mapper functions that transform each item before serialization. Used to add computed properties or hide fields. Mappers are per-type, so they apply uniformly regardless of which request triggered the response.

   Crate!T (Data Access)

   MemoryCrate, MongoCrate — the storage backend. Operations read/write through the Crate!T interface.

   Serializer

   Converts the mapped items into the wire format. RestApiSerializer wraps in model-name keys, JsonApiSerializer uses JSON:API envelopes, etc. Runs after response mappers.

The Key Classes

CrateRouter

The entry point. Created via router.crateSetup!RestApi. Responsibilities:

• Integrates with vibe.d’s URLRouter via a catch-all any("*") handler
• Manages an array of ITypeRouter instances (TypeRouters and BlankRouters)
• Dispatches HTTP requests by iterating through routers to find a matching operation
• Handles CORS/OPTIONS preflight requests
• Supports multiple policies as template parameters (e.g., CrateRouter!(RestApi, Mcp))
• Provides policy lifecycle hooks (onRouterInit, onRouterReady)

TypeRouter

Created by CrateRouter for each model+policy combination. When constructed, it:

1. Inspects the Policy struct at compile time for methods returning CrateRule
2. Creates an operation class for each CRUD method (GetList, GetItem, CreateItem, etc.)
3. Recursively discovers nested resources (struct members implementing CrateResource)
4. Stores everything in an internal BlankRouter via composition

TypeRouter is also responsible for exposing action methods (.expose!) and item operations (.itemOperation!).

BlankRouter

The simplest router. An array of IApiOperation instances with a match() method. Has no model awareness — it just stores operations and finds which one matches a given HTTP method + path + optional body.

TypeRouter wraps one. CrateRouter also creates standalone BlankRouters for custom operations (via .blank()).

IApiOperation

Interface for all endpoint handlers. Each operation knows its CrateRule (method, path, response format) and implements handle(OperationContext).

Concrete implementations use two mixin templates for shared behavior:

• ApiOperationMixin — middleware pipeline, rule management, response mapping
• CrateOperationMixin — database query building, item fetching, ETag generation

Why Composition Over Inheritance

TypeRouter contains a BlankRouter rather than extending it. This is intentional:

1. TypeRouter adds compile-time model introspection that BlankRouter doesn’t need
2. BlankRouter is reusable standalone (for custom endpoints, policy initialization)
3. Both implement ITypeRouter, so CrateRouter treats them uniformly
4. The internal BlankRouter holds the actual operations array — TypeRouter just populates it

Why Policies Are Structs

Policies (RestApi, Mcp, GraphQL) are stateless structs with only static methods. This design:

1. Makes policies zero-cost at runtime — no allocations, no virtual dispatch
2. Enables compile-time introspection via describe!Policy
3. Allows policies to be template parameters (CrateRouter!(RestApi, Mcp))
4. Prevents shared mutable state between models using the same policy

The Global crateGetters Registry

When a model references another model (e.g., Campaign has a Team field), Crate needs to resolve the Team ID to a full Team object during POST/PATCH operations. This is done through crateGetters, a global CrateAccess.GetItem[string] map:

crateGetters["Team"] = &teamCrate.getItem;

Why global? Because D’s template system makes it impractical to thread type information through all the layers. A Campaign’s serializer needs to know about Team, but Campaign and Team are compiled separately. The global registry solves this at runtime.

The collectRequiredGetters!T template validates at startup that all required getters are registered.