# karthikpro/node-router architecture

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

- Interactive diagram: https://gitdiagram.com/karthikpro/node-router
- Repository: https://github.com/karthikpro/node-router

## Overview

#### Purpose and Runtime
This is a Node.js reverse-proxy server that loads JSON route definitions at runtime and applies configuration changes without restart. It runs on Node.js 16.20.2+ and defaults to port 9000, overridable through `PORT`. The main executable and HTTP composition point is `server.js`; package scripts and dependencies are defined in `package.json`.

#### HTTP Entry Points
The server exposes operational and UI endpoints:
- Dashboard: `/`, rendered from `views/index.ejs`
- Documentation: `/documentation`, rendered from `views/documentation.ejs`
- Health endpoint: `/health`
- Fallback/not-found rendering: `views/404.ejs`

All unmatched proxied traffic is evaluated against the dynamically loaded route configuration.

#### Route Configuration Boundary
Route definitions are JSON documents placed under `routes/`, such as `routes/test.json`. Each file defines a URL context and backend target plus optional request transformations and policies. The `routes/` directory is both the operator-facing control plane and the reload boundary: filesystem changes cause the active routing configuration to refresh.

#### Dynamic Routing and Proxy Stage
`server.js` loads route JSON definitions, maps incoming request paths to a configured `urlContext`, and forwards matching traffic to the configured `backend`. Before forwarding, it can remove a client-facing prefix (`removePrefix`) and prepend a backend-facing prefix (`addPrefix`). This separates public gateway paths from upstream service paths.

#### Per-Route Policy Stage
Each route may carry behavior applied at the proxy boundary:
- CORS settings, such as allowed origins and methods.
- Security headers, using Helmet-backed options such as frameguard and XSS filtering.
- Request logging.
- Upstream timeout settings, with path patterns exempted through `ignoreTimeout`.

These policies belong to route configuration rather than application code, allowing per-upstream behavior without redeployment.

#### External Dependencies and Infrastructure
The process depends on reachable backend HTTP services named by route configuration (for example, `backend-server:8080` in the documented schema). It uses the local filesystem as configuration infrastructure and EJS templates for the built-in operator UI. Dependency versions and runtime libraries are locked by `package-lock.json`.

#### Key Repository Paths
- Runtime server and proxy orchestration: `server.js`
- Package/runtime contract: `package.json`
- Live route configuration directory: `routes/`
- Example route definition: `routes/test.json`
- Operator-facing views: `views/index.ejs`, `views/documentation.ejs`, `views/404.ejs`

Main entry points: [`server.js`](https://github.com/karthikpro/node-router/blob/main/server.js) (HTTP listener), [`routes/test.json`](https://github.com/karthikpro/node-router/blob/main/routes/test.json) (Example route), [`package.json`](https://github.com/karthikpro/node-router/blob/main/package.json) (Package contract), [`package-lock.json`](https://github.com/karthikpro/node-router/blob/main/package-lock.json) (Dependency lock)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Proxy Runtime"]
  node_package["Package contract<br/>Node package<br/>[package.json]"]
  node_lockfile["Dependency lock<br/>npm lockfile<br/>[package-lock.json]"]
  node_server["Proxy server<br/>Node.js entry point<br/>[server.js]"]
  node_http["HTTP listener<br/>HTTP server<br/>[server.js]"]
  node_route_loader["Route loader<br/>dynamic configuration<br/>[server.js]"]
  node_router["Dynamic route matcher<br/>request routing<br/>[server.js]"]
  node_transform["Path transformation<br/>proxy rewrite<br/>[server.js]"]
  node_policy["Per-route policies<br/>proxy middleware<br/>[server.js]"]
end

subgraph group_control["Route Control Plane"]
  node_route_dir[("Live route definitions<br/>JSON configuration directory")]
  node_example_route["Example route<br/>route JSON<br/>[test.json]"]
end

subgraph group_ui["Operator UI"]
  node_dashboard["Dashboard view<br/>EJS template<br/>[index.ejs]"]
  node_documentation["Documentation view<br/>EJS template<br/>[documentation.ejs]"]
  node_not_found["Not-found view<br/>EJS template<br/>[404.ejs]"]
end

node_upstreams{{"Backend HTTP services<br/>external upstreams"}}

node_package -->|"runs"| node_server
node_lockfile -.->|"locks dependencies for"| node_package
node_server -->|"creates"| node_http
node_server -->|"loads configuration"| node_route_loader
node_route_dir -->|"contains"| node_example_route
node_route_dir -->|"reloads on changes"| node_route_loader
node_route_loader -->|"supplies active routes"| node_router
node_http -->|"GET / renders"| node_dashboard
node_http -->|"GET /documentation renders"| node_documentation
node_http -->|"fallback renders"| node_not_found
node_http -->|"unmatched proxy traffic"| node_router
node_router -->|"matching route"| node_transform
node_transform -->|"rewritten request"| node_policy
node_policy -->|"forwards with route policy"| node_upstreams
node_example_route -.->|"urlContext and backend"| node_router
node_example_route -.->|"prefix rules"| node_transform
node_example_route -.->|"policy settings"| node_policy

click node_package "https://github.com/karthikpro/node-router/blob/main/package.json"
click node_lockfile "https://github.com/karthikpro/node-router/blob/main/package-lock.json"
click node_server "https://github.com/karthikpro/node-router/blob/main/server.js"
click node_http "https://github.com/karthikpro/node-router/blob/main/server.js"
click node_example_route "https://github.com/karthikpro/node-router/blob/main/routes/test.json"
click node_route_loader "https://github.com/karthikpro/node-router/blob/main/server.js"
click node_router "https://github.com/karthikpro/node-router/blob/main/server.js"
click node_transform "https://github.com/karthikpro/node-router/blob/main/server.js"
click node_policy "https://github.com/karthikpro/node-router/blob/main/server.js"
click node_dashboard "https://github.com/karthikpro/node-router/blob/main/views/index.ejs"
click node_documentation "https://github.com/karthikpro/node-router/blob/main/views/documentation.ejs"
click node_not_found "https://github.com/karthikpro/node-router/blob/main/views/404.ejs"

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_package,node_lockfile,node_server,node_http,node_route_loader,node_router,node_transform,node_policy toneBlue
class node_route_dir,node_example_route toneAmber
class node_dashboard,node_documentation,node_not_found toneMint
class node_upstreams toneNeutral
```

## Components

### Proxy Runtime

- [Package contract](https://github.com/karthikpro/node-router/blob/main/package.json): Node package · Defines scripts, dependencies, and Node runtime requirements. · `package.json`
- [Dependency lock](https://github.com/karthikpro/node-router/blob/main/package-lock.json): npm lockfile · `package-lock.json`
- [Proxy server](https://github.com/karthikpro/node-router/blob/main/server.js): Node.js entry point · Composes HTTP endpoints, route loading, policies, and proxying. · `server.js`
- [HTTP listener](https://github.com/karthikpro/node-router/blob/main/server.js): HTTP server · Listens on port 9000 by default or PORT. · `server.js`
- [Route loader](https://github.com/karthikpro/node-router/blob/main/server.js): dynamic configuration · Loads route documents into the active routing table. · `server.js`
- [Dynamic route matcher](https://github.com/karthikpro/node-router/blob/main/server.js): request routing · Matches request paths against configured urlContext values. · `server.js`
- [Path transformation](https://github.com/karthikpro/node-router/blob/main/server.js): proxy rewrite · Applies removePrefix and addPrefix before forwarding. · `server.js`
- [Per-route policies](https://github.com/karthikpro/node-router/blob/main/server.js): proxy middleware · Applies CORS, Helmet headers, logging, and timeout rules. · `server.js`

### Route Control Plane

- **Live route definitions**: JSON configuration directory · Filesystem changes reload the active routing configuration.
- [Example route](https://github.com/karthikpro/node-router/blob/main/routes/test.json): route JSON · Defines a URL context, backend, transformations, and policies. · `routes/test.json`

### Operator UI

- [Dashboard view](https://github.com/karthikpro/node-router/blob/main/views/index.ejs): EJS template · `views/index.ejs`
- [Documentation view](https://github.com/karthikpro/node-router/blob/main/views/documentation.ejs): EJS template · `views/documentation.ejs`
- [Not-found view](https://github.com/karthikpro/node-router/blob/main/views/404.ejs): EJS template · `views/404.ejs`

### Other components

- **Backend HTTP services**: external upstreams · Targets named by each route backend, such as backend-server:8080.

## Connections

- Package contract → Proxy server: runs
- Dependency lock → Package contract: locks dependencies for
- Proxy server → HTTP listener: creates
- Proxy server → Route loader: loads configuration
- Live route definitions → Example route: contains
- Live route definitions → Route loader: reloads on changes
- Route loader → Dynamic route matcher: supplies active routes
- HTTP listener → Dashboard view: GET / renders
- HTTP listener → Documentation view: GET /documentation renders
- HTTP listener → Not-found view: fallback renders
- HTTP listener → Dynamic route matcher: unmatched proxy traffic
- Dynamic route matcher → Path transformation: matching route
- Path transformation → Per-route policies: rewritten request
- Per-route policies → Backend HTTP services: forwards with route policy
- Example route → Dynamic route matcher: urlContext and backend
- Example route → Path transformation: prefix rules
- Example route → Per-route policies: policy settings