# simoalanne/rest-rpc architecture

> Architecture diagram of the GitHub repository simoalanne/rest-rpc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simoalanne/rest-rpc
- Repository: https://github.com/simoalanne/rest-rpc

## Overview

rest-rpc provides typed REST route contracts, server runtimes, Fetch clients, OpenAPI support, and a TanStack Query adapter. The principal workflow defines routes and handlers, builds a server app, matches and processes HTTP requests, then lets a typed client call the routes and receive typed responses. The graph also includes codecs, validation, errors, streaming, Node support, and query integration. Edges follow README statements or indexed source references; unsampled subsystems are included where documented, without inferring their internal calls.

Main entry points: [`packages/server/src/pipeline/dispatch.ts`](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/pipeline/dispatch.ts) (Request dispatch), [`packages/core/src/client/createClient.ts`](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/client/createClient.ts) (Typed Fetch client), [`packages/server/src/fetch/createApp.ts`](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/fetch/createApp.ts) (Fetch app), [`packages/server/src/builder/routeBuilder.ts`](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/builder/routeBuilder.ts) (Server implementation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["Route contracts"]
  node_routebuilder["Route builder<br/>[routeBuilder.ts]"]
  node_contract["Route definitions<br/>[routeDefinition.ts]"]
  node_schema["Schema validation"]
  node_errors["Route errors<br/>[routeError.ts]"]
end

subgraph group_server["Server runtimes"]
  node_serverbuilder["Server implementation<br/>[routeBuilder.ts]"]
  node_context["Middleware context<br/>[context.ts]"]
  node_fetchapp["Fetch app<br/>[createApp.ts]"]
  node_fetchhandlers["Fetch handlers"]
  node_nodehandlers["Node handlers"]
  node_matcher["Route matching<br/>[match.ts]"]
  node_dispatch["Request dispatch<br/>[dispatch.ts]"]
  node_serialize["Response serialization"]
  node_sse["Server-sent events<br/>[sse.ts]"]
end

subgraph group_client["Client and codecs"]
  node_client["Typed Fetch client<br/>[createClient.ts]"]
  node_request["Request encoding<br/>[request.ts]"]
  node_response["Client responses<br/>[response.ts]"]
  node_codecs["Body codecs<br/>[registry.ts]"]
end

subgraph group_integrations["API integrations"]
  node_openapi["OpenAPI generation<br/>[document.ts]"]
  node_tanstack["TanStack Query utils<br/>[createUtils.ts]"]
end

node_developer(("Application developer"))
node_http(("HTTP caller"))

node_developer -->|"defines routes"| node_routebuilder
node_routebuilder -->|"builds definitions"| node_contract
node_developer -->|"implements handlers"| node_serverbuilder
node_serverbuilder -->|"uses context"| node_context
node_serverbuilder -->|"configures app"| node_fetchapp
node_fetchapp -->|"matches requests"| node_matcher
node_fetchapp -->|"creates handlers"| node_fetchhandlers
node_fetchhandlers -->|"compiles routes"| node_dispatch
node_nodehandlers -->|"compiles routes"| node_dispatch
node_nodehandlers -->|"matches requests"| node_matcher
node_matcher -->|"enumerates routes"| node_contract
node_dispatch -->|"validates input"| node_schema
node_dispatch -->|"serializes results"| node_serialize
node_dispatch -->|"resolves errors"| node_errors
node_dispatch -->|"handles streams"| node_sse
node_developer -->|"creates client"| node_client
node_client -->|"traverses routes"| node_contract
node_client -->|"builds requests"| node_request
node_client -->|"parses responses"| node_response
node_request -->|"encodes bodies"| node_codecs
node_client -->|"sends requests"| node_http
node_http -->|"delivers request"| node_fetchapp
node_developer -->|"generates API docs"| node_openapi
node_developer -->|"uses query utilities"| node_tanstack

click node_routebuilder "https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/contract/routeBuilder.ts"
click node_contract "https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/contract/routeDefinition.ts"
click node_schema "https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/standard-schema/standardSchemaValidator.ts"
click node_errors "https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/contract/routeError.ts"
click node_openapi "https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/openapi/document.ts"
click node_serverbuilder "https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/builder/routeBuilder.ts"
click node_context "https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/builder/context.ts"
click node_fetchapp "https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/fetch/createApp.ts"
click node_fetchhandlers "https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/fetch/createRouteHandlers.ts"
click node_nodehandlers "https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/node/createRouteHandlers.ts"
click node_matcher "https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/routing/match.ts"
click node_dispatch "https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/pipeline/dispatch.ts"
click node_serialize "https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/pipeline/serializeHttpRouteResult.ts"
click node_sse "https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/pipeline/sse.ts"
click node_client "https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/client/createClient.ts"
click node_request "https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/client/request.ts"
click node_response "https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/client/response.ts"
click node_codecs "https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/codecs/registry.ts"
click node_tanstack "https://github.com/simoalanne/rest-rpc/blob/main/packages/tanstack-query/src/createUtils.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routebuilder,node_contract,node_schema,node_errors toneBlue
class node_serverbuilder,node_context,node_fetchapp,node_fetchhandlers,node_nodehandlers,node_matcher,node_dispatch,node_serialize,node_sse toneAmber
class node_client,node_request,node_response,node_codecs toneMint
class node_openapi,node_tanstack toneRose
class node_developer,node_http toneIndigo
```

## Components

### Route contracts

- [Route builder](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/contract/routeBuilder.ts): `packages/core/src/contract/routeBuilder.ts`
- [Route definitions](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/contract/routeDefinition.ts): `packages/core/src/contract/routeDefinition.ts`
- [Schema validation](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/standard-schema/standardSchemaValidator.ts): `packages/core/src/standard-schema/standardSchemaValidator.ts`
- [Route errors](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/contract/routeError.ts): `packages/core/src/contract/routeError.ts`

### Server runtimes

- [Server implementation](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/builder/routeBuilder.ts): `packages/server/src/builder/routeBuilder.ts`
- [Middleware context](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/builder/context.ts): `packages/server/src/builder/context.ts`
- [Fetch app](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/fetch/createApp.ts): `packages/server/src/fetch/createApp.ts`
- [Fetch handlers](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/fetch/createRouteHandlers.ts): `packages/server/src/fetch/createRouteHandlers.ts`
- [Node handlers](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/node/createRouteHandlers.ts): `packages/server/src/node/createRouteHandlers.ts`
- [Route matching](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/routing/match.ts): `packages/server/src/routing/match.ts`
- [Request dispatch](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/pipeline/dispatch.ts): `packages/server/src/pipeline/dispatch.ts`
- [Response serialization](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/pipeline/serializeHttpRouteResult.ts): `packages/server/src/pipeline/serializeHttpRouteResult.ts`
- [Server-sent events](https://github.com/simoalanne/rest-rpc/blob/main/packages/server/src/pipeline/sse.ts): `packages/server/src/pipeline/sse.ts`

### Client and codecs

- [Typed Fetch client](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/client/createClient.ts): `packages/core/src/client/createClient.ts`
- [Request encoding](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/client/request.ts): `packages/core/src/client/request.ts`
- [Client responses](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/client/response.ts): `packages/core/src/client/response.ts`
- [Body codecs](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/codecs/registry.ts): `packages/core/src/codecs/registry.ts`

### API integrations

- [OpenAPI generation](https://github.com/simoalanne/rest-rpc/blob/main/packages/core/src/openapi/document.ts): `packages/core/src/openapi/document.ts`
- [TanStack Query utils](https://github.com/simoalanne/rest-rpc/blob/main/packages/tanstack-query/src/createUtils.ts): `packages/tanstack-query/src/createUtils.ts`

### Other components

- **Application developer**
- **HTTP caller**

## Connections

- Application developer → Route builder: defines routes (evidence: `README.md`)
- Route builder → Route definitions: builds definitions (evidence: `packages/core/src/contract/routeBuilder.ts`)
- Application developer → Server implementation: implements handlers (evidence: `README.md`)
- Server implementation → Middleware context: uses context (evidence: `packages/server/src/builder/routeBuilder.ts`)
- Server implementation → Fetch app: configures app (evidence: `README.md`)
- Fetch app → Route matching: matches requests (evidence: `packages/server/src/fetch/createApp.ts`)
- Fetch app → Fetch handlers: creates handlers (evidence: `packages/server/src/fetch/createApp.ts`)
- Fetch handlers → Request dispatch: compiles routes (evidence: `packages/server/src/fetch/createRouteHandlers.ts`)
- Node handlers → Request dispatch: compiles routes (evidence: `packages/server/src/node/createRouteHandlers.ts`)
- Node handlers → Route matching: matches requests (evidence: `packages/server/src/node/createRouteHandlers.ts`)
- Route matching → Route definitions: enumerates routes (evidence: `packages/server/src/routing/match.ts`)
- Request dispatch → Schema validation: validates input (evidence: `packages/server/src/pipeline/dispatch.ts`)
- Request dispatch → Response serialization: serializes results (evidence: `packages/server/src/pipeline/dispatch.ts`)
- Request dispatch → Route errors: resolves errors (evidence: `packages/server/src/pipeline/dispatch.ts`)
- Request dispatch → Server-sent events: handles streams (evidence: `packages/server/src/pipeline/dispatch.ts`)
- Application developer → Typed Fetch client: creates client (evidence: `README.md`)
- Typed Fetch client → Route definitions: traverses routes (evidence: `packages/core/src/client/createClient.ts`)
- Typed Fetch client → Request encoding: builds requests (evidence: `packages/core/src/client/createClient.ts`)
- Typed Fetch client → Client responses: parses responses (evidence: `packages/core/src/client/createClient.ts`)
- Request encoding → Body codecs: encodes bodies (evidence: `packages/core/src/client/request.ts`)
- Typed Fetch client → HTTP caller: sends requests (evidence: `README.md`)
- HTTP caller → Fetch app: delivers request (evidence: `README.md`)
- Application developer → OpenAPI generation: generates API docs (evidence: `README.md`)
- Application developer → TanStack Query utils: uses query utilities (evidence: `README.md`)
