# gulbaki/jev-llm-guard architecture

> Architecture diagram of the GitHub repository gulbaki/jev-llm-guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gulbaki/jev-llm-guard
- Repository: https://github.com/gulbaki/jev-llm-guard

## Overview

Jev Guard is both a contextual LLM guardrail library and a demo application. Its main workflow accepts text plus trusted task and application context, validates those inputs, asks Jev System One for OWASP risk signals (with optional quotation clarification), applies a versioned policy, and returns an allow/review/block result with per-risk assessments. The browser demo adds origin checks and quotas before evaluation, then presents the result. The README also documents a CLI scenario demo and a separate research-evaluation capability. Some links are based on documented behavior or indexed imports because not every implementation was excerpted.

Main entry points: [`src/guard.js`](https://github.com/gulbaki/jev-llm-guard/blob/master/src/guard.js) (Guardrail evaluator), [`src/web-server.js`](https://github.com/gulbaki/jev-llm-guard/blob/master/src/web-server.js) (Demo HTTP server), [`web/app.js`](https://github.com/gulbaki/jev-llm-guard/blob/master/web/app.js) (Browser app), [`src/demo.js`](https://github.com/gulbaki/jev-llm-guard/blob/master/src/demo.js) (Scenario demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_demo["Web demo"]
  node_browser["Browser app<br/>[app.js]"]
  node_response_reader["API response reader<br/>[api.js]"]
  node_demo_server["Demo HTTP server<br/>[web-server.js]"]
  node_quota[("Demo quotas<br/>[demo-quota.js]")]
end

subgraph group_engine["Guardrail engine"]
  node_input_validation["Input validation<br/>[context.js]"]
  node_guardrail["Guardrail evaluator<br/>[guard.js]"]
  node_quotation["Quotation clarification<br/>[quotation.js]"]
  node_policy["Decision policy<br/>[policy.js]"]
end

subgraph group_tools["Evaluation tools"]
  node_cli["Guard CLI<br/>[cli.js]"]
  node_demo_runner["Scenario demo<br/>[demo.js]"]
  node_scenarios["Demo scenarios<br/>[scenarios.js]"]
  node_html_report["HTML report<br/>[report.js]"]
  node_research_cli["Research evaluator CLI"]
  node_research_cases["Research cases<br/>[research-cases.js]"]
  node_quotation_cases["Quotation cases<br/>[quotation-cases.js]"]
  node_research_runner["Research evaluation<br/>[research-eval.js]"]
end

subgraph group_presentation["Result presentation"]
  node_result_view["Result view model<br/>[view.js]"]
end

node_visitor(("Demo user"))
node_redis[("Upstash Redis")]
node_jev{{"Jev System One"}}

node_visitor -->|"submits text"| node_browser
node_browser -->|"posts evaluation"| node_demo_server
node_demo_server -->|"reserves quota"| node_quota
node_quota -->|"stores counters"| node_redis
node_demo_server -->|"validates input"| node_input_validation
node_demo_server -->|"evaluates request"| node_guardrail
node_guardrail -->|"validates input"| node_input_validation
node_guardrail -->|"requests risk scores"| node_jev
node_guardrail -->|"clarifies quotes"| node_quotation
node_guardrail -->|"applies policy"| node_policy
node_demo_server -->|"returns result"| node_browser
node_browser -->|"checks response"| node_response_reader
node_browser -->|"builds display"| node_result_view
node_cli -->|"evaluates text"| node_guardrail
node_demo_runner -->|"runs scenarios"| node_scenarios
node_scenarios -->|"evaluates cases"| node_guardrail
node_demo_runner -->|"writes report"| node_html_report
node_research_cli -->|"selects cases"| node_research_cases
node_research_cli -->|"evaluates cases"| node_research_runner
node_research_runner -->|"evaluates cases"| node_guardrail
node_research_cases -->|"uses suite"| node_quotation_cases

click node_browser "https://github.com/gulbaki/jev-llm-guard/blob/master/web/app.js"
click node_response_reader "https://github.com/gulbaki/jev-llm-guard/blob/master/web/api.js"
click node_demo_server "https://github.com/gulbaki/jev-llm-guard/blob/master/src/web-server.js"
click node_quota "https://github.com/gulbaki/jev-llm-guard/blob/master/src/demo-quota.js"
click node_input_validation "https://github.com/gulbaki/jev-llm-guard/blob/master/src/context.js"
click node_guardrail "https://github.com/gulbaki/jev-llm-guard/blob/master/src/guard.js"
click node_quotation "https://github.com/gulbaki/jev-llm-guard/blob/master/src/quotation.js"
click node_policy "https://github.com/gulbaki/jev-llm-guard/blob/master/src/policy.js"
click node_result_view "https://github.com/gulbaki/jev-llm-guard/blob/master/web/view.js"
click node_cli "https://github.com/gulbaki/jev-llm-guard/blob/master/src/cli.js"
click node_demo_runner "https://github.com/gulbaki/jev-llm-guard/blob/master/src/demo.js"
click node_scenarios "https://github.com/gulbaki/jev-llm-guard/blob/master/src/scenarios.js"
click node_html_report "https://github.com/gulbaki/jev-llm-guard/blob/master/src/report.js"
click node_research_cli "https://github.com/gulbaki/jev-llm-guard/blob/master/bin/jev-research-eval.js"
click node_research_cases "https://github.com/gulbaki/jev-llm-guard/blob/master/src/research-cases.js"
click node_quotation_cases "https://github.com/gulbaki/jev-llm-guard/blob/master/src/quotation-cases.js"
click node_research_runner "https://github.com/gulbaki/jev-llm-guard/blob/master/src/research-eval.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_browser,node_response_reader,node_demo_server,node_quota,node_visitor toneBlue
class node_input_validation,node_guardrail,node_quotation,node_policy,node_redis toneAmber
class node_cli,node_demo_runner,node_scenarios,node_html_report,node_research_cli,node_research_cases,node_quotation_cases,node_research_runner toneMint
class node_result_view toneRose
class node_jev toneIndigo
```

## Components

### Web demo

- [Browser app](https://github.com/gulbaki/jev-llm-guard/blob/master/web/app.js): `web/app.js`
- [API response reader](https://github.com/gulbaki/jev-llm-guard/blob/master/web/api.js): `web/api.js`
- [Demo HTTP server](https://github.com/gulbaki/jev-llm-guard/blob/master/src/web-server.js): `src/web-server.js`
- [Demo quotas](https://github.com/gulbaki/jev-llm-guard/blob/master/src/demo-quota.js): `src/demo-quota.js`

### Guardrail engine

- [Input validation](https://github.com/gulbaki/jev-llm-guard/blob/master/src/context.js): `src/context.js`
- [Guardrail evaluator](https://github.com/gulbaki/jev-llm-guard/blob/master/src/guard.js): `src/guard.js`
- [Quotation clarification](https://github.com/gulbaki/jev-llm-guard/blob/master/src/quotation.js): `src/quotation.js`
- [Decision policy](https://github.com/gulbaki/jev-llm-guard/blob/master/src/policy.js): `src/policy.js`

### Evaluation tools

- [Guard CLI](https://github.com/gulbaki/jev-llm-guard/blob/master/src/cli.js): `src/cli.js`
- [Scenario demo](https://github.com/gulbaki/jev-llm-guard/blob/master/src/demo.js): `src/demo.js`
- [Demo scenarios](https://github.com/gulbaki/jev-llm-guard/blob/master/src/scenarios.js): `src/scenarios.js`
- [HTML report](https://github.com/gulbaki/jev-llm-guard/blob/master/src/report.js): `src/report.js`
- [Research evaluator CLI](https://github.com/gulbaki/jev-llm-guard/blob/master/bin/jev-research-eval.js): `bin/jev-research-eval.js`
- [Research cases](https://github.com/gulbaki/jev-llm-guard/blob/master/src/research-cases.js): `src/research-cases.js`
- [Quotation cases](https://github.com/gulbaki/jev-llm-guard/blob/master/src/quotation-cases.js): `src/quotation-cases.js`
- [Research evaluation](https://github.com/gulbaki/jev-llm-guard/blob/master/src/research-eval.js): `src/research-eval.js`

### Result presentation

- [Result view model](https://github.com/gulbaki/jev-llm-guard/blob/master/web/view.js): `web/view.js`

### Other components

- **Demo user**
- **Upstash Redis**
- **Jev System One**

## Connections

- Demo user → Browser app: submits text (evidence: `README.md`)
- Browser app → Demo HTTP server: posts evaluation (evidence: `web/app.js`)
- Demo HTTP server → Demo quotas: reserves quota (evidence: `src/web-server.js`)
- Demo quotas → Upstash Redis: stores counters (evidence: `README.md`)
- Demo HTTP server → Input validation: validates input (evidence: `src/web-server.js`)
- Demo HTTP server → Guardrail evaluator: evaluates request (evidence: `src/web-server.js`)
- Guardrail evaluator → Input validation: validates input (evidence: `src/guard.js`)
- Guardrail evaluator → Jev System One: requests risk scores (evidence: `src/guard.js`)
- Guardrail evaluator → Quotation clarification: clarifies quotes (evidence: `src/guard.js`)
- Guardrail evaluator → Decision policy: applies policy (evidence: `src/guard.js`)
- Demo HTTP server → Browser app: returns result (evidence: `README.md`)
- Browser app → API response reader: checks response (evidence: `web/app.js`)
- Browser app → Result view model: builds display (evidence: `web/app.js`)
- Guard CLI → Guardrail evaluator: evaluates text (evidence: `src/cli.js`)
- Scenario demo → Demo scenarios: runs scenarios (evidence: `src/demo.js`)
- Demo scenarios → Guardrail evaluator: evaluates cases (evidence: `src/scenarios.js`)
- Scenario demo → HTML report: writes report (evidence: `src/demo.js`)
- Research evaluator CLI → Research cases: selects cases (evidence: `bin/jev-research-eval.js`)
- Research evaluator CLI → Research evaluation: evaluates cases (evidence: `bin/jev-research-eval.js`)
- Research evaluation → Guardrail evaluator: evaluates cases (evidence: `src/research-eval.js`)
- Research cases → Quotation cases: uses suite (evidence: `src/research-cases.js`)
