# kiwi0719/jev-edge architecture

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

- Interactive diagram: https://gitdiagram.com/kiwi0719/jev-edge
- Repository: https://github.com/kiwi0719/jev-edge

## Overview

jev-edge is typed-judgment admission control for LLM traffic: gateway integrations inspect requests before they reach protected services, applying cheap rules before optional model judgment. The principal flow is request decoding and L1 filtering, cached or provider-backed L2 scoring, then policy enforcement or annotated pass-through; ambiguous cases feed a non-blocking L3 path. The repository also provides JavaScript runtime integrations, multiple judge providers, operational state/configuration endpoints, and gateway protocol adapters. README documents these capabilities; sampled source confirms parts of the JS runtime and adapter behavior, while several Lua and adapter links rely on documented contracts.

Main entry points: [`core/init.lua`](https://github.com/kiwi0719/jev-edge/blob/main/core/init.lua) (Core evaluator), [`adapters/openresty/lib/resty/jev/edge.lua`](https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/edge.lua) (Authz endpoint), [`adapters/js/src/runtime.ts`](https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/runtime.ts) (JS shared runtime), [`core/judge.lua`](https://github.com/kiwi0719/jev-edge/blob/main/core/judge.lua) (L2 judge prompts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Gateway runtime"]
  node_openresty["OpenResty access<br/>[edge.lua]"]
  node_authz["Authz endpoint<br/>[edge.lua]"]
  node_body["Body decoding<br/>[body.lua]"]
  node_js_runtime["JS shared runtime<br/>[runtime.ts]"]
  node_verdict["Verdict response<br/>[edge.lua]"]
end

subgraph group_decision["Judgment pipeline"]
  node_rules["L1 rules<br/>[rules.lua]"]
  node_core["Core evaluator<br/>[init.lua]"]
  node_normalize["Text normalization<br/>[normalize.lua]"]
  node_judge["L2 judge prompts<br/>[judge.lua]"]
  node_policy["Policy verdict<br/>[policy.lua]"]
  node_templates["Prompt templates"]
  node_async["Async L3 path<br/>[async.lua]"]
  node_js_core["JS core evaluator<br/>[index.ts]"]
end

subgraph group_state["State and operations"]
  node_cache[("Verdict cache<br/>[cache.lua]")]
  node_trust[("Subject reputation<br/>[subject.lua]")]
  node_admin["Admin configuration<br/>[config.lua]"]
  node_js_stores[("JS runtime stores<br/>[stores.ts]")]
end

subgraph group_integrations["Runtime integrations"]
  node_js_hosts["JS host adapters<br/>[frameworks.ts]"]
  node_provider["Judge providers"]
  node_laya_service["Laya judge<br/>[laya_server.py]"]
  node_gateway_adapters["Gateway adapters"]
  node_envoy_shim["Envoy gRPC shim<br/>[main.go]"]
  node_haproxy_agent["HAProxy SPOE agent<br/>[main.go]"]
  node_lite_guard["LiteLLM guardrail"]
  node_js_provider["JS judge providers<br/>[index.ts]"]
end

node_client(("Incoming client"))
node_jev_service["TypeSafe Jev"]
node_backend["Protected backend"]

node_client -->|"sends request"| node_openresty
node_openresty -->|"decodes body"| node_body
node_openresty -->|"evaluates request"| node_core
node_core -->|"checks rules"| node_rules
node_core -->|"normalizes text"| node_normalize
node_core -->|"reads and writes"| node_cache
node_core -->|"builds judgment"| node_judge
node_judge -->|"uses templates"| node_templates
node_judge -->|"requests scores"| node_provider
node_provider -->|"calls API"| node_jev_service
node_provider -.->|"calls protocol"| node_laya_service
node_core -->|"applies policy"| node_policy
node_policy -->|"produces verdict"| node_verdict
node_verdict -->|"passes with headers"| node_backend
node_verdict -->|"blocks request"| node_client
node_core -->|"defers ambiguous case"| node_async
node_async -->|"updates reputation"| node_trust
node_admin -->|"updates live config"| node_openresty
node_client -->|"sends request"| node_js_hosts
node_js_hosts -->|"adapts request"| node_js_runtime
node_js_runtime -->|"evaluates request"| node_js_core
node_js_runtime -->|"selects stores"| node_js_stores
node_js_core -->|"requests scores"| node_js_provider
node_js_provider -->|"calls API"| node_jev_service
node_js_runtime -->|"passes or blocks"| node_backend
node_client -.->|"enters gateway"| node_gateway_adapters
node_gateway_adapters -.->|"forwards authz check"| node_authz
node_envoy_shim -->|"forwards HTTP check"| node_authz
node_haproxy_agent -->|"requests verdict"| node_authz
node_lite_guard -->|"requests verdict"| node_authz
node_authz -->|"evaluates request"| node_core

click node_openresty "https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/edge.lua"
click node_authz "https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/edge.lua"
click node_body "https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/body.lua"
click node_js_hosts "https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/frameworks.ts"
click node_js_runtime "https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/runtime.ts"
click node_rules "https://github.com/kiwi0719/jev-edge/blob/main/core/rules.lua"
click node_core "https://github.com/kiwi0719/jev-edge/blob/main/core/init.lua"
click node_normalize "https://github.com/kiwi0719/jev-edge/blob/main/core/normalize.lua"
click node_judge "https://github.com/kiwi0719/jev-edge/blob/main/core/judge.lua"
click node_policy "https://github.com/kiwi0719/jev-edge/blob/main/core/policy.lua"
click node_templates "https://github.com/kiwi0719/jev-edge/tree/main/core/templates"
click node_provider "https://github.com/kiwi0719/jev-edge/tree/main/adapters/openresty/lib/resty/jev/providers"
click node_laya_service "https://github.com/kiwi0719/jev-edge/blob/main/adapters/laya-server/laya_server.py"
click node_verdict "https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/edge.lua"
click node_cache "https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/cache.lua"
click node_async "https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/async.lua"
click node_trust "https://github.com/kiwi0719/jev-edge/blob/main/core/subject.lua"
click node_admin "https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/config.lua"
click node_gateway_adapters "https://github.com/kiwi0719/jev-edge/tree/main/adapters"
click node_envoy_shim "https://github.com/kiwi0719/jev-edge/blob/main/adapters/envoy/grpc-shim/main.go"
click node_haproxy_agent "https://github.com/kiwi0719/jev-edge/blob/main/adapters/haproxy/spoa/main.go"
click node_lite_guard "https://github.com/kiwi0719/jev-edge/blob/main/adapters/litellm/jev_edge_guardrail.py"
click node_js_core "https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/core/index.ts"
click node_js_provider "https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/providers/index.ts"
click node_js_stores "https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/cf/stores.ts"

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_openresty,node_authz,node_body,node_js_runtime,node_verdict,node_client toneBlue
class node_rules,node_core,node_normalize,node_judge,node_policy,node_templates,node_async,node_js_core toneAmber
class node_cache,node_trust,node_admin,node_js_stores toneMint
class node_js_hosts,node_provider,node_laya_service,node_gateway_adapters,node_envoy_shim,node_haproxy_agent,node_lite_guard,node_js_provider toneRose
class node_jev_service,node_backend toneIndigo
```

## Components

### Gateway runtime

- [OpenResty access](https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/edge.lua): `adapters/openresty/lib/resty/jev/edge.lua`
- [Authz endpoint](https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/edge.lua): `adapters/openresty/lib/resty/jev/edge.lua`
- [Body decoding](https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/body.lua): `adapters/openresty/lib/resty/jev/body.lua`
- [JS shared runtime](https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/runtime.ts): `adapters/js/src/runtime.ts`
- [Verdict response](https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/edge.lua): `adapters/openresty/lib/resty/jev/edge.lua`

### Judgment pipeline

- [L1 rules](https://github.com/kiwi0719/jev-edge/blob/main/core/rules.lua): `core/rules.lua`
- [Core evaluator](https://github.com/kiwi0719/jev-edge/blob/main/core/init.lua): `core/init.lua`
- [Text normalization](https://github.com/kiwi0719/jev-edge/blob/main/core/normalize.lua): `core/normalize.lua`
- [L2 judge prompts](https://github.com/kiwi0719/jev-edge/blob/main/core/judge.lua): `core/judge.lua`
- [Policy verdict](https://github.com/kiwi0719/jev-edge/blob/main/core/policy.lua): `core/policy.lua`
- [Prompt templates](https://github.com/kiwi0719/jev-edge/tree/main/core/templates): `core/templates`
- [Async L3 path](https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/async.lua): `adapters/openresty/lib/resty/jev/async.lua`
- [JS core evaluator](https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/core/index.ts): `adapters/js/src/core/index.ts`

### State and operations

- [Verdict cache](https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/cache.lua): `adapters/openresty/lib/resty/jev/cache.lua`
- [Subject reputation](https://github.com/kiwi0719/jev-edge/blob/main/core/subject.lua): `core/subject.lua`
- [Admin configuration](https://github.com/kiwi0719/jev-edge/blob/main/adapters/openresty/lib/resty/jev/config.lua): `adapters/openresty/lib/resty/jev/config.lua`
- [JS runtime stores](https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/cf/stores.ts): `adapters/js/src/cf/stores.ts`

### Runtime integrations

- [JS host adapters](https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/frameworks.ts): `adapters/js/src/frameworks.ts`
- [Judge providers](https://github.com/kiwi0719/jev-edge/tree/main/adapters/openresty/lib/resty/jev/providers): `adapters/openresty/lib/resty/jev/providers`
- [Laya judge](https://github.com/kiwi0719/jev-edge/blob/main/adapters/laya-server/laya_server.py): `adapters/laya-server/laya_server.py`
- [Gateway adapters](https://github.com/kiwi0719/jev-edge/tree/main/adapters): `adapters`
- [Envoy gRPC shim](https://github.com/kiwi0719/jev-edge/blob/main/adapters/envoy/grpc-shim/main.go): `adapters/envoy/grpc-shim/main.go`
- [HAProxy SPOE agent](https://github.com/kiwi0719/jev-edge/blob/main/adapters/haproxy/spoa/main.go): `adapters/haproxy/spoa/main.go`
- [LiteLLM guardrail](https://github.com/kiwi0719/jev-edge/blob/main/adapters/litellm/jev_edge_guardrail.py): `adapters/litellm/jev_edge_guardrail.py`
- [JS judge providers](https://github.com/kiwi0719/jev-edge/blob/main/adapters/js/src/providers/index.ts): `adapters/js/src/providers/index.ts`

### Other components

- **Incoming client**
- **TypeSafe Jev**
- **Protected backend**

## Connections

- Incoming client → OpenResty access: sends request
- OpenResty access → Body decoding: decodes body
- OpenResty access → Core evaluator: evaluates request
- Core evaluator → L1 rules: checks rules
- Core evaluator → Text normalization: normalizes text
- Core evaluator → Verdict cache: reads and writes
- Core evaluator → L2 judge prompts: builds judgment
- L2 judge prompts → Prompt templates: uses templates
- L2 judge prompts → Judge providers: requests scores
- Judge providers → TypeSafe Jev: calls API
- Judge providers → Laya judge: calls protocol
- Core evaluator → Policy verdict: applies policy
- Policy verdict → Verdict response: produces verdict
- Verdict response → Protected backend: passes with headers
- Verdict response → Incoming client: blocks request
- Core evaluator → Async L3 path: defers ambiguous case
- Async L3 path → Subject reputation: updates reputation
- Admin configuration → OpenResty access: updates live config
- Incoming client → JS host adapters: sends request
- JS host adapters → JS shared runtime: adapts request
- JS shared runtime → JS core evaluator: evaluates request
- JS shared runtime → JS runtime stores: selects stores
- JS core evaluator → JS judge providers: requests scores
- JS judge providers → TypeSafe Jev: calls API
- JS shared runtime → Protected backend: passes or blocks
- Incoming client → Gateway adapters: enters gateway
- Gateway adapters → Authz endpoint: forwards authz check
- Envoy gRPC shim → Authz endpoint: forwards HTTP check
- HAProxy SPOE agent → Authz endpoint: requests verdict
- LiteLLM guardrail → Authz endpoint: requests verdict
- Authz endpoint → Core evaluator: evaluates request