# samukadev/routerun architecture

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

- Interactive diagram: https://gitdiagram.com/samukadev/routerun
- Repository: https://github.com/samukadev/routerun

## Overview

RouteRun is a Bun HTTP routing library. An application registers method/path handlers, middleware, parameter callbacks, and nested routers; Router matches requests and dispatches the applicable handler chain, then exports handlers as Bun-native routes whose responses serve the request. Separate capabilities support route inspection, request logging, and a web viewer with JSON and live-log endpoints. The README documents these features; sampled source confirms key dispatch, context, and observability links, while unsampled implementation details are not inferred.

Main entry points: [`lib/router.ts`](https://github.com/samukadev/routerun/blob/main/lib/router.ts) (Router), [`lib/visualizer.ts`](https://github.com/samukadev/routerun/blob/main/lib/visualizer.ts) (Route viewer), [`lib/compose.ts`](https://github.com/samukadev/routerun/blob/main/lib/compose.ts) (Handler dispatcher), [`lib/context.ts`](https://github.com/samukadev/routerun/blob/main/lib/context.ts) (Request context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Route registration"]
  node_router["Router<br/>[router.ts]"]
  node_route["Route builder<br/>[router.ts]"]
  node_exports["Public exports<br/>[index.ts]"]
end

subgraph group_runtime["Request runtime"]
  node_compose["Handler dispatcher<br/>[compose.ts]"]
  node_context["Request context<br/>[context.ts]"]
  node_utils["Route utilities<br/>[utils.ts]"]
  node_types["Public types<br/>[types.ts]"]
end

subgraph group_inspection["Route inspection"]
  node_viewer["Route viewer<br/>[visualizer.ts]"]
  node_viewerhtml["Viewer interface<br/>[visualizer.html]"]
end

subgraph group_logging["Request logging"]
  node_logger["Logger middleware<br/>[logger.ts]"]
  node_logstore[("Request log store<br/>[log-store.ts]")]
end

node_app(("Application"))
node_bun(("Bun server"))
node_request(("HTTP request"))
node_handlers["Route handlers"]
node_response(("HTTP response"))

node_app -->|"registers routes"| node_router
node_router -->|"creates builders"| node_route
node_app -->|"starts server"| node_bun
node_router -->|"exports Bun routes"| node_bun
node_bun -->|"dispatches request"| node_request
node_bun -->|"creates context"| node_context
node_router -->|"dispatches handlers"| node_compose
node_router -->|"matches paths"| node_utils
node_compose -->|"invokes chain"| node_handlers
node_handlers -->|"returns response"| node_response
node_context -->|"sanitizes params"| node_utils
node_app -->|"registers middleware"| node_logger
node_logger -->|"records entries"| node_logstore
node_app -->|"registers viewer"| node_viewer
node_viewer -->|"reads route metadata"| node_router
node_viewer -->|"reads and subscribes"| node_logstore
node_viewer -->|"serves interface"| node_viewerhtml
node_app -->|"imports API"| node_exports
node_router -->|"uses contracts"| node_types

click node_router "https://github.com/samukadev/routerun/blob/main/lib/router.ts"
click node_route "https://github.com/samukadev/routerun/blob/main/lib/router.ts"
click node_compose "https://github.com/samukadev/routerun/blob/main/lib/compose.ts"
click node_context "https://github.com/samukadev/routerun/blob/main/lib/context.ts"
click node_utils "https://github.com/samukadev/routerun/blob/main/lib/utils.ts"
click node_logger "https://github.com/samukadev/routerun/blob/main/lib/logger.ts"
click node_logstore "https://github.com/samukadev/routerun/blob/main/lib/log-store.ts"
click node_viewer "https://github.com/samukadev/routerun/blob/main/lib/visualizer.ts"
click node_viewerhtml "https://github.com/samukadev/routerun/blob/main/resources/visualizer.html"
click node_types "https://github.com/samukadev/routerun/blob/main/lib/types.ts"
click node_exports "https://github.com/samukadev/routerun/blob/main/lib/index.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_router,node_route,node_exports toneBlue
class node_compose,node_context,node_utils,node_types toneAmber
class node_viewer,node_viewerhtml,node_bun,node_request,node_handlers toneMint
class node_logger,node_logstore toneRose
class node_app,node_response toneIndigo
```

## Components

### Route registration

- [Router](https://github.com/samukadev/routerun/blob/main/lib/router.ts): `lib/router.ts`
- [Route builder](https://github.com/samukadev/routerun/blob/main/lib/router.ts): `lib/router.ts`
- [Public exports](https://github.com/samukadev/routerun/blob/main/lib/index.ts): `lib/index.ts`

### Request runtime

- [Handler dispatcher](https://github.com/samukadev/routerun/blob/main/lib/compose.ts): `lib/compose.ts`
- [Request context](https://github.com/samukadev/routerun/blob/main/lib/context.ts): `lib/context.ts`
- [Route utilities](https://github.com/samukadev/routerun/blob/main/lib/utils.ts): `lib/utils.ts`
- [Public types](https://github.com/samukadev/routerun/blob/main/lib/types.ts): `lib/types.ts`

### Route inspection

- [Route viewer](https://github.com/samukadev/routerun/blob/main/lib/visualizer.ts): `lib/visualizer.ts`
- [Viewer interface](https://github.com/samukadev/routerun/blob/main/resources/visualizer.html): `resources/visualizer.html`

### Request logging

- [Logger middleware](https://github.com/samukadev/routerun/blob/main/lib/logger.ts): `lib/logger.ts`
- [Request log store](https://github.com/samukadev/routerun/blob/main/lib/log-store.ts): `lib/log-store.ts`

### Other components

- **Application**
- **Bun server**
- **HTTP request**
- **Route handlers**
- **HTTP response**

## Connections

- Application → Router: registers routes
- Router → Route builder: creates builders
- Application → Bun server: starts server
- Router → Bun server: exports Bun routes
- Bun server → HTTP request: dispatches request
- Bun server → Request context: creates context
- Router → Handler dispatcher: dispatches handlers
- Router → Route utilities: matches paths
- Handler dispatcher → Route handlers: invokes chain
- Route handlers → HTTP response: returns response
- Request context → Route utilities: sanitizes params
- Application → Logger middleware: registers middleware
- Logger middleware → Request log store: records entries
- Application → Route viewer: registers viewer
- Route viewer → Router: reads route metadata
- Route viewer → Request log store: reads and subscribes
- Route viewer → Viewer interface: serves interface
- Application → Public exports: imports API
- Router → Public types: uses contracts