# kierandotai/jev-scout architecture

> Architecture diagram of the GitHub repository kierandotai/jev-scout, 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/kierandotai/jev-scout
- Repository: https://github.com/kierandotai/jev-scout

## Overview

jev-scout is an MCP stdio service that lets agents search and fetch web pages, scores research steps with Jev, optionally gates results, and records decisions for a live dashboard and research reports. Its main flow is MCP tool calls through a shared pipeline: search backends return results for judging, while fetch requests pass a safety-checked fetcher before page judging. Cache, budget, and ledger are internal layers. The README documents the report and dashboard capabilities; source excerpts do not expose every registration or dashboard detail, so uncertain links are omitted or marked unverified.

Main entry points: [`src/pipeline.ts`](https://github.com/kierandotai/jev-scout/blob/main/src/pipeline.ts) (Tool pipeline), [`src/server-mcp.ts`](https://github.com/kierandotai/jev-scout/blob/main/src/server-mcp.ts) (MCP tools), [`src/backends/resolve.ts`](https://github.com/kierandotai/jev-scout/blob/main/src/backends/resolve.ts) (Backend resolver), [`src/ledger.ts`](https://github.com/kierandotai/jev-scout/blob/main/src/ledger.ts) (Decision ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Agent interface"]
  node_mcp["MCP tools<br/>[server-mcp.ts]"]
end

subgraph group_research["Research workflow"]
  node_pipeline["Tool pipeline<br/>[pipeline.ts]"]
  node_resolver["Backend resolver<br/>[resolve.ts]"]
  node_searxng["SearXNG backend<br/>[searxng.ts]"]
  node_brave["Brave backend<br/>[brave.ts]"]
  node_ddg["DuckDuckGo backend<br/>[duckduckgo.ts]"]
  node_fetcher["Safe page fetcher<br/>[fetcher.ts]"]
end

subgraph group_judgment["Judgment controls"]
  node_config["Runtime config<br/>[config.ts]"]
  node_judge["Jev judging<br/>[judge.ts]"]
  node_cache[("Judgment cache<br/>[cache.ts]")]
  node_gate["Result gating<br/>[gate.ts]"]
  node_budget["Call and spend budget<br/>[budget.ts]"]
end

subgraph group_observability["Observability"]
  node_ledger[("Decision ledger<br/>[ledger.ts]")]
  node_dashboard["Live dashboard<br/>[dashboard.ts]"]
  node_drift["Drift analysis<br/>[drift.ts]"]
  node_hash["Content hashing<br/>[hash.ts]"]
end

node_agent(("Research agent"))
node_web(("Web sources"))
node_jev(("Jev service"))

node_agent -->|"calls tools"| node_mcp
node_mcp -->|"dispatches"| node_pipeline
node_pipeline -->|"uses settings"| node_config
node_pipeline -->|"resolves search"| node_resolver
node_resolver -.->|"selects backend"| node_searxng
node_resolver -.->|"selects backend"| node_brave
node_resolver -.->|"selects backend"| node_ddg
node_searxng -->|"searches"| node_web
node_brave -->|"searches"| node_web
node_ddg -->|"searches"| node_web
node_pipeline -->|"scores results"| node_judge
node_pipeline -->|"fetches pages"| node_fetcher
node_fetcher -->|"retrieves pages"| node_web
node_judge -->|"requests decisions"| node_jev
node_pipeline -->|"reads and writes"| node_cache
node_pipeline -->|"applies thresholds"| node_gate
node_pipeline -->|"reserves calls"| node_budget
node_pipeline -->|"appends decisions"| node_ledger
node_mcp -->|"starts dashboard"| node_dashboard
node_dashboard -->|"streams events"| node_ledger
node_mcp -.->|"reports activity"| node_ledger
node_drift -.->|"uses judgments"| node_judge
node_ledger -->|"hashes content"| node_hash

click node_mcp "https://github.com/kierandotai/jev-scout/blob/main/src/server-mcp.ts"
click node_pipeline "https://github.com/kierandotai/jev-scout/blob/main/src/pipeline.ts"
click node_config "https://github.com/kierandotai/jev-scout/blob/main/src/config.ts"
click node_resolver "https://github.com/kierandotai/jev-scout/blob/main/src/backends/resolve.ts"
click node_searxng "https://github.com/kierandotai/jev-scout/blob/main/src/backends/searxng.ts"
click node_brave "https://github.com/kierandotai/jev-scout/blob/main/src/backends/brave.ts"
click node_ddg "https://github.com/kierandotai/jev-scout/blob/main/src/backends/duckduckgo.ts"
click node_fetcher "https://github.com/kierandotai/jev-scout/blob/main/src/fetcher.ts"
click node_judge "https://github.com/kierandotai/jev-scout/blob/main/src/judge.ts"
click node_cache "https://github.com/kierandotai/jev-scout/blob/main/src/cache.ts"
click node_gate "https://github.com/kierandotai/jev-scout/blob/main/src/gate.ts"
click node_budget "https://github.com/kierandotai/jev-scout/blob/main/src/budget.ts"
click node_ledger "https://github.com/kierandotai/jev-scout/blob/main/src/ledger.ts"
click node_dashboard "https://github.com/kierandotai/jev-scout/blob/main/src/dashboard.ts"
click node_drift "https://github.com/kierandotai/jev-scout/blob/main/src/drift.ts"
click node_hash "https://github.com/kierandotai/jev-scout/blob/main/src/hash.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_mcp toneBlue
class node_pipeline,node_resolver,node_searxng,node_brave,node_ddg,node_fetcher toneAmber
class node_config,node_judge,node_cache,node_gate,node_budget toneMint
class node_ledger,node_dashboard,node_drift,node_hash toneRose
class node_agent,node_web,node_jev toneIndigo
```

## Components

### Agent interface

- [MCP tools](https://github.com/kierandotai/jev-scout/blob/main/src/server-mcp.ts): `src/server-mcp.ts`

### Research workflow

- [Tool pipeline](https://github.com/kierandotai/jev-scout/blob/main/src/pipeline.ts): `src/pipeline.ts`
- [Backend resolver](https://github.com/kierandotai/jev-scout/blob/main/src/backends/resolve.ts): `src/backends/resolve.ts`
- [SearXNG backend](https://github.com/kierandotai/jev-scout/blob/main/src/backends/searxng.ts): `src/backends/searxng.ts`
- [Brave backend](https://github.com/kierandotai/jev-scout/blob/main/src/backends/brave.ts): `src/backends/brave.ts`
- [DuckDuckGo backend](https://github.com/kierandotai/jev-scout/blob/main/src/backends/duckduckgo.ts): `src/backends/duckduckgo.ts`
- [Safe page fetcher](https://github.com/kierandotai/jev-scout/blob/main/src/fetcher.ts): `src/fetcher.ts`

### Judgment controls

- [Runtime config](https://github.com/kierandotai/jev-scout/blob/main/src/config.ts): `src/config.ts`
- [Jev judging](https://github.com/kierandotai/jev-scout/blob/main/src/judge.ts): `src/judge.ts`
- [Judgment cache](https://github.com/kierandotai/jev-scout/blob/main/src/cache.ts): `src/cache.ts`
- [Result gating](https://github.com/kierandotai/jev-scout/blob/main/src/gate.ts): `src/gate.ts`
- [Call and spend budget](https://github.com/kierandotai/jev-scout/blob/main/src/budget.ts): `src/budget.ts`

### Observability

- [Decision ledger](https://github.com/kierandotai/jev-scout/blob/main/src/ledger.ts): `src/ledger.ts`
- [Live dashboard](https://github.com/kierandotai/jev-scout/blob/main/src/dashboard.ts): `src/dashboard.ts`
- [Drift analysis](https://github.com/kierandotai/jev-scout/blob/main/src/drift.ts): `src/drift.ts`
- [Content hashing](https://github.com/kierandotai/jev-scout/blob/main/src/hash.ts): `src/hash.ts`

### Other components

- **Research agent**
- **Web sources**
- **Jev service**

## Connections

- Research agent → MCP tools: calls tools (evidence: `README.md`)
- MCP tools → Tool pipeline: dispatches (evidence: `src/server-mcp.ts`)
- Tool pipeline → Runtime config: uses settings (evidence: `src/pipeline.ts`)
- Tool pipeline → Backend resolver: resolves search (evidence: `src/pipeline.ts`)
- Backend resolver → SearXNG backend: selects backend (evidence: `src/backends/searxng.ts`)
- Backend resolver → Brave backend: selects backend (evidence: `src/backends/brave.ts`)
- Backend resolver → DuckDuckGo backend: selects backend (evidence: `src/backends/duckduckgo.ts`)
- SearXNG backend → Web sources: searches (evidence: `README.md`)
- Brave backend → Web sources: searches (evidence: `README.md`)
- DuckDuckGo backend → Web sources: searches (evidence: `README.md`)
- Tool pipeline → Jev judging: scores results (evidence: `src/pipeline.ts`)
- Tool pipeline → Safe page fetcher: fetches pages (evidence: `src/pipeline.ts`)
- Safe page fetcher → Web sources: retrieves pages (evidence: `README.md`)
- Jev judging → Jev service: requests decisions (evidence: `src/judge.ts`)
- Tool pipeline → Judgment cache: reads and writes (evidence: `src/pipeline.ts`)
- Tool pipeline → Result gating: applies thresholds (evidence: `src/pipeline.ts`)
- Tool pipeline → Call and spend budget: reserves calls (evidence: `src/pipeline.ts`)
- Tool pipeline → Decision ledger: appends decisions (evidence: `src/pipeline.ts`)
- MCP tools → Live dashboard: starts dashboard (evidence: `src/server-mcp.ts`)
- Live dashboard → Decision ledger: streams events (evidence: `src/dashboard.ts`)
- MCP tools → Decision ledger: reports activity (evidence: `src/server-mcp.ts`)
- Drift analysis → Jev judging: uses judgments (evidence: `src/drift.ts`)
- Decision ledger → Content hashing: hashes content (evidence: `src/ledger.ts`)
