# chimurai/http-proxy-middleware architecture

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

- Interactive diagram: https://gitdiagram.com/chimurai/http-proxy-middleware
- Repository: https://github.com/chimurai/http-proxy-middleware

## Overview

http-proxy-middleware is a Node.js HTTP/WebSocket proxy middleware with Connect/Express-style and Hono entry points. A host server invokes the middleware; it filters requests, chooses and normalizes a target, rewrites the path, then delegates proxying to httpxy. Plugins and response/request helpers support error handling, events, logging, and body or response manipulation. Edges reflect the sampled middleware implementation, SOURCE INDEX references, and README capabilities; unsampled integrations are represented only where documented.

Main entry points: [`src/http-proxy-middleware.ts`](https://github.com/chimurai/http-proxy-middleware/blob/master/src/http-proxy-middleware.ts) (Proxy middleware), [`src/get-plugins.ts`](https://github.com/chimurai/http-proxy-middleware/blob/master/src/get-plugins.ts) (Plugin selection), [`src/index.ts`](https://github.com/chimurai/http-proxy-middleware/blob/master/src/index.ts) (Public API), [`src/factory.ts`](https://github.com/chimurai/http-proxy-middleware/blob/master/src/factory.ts) (Middleware factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Server integrations"]
  node_api["Public API<br/>[index.ts]"]
  node_factory["Middleware factory<br/>[factory.ts]"]
  node_hono["Hono adapter<br/>[factory-hono.ts]"]
end

subgraph group_request["Request preparation"]
  node_filter["Path filter<br/>[path-filter.ts]"]
  node_router["Target router<br/>[router.ts]"]
  node_rewriter["Path rewriter<br/>[path-rewriter.ts]"]
  node_ipv6["IPv6 normalization<br/>[ipv6.ts]"]
end

subgraph group_proxy["Proxy execution"]
  node_middleware["Proxy middleware"]
  node_httpxy["Proxy engine"]
end

subgraph group_extensions["Hooks and helpers"]
  node_bodyfix["Request body repair"]
  node_formdata["Form-data serializer"]
  node_interceptor["Response interceptor"]
  node_pluginselect["Plugin selection<br/>[get-plugins.ts]"]
  node_eventplugin["Proxy event hooks<br/>[proxy-events.ts]"]
  node_debugplugin["Proxy error diagnostics"]
  node_errorplugin["Error responses"]
  node_loggerplugin["Request logging<br/>[logger-plugin.ts]"]
  node_logger["Logger utility<br/>[logger.ts]"]
end

node_server(("Node server"))
node_upstream(("Upstream service"))

node_server -.->|"mounts middleware"| node_api
node_api -->|"exports factory"| node_factory
node_api -.->|"exports Hono entry"| node_hono
node_factory -->|"constructs"| node_middleware
node_hono -.->|"adapts requests"| node_middleware
node_middleware -->|"checks paths"| node_filter
node_middleware -->|"selects target"| node_router
node_middleware -->|"normalizes target"| node_ipv6
node_middleware -->|"rewrites path"| node_rewriter
node_middleware -->|"proxies HTTP and WebSocket"| node_httpxy
node_httpxy -.->|"forwards traffic"| node_upstream
node_bodyfix -->|"serializes form data"| node_formdata
node_pluginselect -->|"selects default plugins"| node_debugplugin
node_pluginselect -->|"selects default plugins"| node_errorplugin
node_pluginselect -->|"selects default plugins"| node_loggerplugin
node_pluginselect -->|"selects default plugins"| node_eventplugin
node_middleware -->|"registers plugins"| node_pluginselect
node_loggerplugin -->|"gets logger"| node_logger
node_middleware -.->|"supports response hooks"| node_interceptor
node_debugplugin -->|"recommends repair helper"| node_bodyfix

click node_api "https://github.com/chimurai/http-proxy-middleware/blob/master/src/index.ts"
click node_factory "https://github.com/chimurai/http-proxy-middleware/blob/master/src/factory.ts"
click node_hono "https://github.com/chimurai/http-proxy-middleware/blob/master/src/factory-hono.ts"
click node_middleware "https://github.com/chimurai/http-proxy-middleware/blob/master/src/http-proxy-middleware.ts"
click node_filter "https://github.com/chimurai/http-proxy-middleware/blob/master/src/path-filter.ts"
click node_router "https://github.com/chimurai/http-proxy-middleware/blob/master/src/router.ts"
click node_rewriter "https://github.com/chimurai/http-proxy-middleware/blob/master/src/path-rewriter.ts"
click node_ipv6 "https://github.com/chimurai/http-proxy-middleware/blob/master/src/utils/ipv6.ts"
click node_bodyfix "https://github.com/chimurai/http-proxy-middleware/blob/master/src/handlers/fix-request-body.ts"
click node_formdata "https://github.com/chimurai/http-proxy-middleware/blob/master/src/handlers/fix-request-body-utils/stringify-form-data.ts"
click node_interceptor "https://github.com/chimurai/http-proxy-middleware/blob/master/src/handlers/response-interceptor.ts"
click node_pluginselect "https://github.com/chimurai/http-proxy-middleware/blob/master/src/get-plugins.ts"
click node_eventplugin "https://github.com/chimurai/http-proxy-middleware/blob/master/src/plugins/default/proxy-events.ts"
click node_debugplugin "https://github.com/chimurai/http-proxy-middleware/blob/master/src/plugins/default/debug-proxy-errors-plugin.ts"
click node_errorplugin "https://github.com/chimurai/http-proxy-middleware/blob/master/src/plugins/default/error-response-plugin.ts"
click node_loggerplugin "https://github.com/chimurai/http-proxy-middleware/blob/master/src/plugins/default/logger-plugin.ts"
click node_logger "https://github.com/chimurai/http-proxy-middleware/blob/master/src/logger.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_api,node_factory,node_hono toneBlue
class node_filter,node_router,node_rewriter,node_ipv6 toneAmber
class node_middleware,node_httpxy,node_server toneMint
class node_bodyfix,node_formdata,node_interceptor,node_pluginselect,node_eventplugin,node_debugplugin,node_errorplugin,node_loggerplugin,node_logger toneRose
class node_upstream toneIndigo
```

## Components

### Server integrations

- [Public API](https://github.com/chimurai/http-proxy-middleware/blob/master/src/index.ts): `src/index.ts`
- [Middleware factory](https://github.com/chimurai/http-proxy-middleware/blob/master/src/factory.ts): `src/factory.ts`
- [Hono adapter](https://github.com/chimurai/http-proxy-middleware/blob/master/src/factory-hono.ts): `src/factory-hono.ts`

### Request preparation

- [Path filter](https://github.com/chimurai/http-proxy-middleware/blob/master/src/path-filter.ts): `src/path-filter.ts`
- [Target router](https://github.com/chimurai/http-proxy-middleware/blob/master/src/router.ts): `src/router.ts`
- [Path rewriter](https://github.com/chimurai/http-proxy-middleware/blob/master/src/path-rewriter.ts): `src/path-rewriter.ts`
- [IPv6 normalization](https://github.com/chimurai/http-proxy-middleware/blob/master/src/utils/ipv6.ts): `src/utils/ipv6.ts`

### Proxy execution

- [Proxy middleware](https://github.com/chimurai/http-proxy-middleware/blob/master/src/http-proxy-middleware.ts): `src/http-proxy-middleware.ts`
- **Proxy engine**

### Hooks and helpers

- [Request body repair](https://github.com/chimurai/http-proxy-middleware/blob/master/src/handlers/fix-request-body.ts): `src/handlers/fix-request-body.ts`
- [Form-data serializer](https://github.com/chimurai/http-proxy-middleware/blob/master/src/handlers/fix-request-body-utils/stringify-form-data.ts): `src/handlers/fix-request-body-utils/stringify-form-data.ts`
- [Response interceptor](https://github.com/chimurai/http-proxy-middleware/blob/master/src/handlers/response-interceptor.ts): `src/handlers/response-interceptor.ts`
- [Plugin selection](https://github.com/chimurai/http-proxy-middleware/blob/master/src/get-plugins.ts): `src/get-plugins.ts`
- [Proxy event hooks](https://github.com/chimurai/http-proxy-middleware/blob/master/src/plugins/default/proxy-events.ts): `src/plugins/default/proxy-events.ts`
- [Proxy error diagnostics](https://github.com/chimurai/http-proxy-middleware/blob/master/src/plugins/default/debug-proxy-errors-plugin.ts): `src/plugins/default/debug-proxy-errors-plugin.ts`
- [Error responses](https://github.com/chimurai/http-proxy-middleware/blob/master/src/plugins/default/error-response-plugin.ts): `src/plugins/default/error-response-plugin.ts`
- [Request logging](https://github.com/chimurai/http-proxy-middleware/blob/master/src/plugins/default/logger-plugin.ts): `src/plugins/default/logger-plugin.ts`
- [Logger utility](https://github.com/chimurai/http-proxy-middleware/blob/master/src/logger.ts): `src/logger.ts`

### Other components

- **Node server**
- **Upstream service**

## Connections

- Node server → Public API: mounts middleware (evidence: `README.md`)
- Public API → Middleware factory: exports factory (evidence: `src/index.ts`)
- Public API → Hono adapter: exports Hono entry (evidence: `src/factory-hono.ts`)
- Middleware factory → Proxy middleware: constructs (evidence: `src/factory.ts`)
- Hono adapter → Proxy middleware: adapts requests (evidence: `src/factory-hono.ts`)
- Proxy middleware → Path filter: checks paths (evidence: `src/http-proxy-middleware.ts`)
- Proxy middleware → Target router: selects target (evidence: `src/http-proxy-middleware.ts`)
- Proxy middleware → IPv6 normalization: normalizes target (evidence: `src/http-proxy-middleware.ts`)
- Proxy middleware → Path rewriter: rewrites path (evidence: `src/http-proxy-middleware.ts`)
- Proxy middleware → Proxy engine: proxies HTTP and WebSocket (evidence: `src/http-proxy-middleware.ts`)
- Proxy engine → Upstream service: forwards traffic (evidence: `README.md`)
- Request body repair → Form-data serializer: serializes form data (evidence: `src/handlers/fix-request-body.ts`)
- Plugin selection → Proxy error diagnostics: selects default plugins (evidence: `src/get-plugins.ts`)
- Plugin selection → Error responses: selects default plugins (evidence: `src/get-plugins.ts`)
- Plugin selection → Request logging: selects default plugins (evidence: `src/get-plugins.ts`)
- Plugin selection → Proxy event hooks: selects default plugins
- Proxy middleware → Plugin selection: registers plugins (evidence: `src/http-proxy-middleware.ts`)
- Request logging → Logger utility: gets logger (evidence: `src/plugins/default/logger-plugin.ts`)
- Proxy middleware → Response interceptor: supports response hooks (evidence: `README.md`)
- Proxy error diagnostics → Request body repair: recommends repair helper (evidence: `src/plugins/default/debug-proxy-errors-plugin.ts`)
