# ruchikarom/llmsentry architecture

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

- Interactive diagram: https://gitdiagram.com/ruchikarom/llmsentry
- Repository: https://github.com/ruchikarom/llmsentry

## Overview

llmsentry is a prompt-injection firewall with two user-facing modes: a drop-in HTTP proxy and a library wrapper. In either mode, messages are scanned, risk-scored with provenance weighting, and compared with block/flag thresholds; the proxy rejects blocked requests or forwards allowed ones to Groq and exposes recent decisions. The README documents a broader set of detection signals than the sampled scanner excerpt shows, so signal families are represented at a high level. Proxy logging is in-memory, not a persistent store.

Main entry points: [`llmsentry/llmsentry/proxy.py`](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/proxy.py) (HTTP proxy), [`llmsentry/llmsentry/scanner.py`](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py) (Message scanning), [`llmsentry/llmsentry/client.py`](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/client.py) (Guarded client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Entry points"]
  node_proxy["HTTP proxy<br/>[proxy.py]"]
  node_library["Guarded client<br/>[client.py]"]
end

subgraph group_detection["Scanning and decisions"]
  node_guard["Message guard<br/>[client.py]"]
  node_message_scan["Message scanning<br/>[scanner.py]"]
  node_provenance["Source provenance<br/>[scanner.py]"]
  node_text_signals["Text signals<br/>[scanner.py]"]
  node_action_signals["Agent action signals<br/>[scanner.py]"]
  node_scoring["Risk scoring<br/>[scanner.py]"]
  node_decision["Threshold verdict<br/>[client.py]"]
end

subgraph group_proxy_state["Proxy and state"]
  node_recent_log[("Recent decisions<br/>[proxy.py]")]
end

node_application(("LLM application"))
node_upstream["Groq API"]
node_inspect(("Operator"))

node_application -->|"sends requests"| node_proxy
node_proxy -->|"checks messages"| node_guard
node_application -->|"calls completions"| node_library
node_library -->|"checks messages"| node_guard
node_guard -->|"scans messages"| node_message_scan
node_message_scan -->|"maps sources"| node_provenance
node_message_scan -->|"checks content"| node_text_signals
node_message_scan -->|"checks actions"| node_action_signals
node_message_scan -->|"combines signal weights"| node_scoring
node_provenance -->|"weights by source"| node_scoring
node_scoring -->|"returns scores"| node_decision
node_guard -->|"applies thresholds"| node_decision
node_decision -->|"returns verdict"| node_proxy
node_decision -->|"returns verdict"| node_library
node_proxy -->|"records decisions"| node_recent_log
node_proxy -->|"forwards allowed requests"| node_upstream
node_inspect -->|"checks health or log"| node_proxy
node_recent_log -->|"supplies recent entries"| node_proxy
node_library -->|"forwards allowed calls"| node_upstream

click node_proxy "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/proxy.py"
click node_library "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/client.py"
click node_guard "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/client.py"
click node_message_scan "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py"
click node_provenance "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py"
click node_text_signals "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py"
click node_action_signals "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py"
click node_scoring "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py"
click node_decision "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/client.py"
click node_recent_log "https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/proxy.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_proxy,node_library toneBlue
class node_guard,node_message_scan,node_provenance,node_text_signals,node_action_signals,node_scoring,node_decision toneAmber
class node_recent_log,node_upstream toneMint
class node_application,node_inspect toneIndigo
```

## Components

### Entry points

- [HTTP proxy](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/proxy.py): `llmsentry/llmsentry/proxy.py`
- [Guarded client](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/client.py): `llmsentry/llmsentry/client.py`

### Scanning and decisions

- [Message guard](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/client.py): `llmsentry/llmsentry/client.py`
- [Message scanning](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py): `llmsentry/llmsentry/scanner.py`
- [Source provenance](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py): `llmsentry/llmsentry/scanner.py`
- [Text signals](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py): `llmsentry/llmsentry/scanner.py`
- [Agent action signals](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py): `llmsentry/llmsentry/scanner.py`
- [Risk scoring](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/scanner.py): `llmsentry/llmsentry/scanner.py`
- [Threshold verdict](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/client.py): `llmsentry/llmsentry/client.py`

### Proxy and state

- [Recent decisions](https://github.com/ruchikarom/llmsentry/blob/main/llmsentry/llmsentry/proxy.py): `llmsentry/llmsentry/proxy.py`

### Other components

- **LLM application**
- **Groq API**
- **Operator**

## Connections

- LLM application → HTTP proxy: sends requests
- HTTP proxy → Message guard: checks messages
- LLM application → Guarded client: calls completions
- Guarded client → Message guard: checks messages
- Message guard → Message scanning: scans messages
- Message scanning → Source provenance: maps sources
- Message scanning → Text signals: checks content
- Message scanning → Agent action signals: checks actions
- Message scanning → Risk scoring: combines signal weights
- Source provenance → Risk scoring: weights by source
- Risk scoring → Threshold verdict: returns scores
- Message guard → Threshold verdict: applies thresholds
- Threshold verdict → HTTP proxy: returns verdict
- Threshold verdict → Guarded client: returns verdict
- HTTP proxy → Recent decisions: records decisions
- HTTP proxy → Groq API: forwards allowed requests
- Operator → HTTP proxy: checks health or log
- Recent decisions → HTTP proxy: supplies recent entries
- Guarded client → Groq API: forwards allowed calls