# bytemonk-academy/jev-decision-lab architecture

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

- Interactive diagram: https://gitdiagram.com/bytemonk-academy/jev-decision-lab
- Repository: https://github.com/bytemonk-academy/jev-decision-lab

## Overview

jev-decision-lab is an interactive engineering lab comparing typed decision models, deterministic code, and general-purpose LLMs. Users submit labelled examples through Support Pipeline, Agent Firewall, or Model Router; a selected provider returns probability distributions, deterministic policy/gating produces a route or simulated action, and traces record cost, latency, confidence, and correctness. Calibration analyzes those records, while batch runs and CLI benchmarks evaluate datasets. The graph follows documented capabilities and indexed imports; unsampled modules are included where their role is documented, but uncertain internal calls are omitted.

Main entry points: [`lib/experiments/index.ts`](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/experiments/index.ts) (Experiment dispatcher), [`app/api/run-batch/route.ts`](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/app/api/run-batch/route.ts) (Batch-run API), [`lib/providers.ts`](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/providers.ts) (Provider registry), [`app/api/run/route.ts`](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/app/api/run/route.ts) (Single-run API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Lab experience"]
  node_webapp["Next.js pages"]
  node_supportui["Support comparison UI<br/>[SupportCompare.tsx]"]
  node_calibrationui["Calibration UI<br/>[CalibrationLab.tsx]"]
  node_resultviews["Decision displays<br/>[DecisionBars.tsx]"]
end

subgraph group_execution["Decision workflows"]
  node_runapi["Single-run API<br/>[route.ts]"]
  node_batchapi["Batch-run API<br/>[route.ts]"]
  node_datasets["Labelled datasets<br/>[datasets.ts]"]
  node_dispatch["Experiment dispatcher<br/>[index.ts]"]
  node_support["Support pipeline<br/>[support.ts]"]
  node_firewall["Agent firewall<br/>[firewall.ts]"]
  node_router["Model router<br/>[router.ts]"]
  node_policy["Deterministic policy<br/>[policy-engine.ts]"]
end

subgraph group_providers["Provider adapters"]
  node_registry["Provider registry<br/>[providers.ts]"]
  node_jev["Jev adapter<br/>[jev.ts]"]
  node_llm["LLM adapter<br/>[llm.ts]"]
  node_mock["Mock provider<br/>[mock.ts]"]
end

subgraph group_analysis["Measurement and results"]
  node_metrics["Metrics and calibration<br/>[metrics.ts]"]
  node_results[("JSON results store<br/>[results-store.ts]")]
  node_resultsapi["Results API<br/>[route.ts]"]
  node_benchmark["CLI benchmark<br/>[benchmark.ts]"]
  node_sharedcli["CLI shared helpers<br/>[_shared.ts]"]
end

node_engineer(("Lab user"))
node_externalmodels{{"Model services"}}

node_engineer -->|"opens lab"| node_webapp
node_webapp -->|"renders support"| node_supportui
node_webapp -->|"renders calibration"| node_calibrationui
node_supportui -->|"submits run"| node_runapi
node_calibrationui -->|"runs dataset"| node_batchapi
node_runapi -->|"loads examples"| node_datasets
node_runapi -->|"dispatches experiment"| node_dispatch
node_runapi -->|"resolves provider"| node_registry
node_runapi -->|"appends records"| node_results
node_batchapi -->|"loads dataset"| node_datasets
node_batchapi -->|"runs examples"| node_dispatch
node_batchapi -->|"resolves provider"| node_registry
node_batchapi -->|"summarizes records"| node_metrics
node_batchapi -->|"saves benchmark"| node_results
node_dispatch -->|"runs support"| node_support
node_dispatch -->|"runs firewall"| node_firewall
node_dispatch -->|"runs router"| node_router
node_dispatch -->|"gets providers"| node_registry
node_support -->|"evaluates policy"| node_policy
node_support -->|"records outcomes"| node_metrics
node_router -->|"evaluates route"| node_policy
node_router -->|"records outcomes"| node_metrics
node_firewall -->|"checks safeguards"| node_policy
node_registry -->|"selects Jev"| node_jev
node_registry -->|"selects LLM"| node_llm
node_registry -->|"selects mock"| node_mock
node_jev -->|"calls model APIs"| node_externalmodels
node_llm -->|"calls chat APIs"| node_externalmodels
node_supportui -->|"displays decisions"| node_resultviews
node_calibrationui -->|"analyzes records"| node_metrics
node_calibrationui -->|"loads results"| node_resultsapi
node_resultsapi -->|"reads records"| node_results
node_resultsapi -->|"summarizes results"| node_metrics
node_benchmark -.->|"benchmarks data"| node_datasets
node_benchmark -.->|"runs experiments"| node_dispatch
node_benchmark -.->|"uses helpers"| node_sharedcli
node_benchmark -.->|"writes reports"| node_results

click node_webapp "https://github.com/bytemonk-academy/jev-decision-lab/tree/main/app"
click node_supportui "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/components/SupportCompare.tsx"
click node_calibrationui "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/components/CalibrationLab.tsx"
click node_resultviews "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/components/DecisionBars.tsx"
click node_runapi "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/app/api/run/route.ts"
click node_batchapi "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/app/api/run-batch/route.ts"
click node_datasets "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/datasets.ts"
click node_dispatch "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/experiments/index.ts"
click node_support "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/experiments/support.ts"
click node_firewall "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/experiments/firewall.ts"
click node_router "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/experiments/router.ts"
click node_policy "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/policy-engine.ts"
click node_registry "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/providers.ts"
click node_jev "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/jev.ts"
click node_llm "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/llm.ts"
click node_mock "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/mock.ts"
click node_metrics "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/metrics.ts"
click node_results "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/results-store.ts"
click node_resultsapi "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/app/api/results/route.ts"
click node_benchmark "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/experiments/benchmark.ts"
click node_sharedcli "https://github.com/bytemonk-academy/jev-decision-lab/blob/main/experiments/_shared.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_webapp,node_supportui,node_calibrationui,node_resultviews,node_engineer toneBlue
class node_runapi,node_batchapi,node_datasets,node_dispatch,node_support,node_firewall,node_router,node_policy toneAmber
class node_registry,node_jev,node_llm,node_mock toneMint
class node_metrics,node_results,node_resultsapi,node_benchmark,node_sharedcli toneRose
class node_externalmodels toneIndigo
```

## Components

### Lab experience

- [Next.js pages](https://github.com/bytemonk-academy/jev-decision-lab/tree/main/app): `app`
- [Support comparison UI](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/components/SupportCompare.tsx): `components/SupportCompare.tsx`
- [Calibration UI](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/components/CalibrationLab.tsx): `components/CalibrationLab.tsx`
- [Decision displays](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/components/DecisionBars.tsx): `components/DecisionBars.tsx`

### Decision workflows

- [Single-run API](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/app/api/run/route.ts): `app/api/run/route.ts`
- [Batch-run API](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/app/api/run-batch/route.ts): `app/api/run-batch/route.ts`
- [Labelled datasets](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/datasets.ts): `lib/datasets.ts`
- [Experiment dispatcher](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/experiments/index.ts): `lib/experiments/index.ts`
- [Support pipeline](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/experiments/support.ts): `lib/experiments/support.ts`
- [Agent firewall](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/experiments/firewall.ts): `lib/experiments/firewall.ts`
- [Model router](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/experiments/router.ts): `lib/experiments/router.ts`
- [Deterministic policy](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/policy-engine.ts): `lib/policy-engine.ts`

### Provider adapters

- [Provider registry](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/providers.ts): `lib/providers.ts`
- [Jev adapter](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/jev.ts): `lib/jev.ts`
- [LLM adapter](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/llm.ts): `lib/llm.ts`
- [Mock provider](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/mock.ts): `lib/mock.ts`

### Measurement and results

- [Metrics and calibration](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/metrics.ts): `lib/metrics.ts`
- [JSON results store](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/lib/results-store.ts): `lib/results-store.ts`
- [Results API](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/app/api/results/route.ts): `app/api/results/route.ts`
- [CLI benchmark](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/experiments/benchmark.ts): `experiments/benchmark.ts`
- [CLI shared helpers](https://github.com/bytemonk-academy/jev-decision-lab/blob/main/experiments/_shared.ts): `experiments/_shared.ts`

### Other components

- **Lab user**
- **Model services**

## Connections

- Lab user → Next.js pages: opens lab (evidence: `README.md`)
- Next.js pages → Support comparison UI: renders support (evidence: `app/support/page.tsx`)
- Next.js pages → Calibration UI: renders calibration (evidence: `app/calibration/page.tsx`)
- Support comparison UI → Single-run API: submits run (evidence: `README.md`)
- Calibration UI → Batch-run API: runs dataset (evidence: `README.md`)
- Single-run API → Labelled datasets: loads examples (evidence: `app/api/run/route.ts`)
- Single-run API → Experiment dispatcher: dispatches experiment (evidence: `app/api/run/route.ts`)
- Single-run API → Provider registry: resolves provider (evidence: `app/api/run/route.ts`)
- Single-run API → JSON results store: appends records (evidence: `app/api/run/route.ts`)
- Batch-run API → Labelled datasets: loads dataset (evidence: `app/api/run-batch/route.ts`)
- Batch-run API → Experiment dispatcher: runs examples (evidence: `app/api/run-batch/route.ts`)
- Batch-run API → Provider registry: resolves provider (evidence: `app/api/run-batch/route.ts`)
- Batch-run API → Metrics and calibration: summarizes records (evidence: `app/api/run-batch/route.ts`)
- Batch-run API → JSON results store: saves benchmark (evidence: `app/api/run-batch/route.ts`)
- Experiment dispatcher → Support pipeline: runs support (evidence: `lib/experiments/index.ts`)
- Experiment dispatcher → Agent firewall: runs firewall (evidence: `lib/experiments/index.ts`)
- Experiment dispatcher → Model router: runs router (evidence: `lib/experiments/index.ts`)
- Experiment dispatcher → Provider registry: gets providers (evidence: `lib/experiments/index.ts`)
- Support pipeline → Deterministic policy: evaluates policy (evidence: `lib/experiments/support.ts`)
- Support pipeline → Metrics and calibration: records outcomes (evidence: `lib/experiments/support.ts`)
- Model router → Deterministic policy: evaluates route (evidence: `lib/experiments/router.ts`)
- Model router → Metrics and calibration: records outcomes (evidence: `lib/experiments/router.ts`)
- Agent firewall → Deterministic policy: checks safeguards (evidence: `lib/experiments/firewall.ts`)
- Provider registry → Jev adapter: selects Jev (evidence: `lib/providers.ts`)
- Provider registry → LLM adapter: selects LLM (evidence: `lib/providers.ts`)
- Provider registry → Mock provider: selects mock (evidence: `lib/providers.ts`)
- Jev adapter → Model services: calls model APIs (evidence: `lib/jev.ts`)
- LLM adapter → Model services: calls chat APIs (evidence: `lib/llm.ts`)
- Support comparison UI → Decision displays: displays decisions (evidence: `components/SupportCompare.tsx`)
- Calibration UI → Metrics and calibration: analyzes records (evidence: `components/CalibrationLab.tsx`)
- Calibration UI → Results API: loads results (evidence: `README.md`)
- Results API → JSON results store: reads records (evidence: `app/api/results/route.ts`)
- Results API → Metrics and calibration: summarizes results (evidence: `app/api/results/route.ts`)
- CLI benchmark → Labelled datasets: benchmarks data
- CLI benchmark → Experiment dispatcher: runs experiments
- CLI benchmark → CLI shared helpers: uses helpers
- CLI benchmark → JSON results store: writes reports
