# waterbottles792/anzenna architecture

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

- Interactive diagram: https://gitdiagram.com/waterbottles792/anzenna
- Repository: https://github.com/waterbottles792/anzenna

## Overview

Anzenna is a prompt-injection and sensitive-data scanning product, exposed through an HTTP API and an MCP server. Its principal workflow accepts text at an entry point, runs layered detection and scoring, then returns a structured risk result; the API also handles keys, usage limits, scan logs, and subscription billing. Detection includes deterministic heuristics, PII/secrets and encoding checks, an optional ML classifier, LLM judging, and OWASP tagging. The graph reflects sampled source and SOURCE INDEX references; unsampled subsystem details and their internal links are limited accordingly.

Main entry points: [`api/main.py`](https://github.com/waterbottles792/anzenna/blob/main/api/main.py) (API Service), [`engine/pipeline.py`](https://github.com/waterbottles792/anzenna/blob/main/engine/pipeline.py) (Scan Pipeline), [`engine/layer1.py`](https://github.com/waterbottles792/anzenna/blob/main/engine/layer1.py) (Deterministic Layer), [`engine/scan_text.py`](https://github.com/waterbottles792/anzenna/blob/main/engine/scan_text.py) (Text Scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_api_service["API Service<br/>[main.py]"]
end

subgraph group_detection["Detection Engine"]
  node_pipeline["Scan Pipeline<br/>[pipeline.py]"]
  node_scan_text["Text Scanner<br/>[scan_text.py]"]
  node_layer1["Deterministic Layer<br/>[layer1.py]"]
  node_heuristics["Phrase Rules<br/>[heuristics.py]"]
  node_encoding["Encoding Checks<br/>[encoding.py]"]
  node_pii["PII and Secrets<br/>[pii.py]"]
  node_classifier["ML Classifier<br/>[classifier.py]"]
  node_judge["LLM Judge<br/>[llm_judge.py]"]
  node_owasp["OWASP Tags<br/>[owasp.py]"]
end

subgraph group_mcp["MCP Integration"]
  node_mcp_server["MCP Server<br/>[server.py]"]
  node_tool_scanner["Tool Scanner<br/>[mcp_tools.py]"]
end

subgraph group_commerce["Billing and Storage"]
  node_billing["Billing Logic<br/>[billing.py]"]
  node_db_helpers["Database CRUD<br/>[db.py]"]
  node_models["Data Models<br/>[models.py]"]
end

node_client(("API Client"))
node_database[("Application Database")]
node_dodo["Dodo Payments"]
node_mcp_host(("MCP Host"))

node_client -->|"submits scans"| node_api_service
node_api_service -->|"scans text"| node_pipeline
node_pipeline -->|"runs first"| node_layer1
node_pipeline -->|"runs conditionally"| node_classifier
node_pipeline -->|"escalates ambiguities"| node_judge
node_pipeline -->|"maps categories"| node_owasp
node_layer1 -->|"matches rules"| node_heuristics
node_layer1 -->|"checks obfuscation"| node_encoding
node_layer1 -->|"detects sensitive data"| node_pii
node_scan_text -->|"scans text"| node_layer1
node_scan_text -->|"escalates findings"| node_judge
node_scan_text -->|"tags results"| node_owasp
node_mcp_host -.->|"invokes tools"| node_mcp_server
node_mcp_server -->|"scans text"| node_scan_text
node_mcp_server -->|"checks tool descriptions"| node_tool_scanner
node_tool_scanner -->|"shares scan logic"| node_scan_text
node_api_service -->|"reads and writes"| node_db_helpers
node_db_helpers -->|"uses entities"| node_models
node_db_helpers -.->|"persists records"| node_database
node_api_service -->|"starts checkout"| node_billing
node_billing -->|"updates plans"| node_db_helpers
node_billing -.->|"creates sessions"| node_dodo
node_api_service -->|"verifies webhooks"| node_dodo

click node_api_service "https://github.com/waterbottles792/anzenna/blob/main/api/main.py"
click node_billing "https://github.com/waterbottles792/anzenna/blob/main/api/billing.py"
click node_db_helpers "https://github.com/waterbottles792/anzenna/blob/main/api/db.py"
click node_models "https://github.com/waterbottles792/anzenna/blob/main/api/models.py"
click node_pipeline "https://github.com/waterbottles792/anzenna/blob/main/engine/pipeline.py"
click node_scan_text "https://github.com/waterbottles792/anzenna/blob/main/engine/scan_text.py"
click node_layer1 "https://github.com/waterbottles792/anzenna/blob/main/engine/layer1.py"
click node_heuristics "https://github.com/waterbottles792/anzenna/blob/main/engine/heuristics.py"
click node_encoding "https://github.com/waterbottles792/anzenna/blob/main/engine/encoding.py"
click node_pii "https://github.com/waterbottles792/anzenna/blob/main/engine/pii.py"
click node_classifier "https://github.com/waterbottles792/anzenna/blob/main/engine/classifier.py"
click node_judge "https://github.com/waterbottles792/anzenna/blob/main/engine/llm_judge.py"
click node_owasp "https://github.com/waterbottles792/anzenna/blob/main/engine/owasp.py"
click node_mcp_server "https://github.com/waterbottles792/anzenna/blob/main/sdks/mcp/server.py"
click node_tool_scanner "https://github.com/waterbottles792/anzenna/blob/main/engine/mcp_tools.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_api_service,node_client toneBlue
class node_pipeline,node_scan_text,node_layer1,node_heuristics,node_encoding,node_pii,node_classifier,node_judge,node_owasp,node_database toneAmber
class node_mcp_server,node_tool_scanner toneMint
class node_billing,node_db_helpers,node_models toneRose
class node_dodo,node_mcp_host toneIndigo
```

## Components

### HTTP API

- [API Service](https://github.com/waterbottles792/anzenna/blob/main/api/main.py): `api/main.py`

### Detection Engine

- [Scan Pipeline](https://github.com/waterbottles792/anzenna/blob/main/engine/pipeline.py): `engine/pipeline.py`
- [Text Scanner](https://github.com/waterbottles792/anzenna/blob/main/engine/scan_text.py): `engine/scan_text.py`
- [Deterministic Layer](https://github.com/waterbottles792/anzenna/blob/main/engine/layer1.py): `engine/layer1.py`
- [Phrase Rules](https://github.com/waterbottles792/anzenna/blob/main/engine/heuristics.py): `engine/heuristics.py`
- [Encoding Checks](https://github.com/waterbottles792/anzenna/blob/main/engine/encoding.py): `engine/encoding.py`
- [PII and Secrets](https://github.com/waterbottles792/anzenna/blob/main/engine/pii.py): `engine/pii.py`
- [ML Classifier](https://github.com/waterbottles792/anzenna/blob/main/engine/classifier.py): `engine/classifier.py`
- [LLM Judge](https://github.com/waterbottles792/anzenna/blob/main/engine/llm_judge.py): `engine/llm_judge.py`
- [OWASP Tags](https://github.com/waterbottles792/anzenna/blob/main/engine/owasp.py): `engine/owasp.py`

### MCP Integration

- [MCP Server](https://github.com/waterbottles792/anzenna/blob/main/sdks/mcp/server.py): `sdks/mcp/server.py`
- [Tool Scanner](https://github.com/waterbottles792/anzenna/blob/main/engine/mcp_tools.py): `engine/mcp_tools.py`

### Billing and Storage

- [Billing Logic](https://github.com/waterbottles792/anzenna/blob/main/api/billing.py): `api/billing.py`
- [Database CRUD](https://github.com/waterbottles792/anzenna/blob/main/api/db.py): `api/db.py`
- [Data Models](https://github.com/waterbottles792/anzenna/blob/main/api/models.py): `api/models.py`

### Other components

- **API Client**
- **Application Database**
- **Dodo Payments**
- **MCP Host**

## Connections

- API Client → API Service: submits scans (evidence: `api/main.py`)
- API Service → Scan Pipeline: scans text (evidence: `api/main.py`)
- Scan Pipeline → Deterministic Layer: runs first (evidence: `engine/pipeline.py`)
- Scan Pipeline → ML Classifier: runs conditionally (evidence: `engine/pipeline.py`)
- Scan Pipeline → LLM Judge: escalates ambiguities (evidence: `engine/pipeline.py`)
- Scan Pipeline → OWASP Tags: maps categories (evidence: `engine/pipeline.py`)
- Deterministic Layer → Phrase Rules: matches rules (evidence: `engine/layer1.py`)
- Deterministic Layer → Encoding Checks: checks obfuscation (evidence: `engine/layer1.py`)
- Deterministic Layer → PII and Secrets: detects sensitive data (evidence: `engine/layer1.py`)
- Text Scanner → Deterministic Layer: scans text (evidence: `engine/scan_text.py`)
- Text Scanner → LLM Judge: escalates findings (evidence: `engine/scan_text.py`)
- Text Scanner → OWASP Tags: tags results (evidence: `engine/scan_text.py`)
- MCP Host → MCP Server: invokes tools (evidence: `sdks/mcp/server.py`)
- MCP Server → Text Scanner: scans text (evidence: `sdks/mcp/server.py`)
- MCP Server → Tool Scanner: checks tool descriptions (evidence: `sdks/mcp/server.py`)
- Tool Scanner → Text Scanner: shares scan logic (evidence: `engine/mcp_tools.py`)
- API Service → Database CRUD: reads and writes (evidence: `api/main.py`)
- Database CRUD → Data Models: uses entities (evidence: `api/db.py`)
- Database CRUD → Application Database: persists records (evidence: `api/db.py`)
- API Service → Billing Logic: starts checkout (evidence: `api/main.py`)
- Billing Logic → Database CRUD: updates plans (evidence: `api/billing.py`)
- Billing Logic → Dodo Payments: creates sessions (evidence: `api/billing.py`)
- API Service → Dodo Payments: verifies webhooks (evidence: `api/main.py`)
