# marksman8/phishing_guard architecture

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

- Interactive diagram: https://gitdiagram.com/marksman8/phishing_guard
- Repository: https://github.com/marksman8/phishing_guard

## Overview

PhishGuard takes a pasted raw email through deterministic parsing and injection detection, evidence retrieval, external tool verification, risk/confidence scoring, and a threshold-based decision. It returns a cited recommendation and audit trail, escalating low-confidence cases for human review. The graph and node excerpts establish the main runtime flow; README capability descriptions support the tool and escalation branches. Some integrations and UI details are documented but their implementation was not sampled.

Main entry points: [`phishguard/graph.py`](https://github.com/marksman8/phishing_guard/blob/main/phishguard/graph.py) (Analysis graph), [`phishguard/nodes/decision.py`](https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/decision.py) (Decision and citations), [`phishguard/llm/factory.py`](https://github.com/marksman8/phishing_guard/blob/main/phishguard/llm/factory.py) (Provider selection), [`phishguard/nodes/analyzer.py`](https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/analyzer.py) (Email analyzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Email intake"]
  node_app["Paste UI<br/>[app.py]"]
  node_orchestrator["Analysis graph<br/>[graph.py]"]
  node_state["Case state<br/>[state.py]"]
  node_analyzer["Email analyzer<br/>[analyzer.py]"]
  node_parser["Email parser<br/>[parsing.py]"]
  node_injection["Injection detector<br/>[injection.py]"]
end

subgraph group_evidence["Evidence gathering"]
  node_retriever["Evidence retriever<br/>[retriever.py]"]
  node_vectorstore["Pattern index access<br/>[vectorstore.py]"]
  node_pattern_db[("Chroma pattern store")]
  node_verifier["Tool verifier<br/>[verifier.py]"]
end

subgraph group_assessment["Risk assessment"]
  node_risk["Risk and confidence<br/>[risk.py]"]
end

subgraph group_decision["Decision and audit"]
  node_decision["Decision and citations<br/>[decision.py]"]
  node_audit["Redacted trace<br/>[state.py]"]
end

subgraph group_integrations["Models and tools"]
  node_mcp_client["MCP tool client<br/>[mcp_client.py]"]
  node_mcp_server["MCP tool server<br/>[mcp_server.py]"]
  node_llm_api["LLM provider interface<br/>[base.py]"]
  node_llm_factory["Provider selection<br/>[factory.py]"]
  node_llm_backends["LLM backends<br/>[ollama.py]"]
end

node_analyst(("Email analyst"))
node_tool_services["Domain and URL checks"]
node_human_review(("Human review"))
node_result["Classification and recommendation"]

node_analyst -->|"pastes email"| node_app
node_app -->|"runs analysis"| node_orchestrator
node_orchestrator -->|"starts at"| node_analyzer
node_analyzer -->|"parses email"| node_parser
node_analyzer -->|"detects injection"| node_injection
node_orchestrator -->|"routes to"| node_retriever
node_retriever -->|"queries patterns"| node_vectorstore
node_vectorstore -.->|"reads index"| node_pattern_db
node_orchestrator -->|"routes to"| node_verifier
node_verifier -->|"calls tools"| node_mcp_client
node_mcp_client -->|"starts subprocess"| node_mcp_server
node_mcp_server -->|"checks domains and URLs"| node_tool_services
node_orchestrator -->|"routes to"| node_risk
node_risk -->|"reads tool results"| node_verifier
node_risk -->|"requests content flags"| node_llm_factory
node_decision -->|"requests recommendation"| node_llm_factory
node_llm_factory -->|"creates provider"| node_llm_api
node_llm_factory -->|"selects backend"| node_llm_backends
node_orchestrator -->|"routes to"| node_decision
node_decision -->|"escalates case"| node_mcp_client
node_mcp_server -->|"creates review ticket"| node_human_review
node_decision -->|"returns classification"| node_result
node_orchestrator -->|"persists trace"| node_audit
node_state -->|"redacts trace entries"| node_audit

click node_app "https://github.com/marksman8/phishing_guard/blob/main/app.py"
click node_orchestrator "https://github.com/marksman8/phishing_guard/blob/main/phishguard/graph.py"
click node_state "https://github.com/marksman8/phishing_guard/blob/main/phishguard/state.py"
click node_analyzer "https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/analyzer.py"
click node_parser "https://github.com/marksman8/phishing_guard/blob/main/phishguard/parsing.py"
click node_injection "https://github.com/marksman8/phishing_guard/blob/main/phishguard/injection.py"
click node_retriever "https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/retriever.py"
click node_vectorstore "https://github.com/marksman8/phishing_guard/blob/main/phishguard/vectorstore.py"
click node_pattern_db "https://github.com/marksman8/phishing_guard/blob/main/data/seed_patterns.jsonl"
click node_verifier "https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/verifier.py"
click node_mcp_client "https://github.com/marksman8/phishing_guard/blob/main/phishguard/mcp_client.py"
click node_mcp_server "https://github.com/marksman8/phishing_guard/blob/main/mcp_server.py"
click node_risk "https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/risk.py"
click node_llm_api "https://github.com/marksman8/phishing_guard/blob/main/phishguard/llm/base.py"
click node_llm_factory "https://github.com/marksman8/phishing_guard/blob/main/phishguard/llm/factory.py"
click node_llm_backends "https://github.com/marksman8/phishing_guard/blob/main/phishguard/llm/ollama.py"
click node_decision "https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/decision.py"
click node_audit "https://github.com/marksman8/phishing_guard/blob/main/phishguard/state.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_app,node_orchestrator,node_state,node_analyzer,node_parser,node_injection,node_human_review toneBlue
class node_retriever,node_vectorstore,node_pattern_db,node_verifier toneAmber
class node_risk toneMint
class node_decision,node_audit toneRose
class node_mcp_client,node_mcp_server,node_llm_api,node_llm_factory,node_llm_backends,node_analyst,node_tool_services,node_result toneIndigo
```

## Components

### Email intake

- [Paste UI](https://github.com/marksman8/phishing_guard/blob/main/app.py): `app.py`
- [Analysis graph](https://github.com/marksman8/phishing_guard/blob/main/phishguard/graph.py): `phishguard/graph.py`
- [Case state](https://github.com/marksman8/phishing_guard/blob/main/phishguard/state.py): `phishguard/state.py`
- [Email analyzer](https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/analyzer.py): `phishguard/nodes/analyzer.py`
- [Email parser](https://github.com/marksman8/phishing_guard/blob/main/phishguard/parsing.py): `phishguard/parsing.py`
- [Injection detector](https://github.com/marksman8/phishing_guard/blob/main/phishguard/injection.py): `phishguard/injection.py`

### Evidence gathering

- [Evidence retriever](https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/retriever.py): `phishguard/nodes/retriever.py`
- [Pattern index access](https://github.com/marksman8/phishing_guard/blob/main/phishguard/vectorstore.py): `phishguard/vectorstore.py`
- [Chroma pattern store](https://github.com/marksman8/phishing_guard/blob/main/data/seed_patterns.jsonl): `data/seed_patterns.jsonl`
- [Tool verifier](https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/verifier.py): `phishguard/nodes/verifier.py`

### Risk assessment

- [Risk and confidence](https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/risk.py): `phishguard/nodes/risk.py`

### Decision and audit

- [Decision and citations](https://github.com/marksman8/phishing_guard/blob/main/phishguard/nodes/decision.py): `phishguard/nodes/decision.py`
- [Redacted trace](https://github.com/marksman8/phishing_guard/blob/main/phishguard/state.py): `phishguard/state.py`

### Models and tools

- [MCP tool client](https://github.com/marksman8/phishing_guard/blob/main/phishguard/mcp_client.py): `phishguard/mcp_client.py`
- [MCP tool server](https://github.com/marksman8/phishing_guard/blob/main/mcp_server.py): `mcp_server.py`
- [LLM provider interface](https://github.com/marksman8/phishing_guard/blob/main/phishguard/llm/base.py): `phishguard/llm/base.py`
- [Provider selection](https://github.com/marksman8/phishing_guard/blob/main/phishguard/llm/factory.py): `phishguard/llm/factory.py`
- [LLM backends](https://github.com/marksman8/phishing_guard/blob/main/phishguard/llm/ollama.py): `phishguard/llm/ollama.py`

### Other components

- **Email analyst**
- **Domain and URL checks**
- **Human review**
- **Classification and recommendation**

## Connections

- Email analyst → Paste UI: pastes email (evidence: `README.md`)
- Paste UI → Analysis graph: runs analysis (evidence: `app.py`)
- Analysis graph → Email analyzer: starts at (evidence: `phishguard/graph.py`)
- Email analyzer → Email parser: parses email (evidence: `phishguard/nodes/analyzer.py`)
- Email analyzer → Injection detector: detects injection (evidence: `phishguard/nodes/analyzer.py`)
- Analysis graph → Evidence retriever: routes to (evidence: `phishguard/graph.py`)
- Evidence retriever → Pattern index access: queries patterns (evidence: `phishguard/nodes/retriever.py`)
- Pattern index access → Chroma pattern store: reads index
- Analysis graph → Tool verifier: routes to (evidence: `phishguard/graph.py`)
- Tool verifier → MCP tool client: calls tools (evidence: `phishguard/nodes/verifier.py`)
- MCP tool client → MCP tool server: starts subprocess (evidence: `phishguard/mcp_client.py`)
- MCP tool server → Domain and URL checks: checks domains and URLs (evidence: `README.md`)
- Analysis graph → Risk and confidence: routes to (evidence: `phishguard/graph.py`)
- Risk and confidence → Tool verifier: reads tool results (evidence: `phishguard/nodes/risk.py`)
- Risk and confidence → Provider selection: requests content flags (evidence: `phishguard/nodes/risk.py`)
- Decision and citations → Provider selection: requests recommendation (evidence: `phishguard/nodes/decision.py`)
- Provider selection → LLM provider interface: creates provider (evidence: `phishguard/llm/factory.py`)
- Provider selection → LLM backends: selects backend (evidence: `phishguard/llm/factory.py`)
- Analysis graph → Decision and citations: routes to (evidence: `phishguard/graph.py`)
- Decision and citations → MCP tool client: escalates case (evidence: `phishguard/nodes/decision.py`)
- MCP tool server → Human review: creates review ticket (evidence: `README.md`)
- Decision and citations → Classification and recommendation: returns classification (evidence: `README.md`)
- Analysis graph → Redacted trace: persists trace (evidence: `phishguard/graph.py`)
- Case state → Redacted trace: redacts trace entries (evidence: `phishguard/state.py`)
