# githubnext/localjev architecture

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

- Interactive diagram: https://gitdiagram.com/githubnext/localjev
- Repository: https://github.com/githubnext/localjev

## Overview

LocalJev is a Jev-compatible HTTP bridge: clients submit state and typed questions, the server validates them, and the engine prompts an OpenAI-compatible model for probabilities before returning Jev-shaped answers. A separate documented capability runs reproducible model bake-offs and reports quality, calibration, and latency. The evaluation branch is included because its substantial runtime modules are part of the repository; relationships inside the engine workflow follow the README, since the sampled engine excerpt omits those implementation details.

Main entry points: [`scripts/eval/run.ts`](https://github.com/githubnext/localjev/blob/main/scripts/eval/run.ts) (Bake-off Runner), [`src/index.ts`](https://github.com/githubnext/localjev/blob/main/src/index.ts) (Bun Entrypoint), [`src/engine.ts`](https://github.com/githubnext/localjev/blob/main/src/engine.ts) (Decision Engine), [`src/server.ts`](https://github.com/githubnext/localjev/blob/main/src/server.ts) (HTTP Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Jev API"]
  node_app["Bun Entrypoint<br/>[index.ts]"]
  node_settings["Runtime Settings<br/>[config.ts]"]
  node_http["HTTP Routes<br/>[server.ts]"]
  node_schema["Request Validation<br/>[types.ts]"]
end

subgraph group_inference["Inference"]
  node_engine["Decision Engine<br/>[engine.ts]"]
  node_prompt["Classification Prompt<br/>[engine.ts]"]
  node_completion["Chat Completion<br/>[engine.ts]"]
  node_probabilities["Probability Parsing<br/>[engine.ts]"]
  node_answers["Jev Answers<br/>[engine.ts]"]
end

subgraph group_evaluation["Model Evaluation"]
  node_evalrun["Bake-off Runner<br/>[run.ts]"]
  node_evaldata["Dataset Preparation<br/>[data.ts]"]
  node_evalcommon["Evaluation Types<br/>[common.ts]"]
  node_evalreport["Report Generation<br/>[report.ts]"]
  node_metrics["Quality Metrics<br/>[metrics.ts]"]
end

node_client(("API Client"))
node_model{{"OpenAI-Compatible Model"}}
node_datasets[("Public Datasets")]
node_runfiles[("Evaluation Run Files")]

node_client -->|"sends request"| node_app
node_app -->|"loads settings"| node_settings
node_app -->|"serves requests"| node_http
node_http -->|"validates body"| node_schema
node_http -->|"requests decision"| node_engine
node_engine -->|"uses settings"| node_settings
node_engine -->|"prepares prompt"| node_prompt
node_prompt -->|"requests probabilities"| node_completion
node_completion -->|"calls endpoint"| node_model
node_completion -->|"parses output"| node_probabilities
node_probabilities -->|"normalizes and scores"| node_answers
node_app -.->|"runs separately"| node_evalrun
node_evalrun -->|"loads settings"| node_settings
node_evalrun -->|"runs decisions"| node_engine
node_evalrun -->|"prepares examples"| node_evaldata
node_evaldata -->|"downloads data"| node_datasets
node_evalrun -->|"uses evaluation types"| node_evalcommon
node_evaldata -->|"uses evaluation types"| node_evalcommon
node_evalrun -->|"generates report"| node_evalreport
node_evalreport -->|"calculates metrics"| node_metrics
node_evalrun -->|"writes results"| node_runfiles
node_evalreport -->|"writes summaries"| node_runfiles

click node_app "https://github.com/githubnext/localjev/blob/main/src/index.ts"
click node_settings "https://github.com/githubnext/localjev/blob/main/src/config.ts"
click node_http "https://github.com/githubnext/localjev/blob/main/src/server.ts"
click node_schema "https://github.com/githubnext/localjev/blob/main/src/types.ts"
click node_engine "https://github.com/githubnext/localjev/blob/main/src/engine.ts"
click node_prompt "https://github.com/githubnext/localjev/blob/main/src/engine.ts"
click node_completion "https://github.com/githubnext/localjev/blob/main/src/engine.ts"
click node_probabilities "https://github.com/githubnext/localjev/blob/main/src/engine.ts"
click node_answers "https://github.com/githubnext/localjev/blob/main/src/engine.ts"
click node_evalrun "https://github.com/githubnext/localjev/blob/main/scripts/eval/run.ts"
click node_evaldata "https://github.com/githubnext/localjev/blob/main/scripts/eval/data.ts"
click node_evalcommon "https://github.com/githubnext/localjev/blob/main/scripts/eval/common.ts"
click node_evalreport "https://github.com/githubnext/localjev/blob/main/scripts/eval/report.ts"
click node_metrics "https://github.com/githubnext/localjev/blob/main/scripts/eval/metrics.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_app,node_settings,node_http,node_schema,node_client toneBlue
class node_engine,node_prompt,node_completion,node_probabilities,node_answers,node_datasets,node_runfiles toneAmber
class node_evalrun,node_evaldata,node_evalcommon,node_evalreport,node_metrics toneMint
class node_model toneIndigo
```

## Components

### Jev API

- [Bun Entrypoint](https://github.com/githubnext/localjev/blob/main/src/index.ts): `src/index.ts`
- [Runtime Settings](https://github.com/githubnext/localjev/blob/main/src/config.ts): `src/config.ts`
- [HTTP Routes](https://github.com/githubnext/localjev/blob/main/src/server.ts): `src/server.ts`
- [Request Validation](https://github.com/githubnext/localjev/blob/main/src/types.ts): `src/types.ts`

### Inference

- [Decision Engine](https://github.com/githubnext/localjev/blob/main/src/engine.ts): `src/engine.ts`
- [Classification Prompt](https://github.com/githubnext/localjev/blob/main/src/engine.ts): `src/engine.ts`
- [Chat Completion](https://github.com/githubnext/localjev/blob/main/src/engine.ts): `src/engine.ts`
- [Probability Parsing](https://github.com/githubnext/localjev/blob/main/src/engine.ts): `src/engine.ts`
- [Jev Answers](https://github.com/githubnext/localjev/blob/main/src/engine.ts): `src/engine.ts`

### Model Evaluation

- [Bake-off Runner](https://github.com/githubnext/localjev/blob/main/scripts/eval/run.ts): `scripts/eval/run.ts`
- [Dataset Preparation](https://github.com/githubnext/localjev/blob/main/scripts/eval/data.ts): `scripts/eval/data.ts`
- [Evaluation Types](https://github.com/githubnext/localjev/blob/main/scripts/eval/common.ts): `scripts/eval/common.ts`
- [Report Generation](https://github.com/githubnext/localjev/blob/main/scripts/eval/report.ts): `scripts/eval/report.ts`
- [Quality Metrics](https://github.com/githubnext/localjev/blob/main/scripts/eval/metrics.ts): `scripts/eval/metrics.ts`

### Other components

- **API Client**
- **OpenAI-Compatible Model**
- **Public Datasets**
- **Evaluation Run Files**

## Connections

- API Client → Bun Entrypoint: sends request (evidence: `README.md`)
- Bun Entrypoint → Runtime Settings: loads settings (evidence: `src/index.ts`)
- Bun Entrypoint → HTTP Routes: serves requests (evidence: `src/index.ts`)
- HTTP Routes → Request Validation: validates body (evidence: `src/server.ts`)
- HTTP Routes → Decision Engine: requests decision (evidence: `src/server.ts`)
- Decision Engine → Runtime Settings: uses settings (evidence: `src/engine.ts`)
- Decision Engine → Classification Prompt: prepares prompt (evidence: `README.md`)
- Classification Prompt → Chat Completion: requests probabilities (evidence: `README.md`)
- Chat Completion → OpenAI-Compatible Model: calls endpoint (evidence: `src/engine.ts`)
- Chat Completion → Probability Parsing: parses output (evidence: `README.md`)
- Probability Parsing → Jev Answers: normalizes and scores (evidence: `README.md`)
- Bun Entrypoint → Bake-off Runner: runs separately
- Bake-off Runner → Runtime Settings: loads settings (evidence: `scripts/eval/run.ts`)
- Bake-off Runner → Decision Engine: runs decisions (evidence: `scripts/eval/run.ts`)
- Bake-off Runner → Dataset Preparation: prepares examples (evidence: `scripts/eval/run.ts`)
- Dataset Preparation → Public Datasets: downloads data (evidence: `scripts/eval/data.ts`)
- Bake-off Runner → Evaluation Types: uses evaluation types (evidence: `scripts/eval/run.ts`)
- Dataset Preparation → Evaluation Types: uses evaluation types (evidence: `scripts/eval/data.ts`)
- Bake-off Runner → Report Generation: generates report (evidence: `scripts/eval/run.ts`)
- Report Generation → Quality Metrics: calculates metrics (evidence: `scripts/eval/report.ts`)
- Bake-off Runner → Evaluation Run Files: writes results (evidence: `scripts/eval/run.ts`)
- Report Generation → Evaluation Run Files: writes summaries (evidence: `scripts/eval/report.ts`)
