# pavankalyanv5/claude-code-privacy-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/pavankalyanv5/claude-code-privacy-proxy
- Repository: https://github.com/pavankalyanv5/claude-code-privacy-proxy

## Overview

This is a local privacy proxy for Claude Code: it transforms sensitive request content and metadata before forwarding requests, then restores reversible aliases in streamed responses so local tools can still operate on real values. The runtime also supports optional IP-masking egress, residue scrubbing, durable audit records, retention, and a local dashboard. The graph emphasizes documented capabilities and relationships visible in excerpts, the README, or the SOURCE INDEX; unsampled wiring is omitted where it cannot be established.

Main entry points: [`src/start.js`](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/start.js) (Runtime Startup), [`src/server.js`](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/server.js) (Local Proxy), [`src/pipeline.js`](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/pipeline.js) (Render Pipeline), [`src/egress.js`](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/egress.js) (Egress Tunnel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_proxy["Proxy Runtime"]
  node_start["Runtime Startup<br/>[start.js]"]
  node_proxy_server["Local Proxy<br/>[server.js]"]
end

subgraph group_transform["Privacy Transforms"]
  node_rules["Redaction Rules<br/>[rules.js]"]
  node_pipeline["Render Pipeline<br/>[pipeline.js]"]
  node_spans["Redaction Spans<br/>[spans.js]"]
  node_aliases["Identity Aliases<br/>[aliases.js]"]
  node_normalize["Metadata Normalization<br/>[normalize.js]"]
  node_walk["Outbound Walk<br/>[walk.js]"]
  node_resolver["Inbound Resolver<br/>[resolver.js]"]
  node_headers["Header Sanitization<br/>[headers.js]"]
  node_sse["Stream Restoration<br/>[sse.js]"]
end

subgraph group_egress["Network Egress"]
  node_egress_tunnel["Egress Tunnel<br/>[egress.js]"]
  node_providers["Tunnel Discovery<br/>[providers.js]"]
  node_pool["Proxy Pool<br/>[pool.js]"]
end

subgraph group_residue["Residue Governance"]
  node_scrubber["Residue Scrubber<br/>[scrub-residue.js]"]
  node_residue_index[("Clean-File Index<br/>[residue-index.js]")]
  node_residue_log[("Residue Job Log<br/>[residue-log.js]")]
  node_retention["Retention Policy<br/>[retention.js]"]
end

subgraph group_operations["Operations and Audit"]
  node_dashboard["Audit Dashboard<br/>[dash.js]"]
  node_supervisor["Process Supervisor<br/>[supervise.js]"]
  node_doctor["Privacy Diagnostics<br/>[doctor.js]"]
  node_audit["Audit Records<br/>[audit.js]"]
end

node_claude(("Claude Code"))
node_upstream(("Claude API"))

node_claude -->|"sends requests"| node_proxy_server
node_start -->|"starts"| node_proxy_server
node_start -->|"loads"| node_rules
node_start -->|"configures"| node_walk
node_start -->|"configures"| node_resolver
node_start -->|"configures"| node_egress_tunnel
node_proxy_server -->|"forwards requests"| node_upstream
node_proxy_server -->|"transforms streams"| node_sse
node_proxy_server -->|"routes dashboard"| node_dashboard
node_walk -->|"renders outbound"| node_pipeline
node_resolver -->|"uses shared config"| node_pipeline
node_pipeline -->|"redacts text"| node_spans
node_pipeline -->|"aliases identity"| node_aliases
node_pipeline -->|"normalizes values"| node_normalize
node_proxy_server -->|"sanitizes headers"| node_headers
node_resolver -->|"restores tool values"| node_claude
node_proxy_server -.->|"tunnels upstream"| node_egress_tunnel
node_providers -->|"supplies endpoints"| node_egress_tunnel
node_pool -.->|"supplies proxies"| node_egress_tunnel
node_scrubber -->|"reuses transforms"| node_pipeline
node_scrubber -->|"marks clean files"| node_residue_index
node_scrubber -->|"records passes"| node_residue_log
node_retention -.->|"limits history"| node_residue_log
node_dashboard -->|"shows job history"| node_residue_log
node_start -->|"configures"| node_retention
node_start -->|"configures"| node_audit
node_doctor -->|"checks rules"| node_rules
node_doctor -->|"checks audit history"| node_residue_log
node_start -->|"configures supervision"| node_supervisor

click node_start "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/start.js"
click node_proxy_server "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/server.js"
click node_rules "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/rules.js"
click node_pipeline "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/pipeline.js"
click node_spans "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/spans.js"
click node_aliases "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/aliases.js"
click node_normalize "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/normalize.js"
click node_walk "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/walk.js"
click node_resolver "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/resolver.js"
click node_headers "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/headers.js"
click node_sse "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/sse.js"
click node_egress_tunnel "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/egress.js"
click node_providers "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/providers.js"
click node_pool "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/pool.js"
click node_scrubber "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/scrub-residue.js"
click node_residue_index "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/residue-index.js"
click node_residue_log "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/residue-log.js"
click node_retention "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/retention.js"
click node_dashboard "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/dash.js"
click node_supervisor "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/supervise.js"
click node_doctor "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/doctor.js"
click node_audit "https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/audit.js"

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_start,node_proxy_server toneBlue
class node_rules,node_pipeline,node_spans,node_aliases,node_normalize,node_walk,node_resolver,node_headers,node_sse toneAmber
class node_egress_tunnel,node_providers,node_pool,node_upstream toneMint
class node_scrubber,node_residue_index,node_residue_log,node_retention toneRose
class node_dashboard,node_supervisor,node_doctor,node_audit,node_claude toneIndigo
```

## Components

### Proxy Runtime

- [Runtime Startup](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/start.js): `src/start.js`
- [Local Proxy](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/server.js): `src/server.js`

### Privacy Transforms

- [Redaction Rules](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/rules.js): `src/rules.js`
- [Render Pipeline](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/pipeline.js): `src/pipeline.js`
- [Redaction Spans](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/spans.js): `src/spans.js`
- [Identity Aliases](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/aliases.js): `src/aliases.js`
- [Metadata Normalization](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/normalize.js): `src/normalize.js`
- [Outbound Walk](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/walk.js): `src/walk.js`
- [Inbound Resolver](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/resolver.js): `src/resolver.js`
- [Header Sanitization](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/headers.js): `src/headers.js`
- [Stream Restoration](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/sse.js): `src/sse.js`

### Network Egress

- [Egress Tunnel](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/egress.js): `src/egress.js`
- [Tunnel Discovery](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/providers.js): `src/providers.js`
- [Proxy Pool](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/pool.js): `src/pool.js`

### Residue Governance

- [Residue Scrubber](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/scrub-residue.js): `src/scrub-residue.js`
- [Clean-File Index](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/residue-index.js): `src/residue-index.js`
- [Residue Job Log](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/residue-log.js): `src/residue-log.js`
- [Retention Policy](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/retention.js): `src/retention.js`

### Operations and Audit

- [Audit Dashboard](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/dash.js): `src/dash.js`
- [Process Supervisor](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/supervise.js): `src/supervise.js`
- [Privacy Diagnostics](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/doctor.js): `src/doctor.js`
- [Audit Records](https://github.com/pavankalyanv5/claude-code-privacy-proxy/blob/main/src/audit.js): `src/audit.js`

### Other components

- **Claude Code**
- **Claude API**

## Connections

- Claude Code → Local Proxy: sends requests (evidence: `README.md`)
- Runtime Startup → Local Proxy: starts (evidence: `src/start.js`)
- Runtime Startup → Redaction Rules: loads (evidence: `src/start.js`)
- Runtime Startup → Outbound Walk: configures (evidence: `src/start.js`)
- Runtime Startup → Inbound Resolver: configures (evidence: `src/start.js`)
- Runtime Startup → Egress Tunnel: configures (evidence: `src/start.js`)
- Local Proxy → Claude API: forwards requests (evidence: `README.md`)
- Local Proxy → Stream Restoration: transforms streams (evidence: `src/server.js`)
- Local Proxy → Audit Dashboard: routes dashboard (evidence: `src/server.js`)
- Outbound Walk → Render Pipeline: renders outbound (evidence: `src/pipeline.js`)
- Inbound Resolver → Render Pipeline: uses shared config (evidence: `src/pipeline.js`)
- Render Pipeline → Redaction Spans: redacts text (evidence: `src/pipeline.js`)
- Render Pipeline → Identity Aliases: aliases identity (evidence: `src/pipeline.js`)
- Render Pipeline → Metadata Normalization: normalizes values (evidence: `src/pipeline.js`)
- Local Proxy → Header Sanitization: sanitizes headers (evidence: `src/server.js`)
- Inbound Resolver → Claude Code: restores tool values (evidence: `README.md`)
- Local Proxy → Egress Tunnel: tunnels upstream
- Tunnel Discovery → Egress Tunnel: supplies endpoints (evidence: `src/providers.js`)
- Proxy Pool → Egress Tunnel: supplies proxies (evidence: `src/pool.js`)
- Residue Scrubber → Render Pipeline: reuses transforms (evidence: `src/scrub-residue.js`)
- Residue Scrubber → Clean-File Index: marks clean files (evidence: `src/scrub-residue.js`)
- Residue Scrubber → Residue Job Log: records passes (evidence: `src/residue-log.js`)
- Retention Policy → Residue Job Log: limits history
- Audit Dashboard → Residue Job Log: shows job history (evidence: `src/dash.js`)
- Runtime Startup → Retention Policy: configures (evidence: `src/start.js`)
- Runtime Startup → Audit Records: configures (evidence: `src/start.js`)
- Privacy Diagnostics → Redaction Rules: checks rules (evidence: `src/doctor.js`)
- Privacy Diagnostics → Residue Job Log: checks audit history (evidence: `src/doctor.js`)
- Runtime Startup → Process Supervisor: configures supervision (evidence: `src/start.js`)
