# vaibhav375/protocol-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/vaibhav375/protocol-toolkit
- Repository: https://github.com/vaibhav375/protocol-toolkit

## Overview

Protocol Toolkit is a network-protocol workbench: users run real HTTP, DNS, SMTP, mail-deliverability, and port-scan operations, then inspect the recorded exchange and export captures. The browser UI calls a Python web backend, which dispatches to raw-socket protocol clients and maintains session and capture state. The README documents HTTP/1.1–3, DNS trace and transports, test servers, assistant tool use, pcapng, and HAR. Some backend routes and export wiring are unsampled, so only documented or indexed relationships are shown.

Main entry points: [`protocol_toolkit/webapp/server.py`](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/webapp/server.py) (Web API), [`protocol_toolkit/httpclient.py`](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/httpclient.py) (HTTP Client), [`protocol_toolkit/wire.py`](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/wire.py) (Wire Capture), [`protocol_toolkit/agent.py`](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/agent.py) (Assistant Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Workbench UI"]
  node_webui["Workbench Views<br/>[HttpView.tsx]"]
  node_app["App Shell<br/>[App.tsx]"]
  node_state["UI State<br/>[store.tsx]"]
  node_api["API Client<br/>[api.ts]"]
  node_wireui["Wire Display<br/>[wire.tsx]"]
end

subgraph group_backend["Web Backend"]
  node_server["Web API<br/>[server.py]"]
end

subgraph group_protocols["Protocol Operations"]
  node_http["HTTP Client<br/>[httpclient.py]"]
  node_http2["HTTP/2<br/>[http2.py]"]
  node_http3["HTTP/3<br/>[http3.py]"]
  node_dns["DNS Client<br/>[dnsclient.py]"]
  node_smtp["SMTP Client<br/>[smtpclient.py]"]
  node_mailcheck["Mail Check<br/>[mailcheck.py]"]
  node_scanner["Port Scanner<br/>[scanner.py]"]
  node_assistant["Assistant Agent<br/>[agent.py]"]
  node_llm["LLM Providers<br/>[llm.py]"]
end

subgraph group_inspection["Capture and Analysis"]
  node_wire["Wire Capture<br/>[wire.py]"]
  node_inspector["Inspector UI<br/>[InspectorView.tsx]"]
  node_pcap["pcapng Export<br/>[pcap.py]"]
  node_har["HAR Export<br/>[har.py]"]
  node_explain["Protocol Annotations<br/>[explain.py]"]
end

subgraph group_support["Safety and Lab"]
  node_guard["Network Guard<br/>[guard.py]"]
  node_testservers["Local Test Servers<br/>[testservers.py]"]
  node_net["TCP and TLS<br/>[net.py]"]
end

node_user(("User"))

node_user -->|"runs operations"| node_webui
node_webui -->|"renders in"| node_app
node_app -->|"uses state"| node_state
node_webui -->|"calls API"| node_api
node_api -->|"sends requests"| node_server
node_server -->|"dispatches HTTP"| node_http
node_server -->|"dispatches DNS"| node_dns
node_server -->|"dispatches SMTP"| node_smtp
node_server -->|"dispatches checks"| node_mailcheck
node_server -->|"dispatches scans"| node_scanner
node_server -->|"dispatches assistant"| node_assistant
node_http -->|"uses when negotiated"| node_http2
node_http -.->|"supports HTTP/3"| node_http3
node_mailcheck -->|"queries records"| node_dns
node_mailcheck -->|"fetches policies"| node_http
node_mailcheck -->|"checks SMTP"| node_smtp
node_assistant -->|"requests model steps"| node_llm
node_assistant -->|"invokes tools"| node_http
node_assistant -->|"invokes tools"| node_dns
node_assistant -->|"invokes tools"| node_mailcheck
node_http -->|"opens connections"| node_net
node_dns -->|"uses transport"| node_net
node_smtp -->|"uses transport"| node_net
node_scanner -->|"probes ports"| node_net
node_http -->|"records exchange"| node_wire
node_dns -->|"records exchange"| node_wire
node_smtp -->|"records exchange"| node_wire
node_wireui -->|"formats capture data"| node_api
node_inspector -->|"loads captures"| node_api
node_wire -.->|"exports pcapng"| node_pcap
node_wire -.->|"exports HAR"| node_har
node_wire -->|"annotates bytes"| node_explain
node_server -->|"applies network safety"| node_guard
node_server -->|"controls local servers"| node_testservers

click node_webui "https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/views/HttpView.tsx"
click node_app "https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/App.tsx"
click node_state "https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/lib/store.tsx"
click node_api "https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/lib/api.ts"
click node_wireui "https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/components/wire.tsx"
click node_server "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/webapp/server.py"
click node_http "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/httpclient.py"
click node_http2 "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/http2.py"
click node_http3 "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/http3.py"
click node_dns "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/dnsclient.py"
click node_smtp "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/smtpclient.py"
click node_mailcheck "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/mailcheck.py"
click node_scanner "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/scanner.py"
click node_assistant "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/agent.py"
click node_llm "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/llm.py"
click node_wire "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/wire.py"
click node_inspector "https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/views/InspectorView.tsx"
click node_pcap "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/pcap.py"
click node_har "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/har.py"
click node_explain "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/explain.py"
click node_guard "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/guard.py"
click node_testservers "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/testservers.py"
click node_net "https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/net.py"

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_webui,node_app,node_state,node_api,node_wireui,node_user toneBlue
class node_server toneAmber
class node_http,node_http2,node_http3,node_dns,node_smtp,node_mailcheck,node_scanner,node_assistant,node_llm toneMint
class node_wire,node_inspector,node_pcap,node_har,node_explain toneRose
class node_guard,node_testservers,node_net toneIndigo
```

## Components

### Workbench UI

- [Workbench Views](https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/views/HttpView.tsx): `web/src/views/HttpView.tsx`
- [App Shell](https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [UI State](https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/lib/store.tsx): `web/src/lib/store.tsx`
- [API Client](https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Wire Display](https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/components/wire.tsx): `web/src/components/wire.tsx`

### Web Backend

- [Web API](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/webapp/server.py): `protocol_toolkit/webapp/server.py`

### Protocol Operations

- [HTTP Client](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/httpclient.py): `protocol_toolkit/httpclient.py`
- [HTTP/2](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/http2.py): `protocol_toolkit/http2.py`
- [HTTP/3](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/http3.py): `protocol_toolkit/http3.py`
- [DNS Client](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/dnsclient.py): `protocol_toolkit/dnsclient.py`
- [SMTP Client](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/smtpclient.py): `protocol_toolkit/smtpclient.py`
- [Mail Check](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/mailcheck.py): `protocol_toolkit/mailcheck.py`
- [Port Scanner](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/scanner.py): `protocol_toolkit/scanner.py`
- [Assistant Agent](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/agent.py): `protocol_toolkit/agent.py`
- [LLM Providers](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/llm.py): `protocol_toolkit/llm.py`

### Capture and Analysis

- [Wire Capture](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/wire.py): `protocol_toolkit/wire.py`
- [Inspector UI](https://github.com/vaibhav375/protocol-toolkit/blob/main/web/src/views/InspectorView.tsx): `web/src/views/InspectorView.tsx`
- [pcapng Export](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/pcap.py): `protocol_toolkit/pcap.py`
- [HAR Export](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/har.py): `protocol_toolkit/har.py`
- [Protocol Annotations](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/explain.py): `protocol_toolkit/explain.py`

### Safety and Lab

- [Network Guard](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/guard.py): `protocol_toolkit/guard.py`
- [Local Test Servers](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/testservers.py): `protocol_toolkit/testservers.py`
- [TCP and TLS](https://github.com/vaibhav375/protocol-toolkit/blob/main/protocol_toolkit/net.py): `protocol_toolkit/net.py`

### Other components

- **User**

## Connections

- User → Workbench Views: runs operations (evidence: `README.md`)
- Workbench Views → App Shell: renders in (evidence: `web/src/App.tsx`)
- App Shell → UI State: uses state (evidence: `web/src/App.tsx`)
- Workbench Views → API Client: calls API (evidence: `web/src/views/HttpView.tsx`)
- API Client → Web API: sends requests (evidence: `web/src/lib/api.ts`)
- Web API → HTTP Client: dispatches HTTP (evidence: `protocol_toolkit/webapp/server.py`)
- Web API → DNS Client: dispatches DNS (evidence: `protocol_toolkit/webapp/server.py`)
- Web API → SMTP Client: dispatches SMTP (evidence: `protocol_toolkit/webapp/server.py`)
- Web API → Mail Check: dispatches checks (evidence: `protocol_toolkit/webapp/server.py`)
- Web API → Port Scanner: dispatches scans (evidence: `protocol_toolkit/webapp/server.py`)
- Web API → Assistant Agent: dispatches assistant (evidence: `protocol_toolkit/webapp/server.py`)
- HTTP Client → HTTP/2: uses when negotiated (evidence: `protocol_toolkit/httpclient.py`)
- HTTP Client → HTTP/3: supports HTTP/3 (evidence: `README.md`)
- Mail Check → DNS Client: queries records (evidence: `protocol_toolkit/mailcheck.py`)
- Mail Check → HTTP Client: fetches policies (evidence: `protocol_toolkit/mailcheck.py`)
- Mail Check → SMTP Client: checks SMTP (evidence: `protocol_toolkit/mailcheck.py`)
- Assistant Agent → LLM Providers: requests model steps (evidence: `protocol_toolkit/agent.py`)
- Assistant Agent → HTTP Client: invokes tools (evidence: `protocol_toolkit/agent.py`)
- Assistant Agent → DNS Client: invokes tools (evidence: `protocol_toolkit/agent.py`)
- Assistant Agent → Mail Check: invokes tools (evidence: `protocol_toolkit/agent.py`)
- HTTP Client → TCP and TLS: opens connections (evidence: `protocol_toolkit/httpclient.py`)
- DNS Client → TCP and TLS: uses transport (evidence: `protocol_toolkit/dnsclient.py`)
- SMTP Client → TCP and TLS: uses transport (evidence: `protocol_toolkit/smtpclient.py`)
- Port Scanner → TCP and TLS: probes ports (evidence: `protocol_toolkit/scanner.py`)
- HTTP Client → Wire Capture: records exchange (evidence: `protocol_toolkit/httpclient.py`)
- DNS Client → Wire Capture: records exchange (evidence: `protocol_toolkit/dnsclient.py`)
- SMTP Client → Wire Capture: records exchange (evidence: `protocol_toolkit/smtpclient.py`)
- Wire Display → API Client: formats capture data (evidence: `web/src/components/wire.tsx`)
- Inspector UI → API Client: loads captures (evidence: `web/src/views/InspectorView.tsx`)
- Wire Capture → pcapng Export: exports pcapng (evidence: `README.md`)
- Wire Capture → HAR Export: exports HAR (evidence: `README.md`)
- Wire Capture → Protocol Annotations: annotates bytes (evidence: `protocol_toolkit/har.py`)
- Web API → Network Guard: applies network safety (evidence: `protocol_toolkit/webapp/server.py`)
- Web API → Local Test Servers: controls local servers (evidence: `protocol_toolkit/webapp/server.py`)
