# debanshup/mitm-core architecture

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

- Interactive diagram: https://gitdiagram.com/debanshup/mitm-core
- Repository: https://github.com/debanshup/mitm-core

## Overview

mitm-core is a Node.js MITM proxy framework. A client connects to the Proxy, whose middleware initializes connection/request scopes, dispatches protocol lifecycle events, and runs phased handlers; the transport layer forwards traffic to upstreams and returns responses. Plugins can inspect or modify traffic, while rules, TLS certificate handling, and optional response caching provide policy and supporting capabilities. The README documents HTTP/1.1, HTTPS, WebSockets, streaming, and lifecycle support; some of those implementation links are documented capabilities rather than sampled call paths.

Main entry points: [`src/core/pipelines/PipelineCompiler.ts`](https://github.com/debanshup/mitm-core/blob/main/src/core/pipelines/PipelineCompiler.ts) (Pipeline compiler), [`src/lib/Proxy.ts`](https://github.com/debanshup/mitm-core/blob/main/src/lib/Proxy.ts) (Proxy API), [`src/middleware/middleware.ts`](https://github.com/debanshup/mitm-core/blob/main/src/middleware/middleware.ts) (Connection middleware), [`src/core/event/proxy-events/proxyEvents.ts`](https://github.com/debanshup/mitm-core/blob/main/src/core/event/proxy-events/proxyEvents.ts) (Proxy events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Proxy entry"]
  node_proxy["Proxy API<br/>[Proxy.ts]"]
  node_middleware["Connection middleware<br/>[middleware.ts]"]
end

subgraph group_pipeline["Processing pipeline"]
  node_pipelinecompiler["Pipeline compiler"]
  node_phase["Lifecycle phases<br/>[Phase.ts]"]
  node_requesthandler["Request handling<br/>[request.handler.ts]"]
  node_responsehandler["Response handling"]
  node_handshake["TLS handshake"]
end

subgraph group_transport["Protocol transports"]
  node_h1in["HTTP/1 inbound<br/>[H1InboundBridge.ts]"]
  node_upstream["HTTP/1 upstream"]
  node_h1out["HTTP/1 outbound"]
  node_websocket["WebSocket bridge"]
  node_http2["HTTP/2 bridges<br/>[H2InboundBridge.ts]"]
  node_streaming["Streaming responses"]
end

subgraph group_extensions["Plugins and policy"]
  node_plugins["Plugin lifecycle<br/>[BasePlugin.ts]"]
  node_pluginevents["Plugin events<br/>[pluginEvents.ts]"]
  node_proxyevents["Proxy events<br/>[proxyEvents.ts]"]
  node_ruleengine["Rule engine<br/>[RuleEngine.ts]"]
  node_rulestore["Rule store<br/>[ruleStore.ts]"]
end

subgraph group_runtime["Runtime services"]
  node_scope["Request scopes<br/>[ContextManager.ts]"]
  node_mutator["Scope mutation<br/>[ScopeMutator.ts]"]
  node_secure["TLS contexts"]
  node_certcache[("Certificate cache")]
  node_responsecache[("Response cache<br/>[ResponseCache.ts]")]
  node_state["Request state<br/>[StateStore.ts]"]
end

node_client(("Client"))

node_client -->|"connects to"| node_proxy
node_proxy -->|"registers"| node_middleware
node_middleware -->|"initializes context"| node_scope
node_middleware -->|"runs pipeline"| node_pipelinecompiler
node_middleware -->|"emits lifecycle events"| node_pluginevents
node_middleware -->|"emits connection events"| node_proxyevents
node_middleware -->|"initializes scopes"| node_mutator
node_pipelinecompiler -->|"dispatches phases"| node_phase
node_pipelinecompiler -->|"dispatches handlers"| node_requesthandler
node_pipelinecompiler -->|"dispatches handlers"| node_responsehandler
node_pipelinecompiler -->|"dispatches handlers"| node_handshake
node_pipelinecompiler -->|"executes bridge"| node_websocket
node_pipelinecompiler -->|"reports errors"| node_proxyevents
node_requesthandler -->|"initiates upstream"| node_upstream
node_requesthandler -->|"mutates scope"| node_mutator
node_responsehandler -->|"writes response"| node_h1out
node_handshake -->|"creates TLS context"| node_secure
node_handshake -->|"uses inbound bridge"| node_h1in
node_handshake -->|"reports lifecycle"| node_proxyevents
node_plugins -->|"uses event hooks"| node_pluginevents
node_secure -->|"uses certificate cache"| node_certcache
node_streaming -->|"processes cached responses"| node_responsecache
node_streaming -->|"updates scope"| node_mutator
node_scope -->|"creates lifecycle state"| node_state
node_ruleengine -->|"uses rule store"| node_rulestore
node_websocket -->|"intercepts messages"| node_pluginevents
node_websocket -->|"emits message events"| node_proxyevents
node_websocket -->|"updates scope"| node_mutator
node_h1in -->|"emits connection events"| node_proxyevents
node_h1in -->|"uses request context"| node_scope
node_proxy -->|"manages plugins"| node_plugins
node_proxy -->|"manages active requests"| node_scope
node_proxy -->|"reports proxy errors"| node_proxyevents
node_client -.->|"uses HTTP/2"| node_http2
node_client -->|"upgrades WebSocket"| node_websocket
node_upstream -.->|"streams responses"| node_streaming
node_client -.->|"traffic governed by rules"| node_ruleengine
node_proxy -.->|"optionally caches responses"| node_responsecache

click node_proxy "https://github.com/debanshup/mitm-core/blob/main/src/lib/Proxy.ts"
click node_middleware "https://github.com/debanshup/mitm-core/blob/main/src/middleware/middleware.ts"
click node_scope "https://github.com/debanshup/mitm-core/blob/main/src/core/scope/ContextManager.ts"
click node_mutator "https://github.com/debanshup/mitm-core/blob/main/src/core/scope/ScopeMutator.ts"
click node_pipelinecompiler "https://github.com/debanshup/mitm-core/blob/main/src/core/pipelines/PipelineCompiler.ts"
click node_phase "https://github.com/debanshup/mitm-core/blob/main/src/phase/Phase.ts"
click node_requesthandler "https://github.com/debanshup/mitm-core/blob/main/src/core/handlers/request.handler.ts"
click node_responsehandler "https://github.com/debanshup/mitm-core/blob/main/src/core/handlers/response.handler.ts"
click node_handshake "https://github.com/debanshup/mitm-core/blob/main/src/core/handlers/handshake.handler.ts"
click node_h1in "https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http1/H1InboundBridge.ts"
click node_upstream "https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http1/UpstreamInitiator.ts"
click node_h1out "https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http1/H1OutboundBridge.ts"
click node_websocket "https://github.com/debanshup/mitm-core/blob/main/src/core/transport/ws/WSOutboundBridge.ts"
click node_http2 "https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http2/H2InboundBridge.ts"
click node_plugins "https://github.com/debanshup/mitm-core/blob/main/src/core/plugin/BasePlugin.ts"
click node_pluginevents "https://github.com/debanshup/mitm-core/blob/main/src/core/event/plugin-events/pluginEvents.ts"
click node_proxyevents "https://github.com/debanshup/mitm-core/blob/main/src/core/event/proxy-events/proxyEvents.ts"
click node_ruleengine "https://github.com/debanshup/mitm-core/blob/main/src/core/rule/RuleEngine.ts"
click node_rulestore "https://github.com/debanshup/mitm-core/blob/main/src/core/rule/ruleStore.ts"
click node_secure "https://github.com/debanshup/mitm-core/blob/main/src/core/security/SecureContextManager.ts"
click node_certcache "https://github.com/debanshup/mitm-core/blob/main/src/core/cache/CertificateCacheManager.ts"
click node_responsecache "https://github.com/debanshup/mitm-core/blob/main/src/core/cache/ResponseCache.ts"
click node_streaming "https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http1/streamingResponseHandler.ts"
click node_state "https://github.com/debanshup/mitm-core/blob/main/src/core/state/StateStore.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_proxy,node_middleware,node_client toneBlue
class node_pipelinecompiler,node_phase,node_requesthandler,node_responsehandler,node_handshake toneAmber
class node_h1in,node_upstream,node_h1out,node_websocket,node_http2,node_streaming toneMint
class node_plugins,node_pluginevents,node_proxyevents,node_ruleengine,node_rulestore toneRose
class node_scope,node_mutator,node_secure,node_certcache,node_responsecache,node_state toneIndigo
```

## Components

### Proxy entry

- [Proxy API](https://github.com/debanshup/mitm-core/blob/main/src/lib/Proxy.ts): `src/lib/Proxy.ts`
- [Connection middleware](https://github.com/debanshup/mitm-core/blob/main/src/middleware/middleware.ts): `src/middleware/middleware.ts`

### Processing pipeline

- [Pipeline compiler](https://github.com/debanshup/mitm-core/blob/main/src/core/pipelines/PipelineCompiler.ts): `src/core/pipelines/PipelineCompiler.ts`
- [Lifecycle phases](https://github.com/debanshup/mitm-core/blob/main/src/phase/Phase.ts): `src/phase/Phase.ts`
- [Request handling](https://github.com/debanshup/mitm-core/blob/main/src/core/handlers/request.handler.ts): `src/core/handlers/request.handler.ts`
- [Response handling](https://github.com/debanshup/mitm-core/blob/main/src/core/handlers/response.handler.ts): `src/core/handlers/response.handler.ts`
- [TLS handshake](https://github.com/debanshup/mitm-core/blob/main/src/core/handlers/handshake.handler.ts): `src/core/handlers/handshake.handler.ts`

### Protocol transports

- [HTTP/1 inbound](https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http1/H1InboundBridge.ts): `src/core/transport/http1/H1InboundBridge.ts`
- [HTTP/1 upstream](https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http1/UpstreamInitiator.ts): `src/core/transport/http1/UpstreamInitiator.ts`
- [HTTP/1 outbound](https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http1/H1OutboundBridge.ts): `src/core/transport/http1/H1OutboundBridge.ts`
- [WebSocket bridge](https://github.com/debanshup/mitm-core/blob/main/src/core/transport/ws/WSOutboundBridge.ts): `src/core/transport/ws/WSOutboundBridge.ts`
- [HTTP/2 bridges](https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http2/H2InboundBridge.ts): `src/core/transport/http2/H2InboundBridge.ts`
- [Streaming responses](https://github.com/debanshup/mitm-core/blob/main/src/core/transport/http1/streamingResponseHandler.ts): `src/core/transport/http1/streamingResponseHandler.ts`

### Plugins and policy

- [Plugin lifecycle](https://github.com/debanshup/mitm-core/blob/main/src/core/plugin/BasePlugin.ts): `src/core/plugin/BasePlugin.ts`
- [Plugin events](https://github.com/debanshup/mitm-core/blob/main/src/core/event/plugin-events/pluginEvents.ts): `src/core/event/plugin-events/pluginEvents.ts`
- [Proxy events](https://github.com/debanshup/mitm-core/blob/main/src/core/event/proxy-events/proxyEvents.ts): `src/core/event/proxy-events/proxyEvents.ts`
- [Rule engine](https://github.com/debanshup/mitm-core/blob/main/src/core/rule/RuleEngine.ts): `src/core/rule/RuleEngine.ts`
- [Rule store](https://github.com/debanshup/mitm-core/blob/main/src/core/rule/ruleStore.ts): `src/core/rule/ruleStore.ts`

### Runtime services

- [Request scopes](https://github.com/debanshup/mitm-core/blob/main/src/core/scope/ContextManager.ts): `src/core/scope/ContextManager.ts`
- [Scope mutation](https://github.com/debanshup/mitm-core/blob/main/src/core/scope/ScopeMutator.ts): `src/core/scope/ScopeMutator.ts`
- [TLS contexts](https://github.com/debanshup/mitm-core/blob/main/src/core/security/SecureContextManager.ts): `src/core/security/SecureContextManager.ts`
- [Certificate cache](https://github.com/debanshup/mitm-core/blob/main/src/core/cache/CertificateCacheManager.ts): `src/core/cache/CertificateCacheManager.ts`
- [Response cache](https://github.com/debanshup/mitm-core/blob/main/src/core/cache/ResponseCache.ts): `src/core/cache/ResponseCache.ts`
- [Request state](https://github.com/debanshup/mitm-core/blob/main/src/core/state/StateStore.ts): `src/core/state/StateStore.ts`

### Other components

- **Client**

## Connections

- Client → Proxy API: connects to (evidence: `README.md`)
- Proxy API → Connection middleware: registers (evidence: `src/lib/Proxy.ts`)
- Connection middleware → Request scopes: initializes context (evidence: `src/middleware/middleware.ts`)
- Connection middleware → Pipeline compiler: runs pipeline (evidence: `src/middleware/middleware.ts`)
- Connection middleware → Plugin events: emits lifecycle events (evidence: `src/middleware/middleware.ts`)
- Connection middleware → Proxy events: emits connection events (evidence: `src/middleware/middleware.ts`)
- Connection middleware → Scope mutation: initializes scopes (evidence: `src/middleware/middleware.ts`)
- Pipeline compiler → Lifecycle phases: dispatches phases (evidence: `src/core/pipelines/PipelineCompiler.ts`)
- Pipeline compiler → Request handling: dispatches handlers (evidence: `src/core/pipelines/PipelineCompiler.ts`)
- Pipeline compiler → Response handling: dispatches handlers (evidence: `src/core/pipelines/PipelineCompiler.ts`)
- Pipeline compiler → TLS handshake: dispatches handlers (evidence: `src/core/pipelines/PipelineCompiler.ts`)
- Pipeline compiler → WebSocket bridge: executes bridge (evidence: `src/core/pipelines/PipelineCompiler.ts`)
- Pipeline compiler → Proxy events: reports errors (evidence: `src/core/pipelines/PipelineCompiler.ts`)
- Request handling → HTTP/1 upstream: initiates upstream (evidence: `src/core/handlers/request.handler.ts`)
- Request handling → Scope mutation: mutates scope (evidence: `src/core/handlers/request.handler.ts`)
- Response handling → HTTP/1 outbound: writes response (evidence: `src/core/handlers/response.handler.ts`)
- TLS handshake → TLS contexts: creates TLS context (evidence: `src/core/handlers/handshake.handler.ts`)
- TLS handshake → HTTP/1 inbound: uses inbound bridge (evidence: `src/core/handlers/handshake.handler.ts`)
- TLS handshake → Proxy events: reports lifecycle (evidence: `src/core/handlers/handshake.handler.ts`)
- Plugin lifecycle → Plugin events: uses event hooks (evidence: `src/core/plugin/BasePlugin.ts`)
- TLS contexts → Certificate cache: uses certificate cache (evidence: `src/core/security/SecureContextManager.ts`)
- Streaming responses → Response cache: processes cached responses (evidence: `src/core/transport/http1/streamingResponseHandler.ts`)
- Streaming responses → Scope mutation: updates scope (evidence: `src/core/transport/http1/streamingResponseHandler.ts`)
- Request scopes → Request state: creates lifecycle state (evidence: `src/core/scope/ContextManager.ts`)
- Rule engine → Rule store: uses rule store (evidence: `src/core/rule/RuleEngine.ts`)
- WebSocket bridge → Plugin events: intercepts messages (evidence: `src/core/transport/ws/WSOutboundBridge.ts`)
- WebSocket bridge → Proxy events: emits message events (evidence: `src/core/transport/ws/WSOutboundBridge.ts`)
- WebSocket bridge → Scope mutation: updates scope (evidence: `src/core/transport/ws/WSOutboundBridge.ts`)
- HTTP/1 inbound → Proxy events: emits connection events (evidence: `src/core/transport/http1/H1InboundBridge.ts`)
- HTTP/1 inbound → Request scopes: uses request context (evidence: `src/core/transport/http1/H1InboundBridge.ts`)
- Proxy API → Plugin lifecycle: manages plugins (evidence: `src/lib/Proxy.ts`)
- Proxy API → Request scopes: manages active requests (evidence: `src/lib/Proxy.ts`)
- Proxy API → Proxy events: reports proxy errors (evidence: `src/lib/Proxy.ts`)
- Client → HTTP/2 bridges: uses HTTP/2 (evidence: `README.md`)
- Client → WebSocket bridge: upgrades WebSocket (evidence: `README.md`)
- HTTP/1 upstream → Streaming responses: streams responses (evidence: `README.md`)
- Client → Rule engine: traffic governed by rules (evidence: `README.md`)
- Proxy API → Response cache: optionally caches responses (evidence: `README.md`)