# superagents-lab/jev-search architecture

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

## Overview

Jev Search turns a plain-language request into source and time choices, searches multiple web and vertical engines, then streams ranked, deduplicated results with relevance scores and editable filters. The browser submits through `/api/ask`; the server pipeline coordinates interpretation, search lanes, freshness handling, ranking, and merging. Search1API and configurable Jev providers are external services. The README documents provider and PWA capabilities; some implementation details are unsampled, so those links are shown only where documented or evidenced by the source index.

Main entry points: [`src/lib/pipeline.ts`](https://github.com/superagents-lab/jev-search/blob/main/src/lib/pipeline.ts) (Search pipeline), [`src/routes/search.tsx`](https://github.com/superagents-lab/jev-search/blob/main/src/routes/search.tsx) (Search page), [`src/lib/use-ask.ts`](https://github.com/superagents-lab/jev-search/blob/main/src/lib/use-ask.ts) (Stream consumer), [`src/routes/api/ask.ts`](https://github.com/superagents-lab/jev-search/blob/main/src/routes/api/ask.ts) (Ask endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Search experience"]
  node_home["Home page<br/>[index.tsx]"]
  node_searchpage["Search page<br/>[search.tsx]"]
  node_searchbox["Query entry<br/>[search-box.tsx]"]
  node_filters["Editable filters<br/>[filters.tsx]"]
  node_askhook["Stream consumer<br/>[use-ask.ts]"]
  node_results["Ranked results<br/>[results.tsx]"]
  node_working["Search progress<br/>[working.tsx]"]
  node_pwa["Offline app shell<br/>[sw.js]"]
end

subgraph group_request["Request workflow"]
  node_api["Ask endpoint<br/>[ask.ts]"]
  node_validate["Request validation<br/>[validate.ts]"]
  node_pipeline["Search pipeline<br/>[pipeline.ts]"]
  node_candidates["Query candidates<br/>[candidates.ts]"]
  node_sources["Source definitions<br/>[sources.ts]"]
end

subgraph group_judgment["Jev judgment"]
  node_judgeconfig["Provider selection<br/>[judge-config.ts]"]
  node_jev["Intent and ranking<br/>[typesafe.ts]"]
end

subgraph group_search["Search and results"]
  node_searchapi["Search1API client<br/>[search1api.ts]"]
  node_cache[("Search cache<br/>[cache.ts]")]
  node_freshness["Freshness handling<br/>[freshness.ts]"]
  node_merge["URL result merging<br/>[merge.ts]"]
  node_rank["Ranking and clusters<br/>[rank.ts]"]
end

node_user(("Search user"))
node_jevservice{{"Jev provider services"}}
node_searchservice{{"Search1API service"}}

node_user -->|"opens"| node_home
node_home -->|"renders"| node_searchbox
node_searchbox -->|"navigates"| node_searchpage
node_searchpage -->|"starts search"| node_askhook
node_searchpage -->|"renders"| node_filters
node_searchpage -->|"renders"| node_results
node_searchpage -->|"renders"| node_working
node_askhook -->|"posts and reads stream"| node_api
node_api -->|"validates request"| node_validate
node_api -->|"runs"| node_pipeline
node_pipeline -->|"builds candidates"| node_candidates
node_pipeline -->|"selects lanes"| node_sources
node_pipeline -->|"interprets and reranks"| node_jev
node_jev -->|"calls provider"| node_jevservice
node_pipeline -->|"checks cache"| node_cache
node_pipeline -->|"runs search lanes"| node_searchapi
node_searchapi -->|"requests results"| node_searchservice
node_pipeline -->|"filters stale results"| node_freshness
node_pipeline -->|"uses ranked items"| node_rank
node_pipeline -->|"merges results"| node_merge
node_askhook -->|"supplies streamed state"| node_results
node_user -->|"installs app"| node_pwa
node_judgeconfig -->|"configures providers"| node_jev

click node_home "https://github.com/superagents-lab/jev-search/blob/main/src/routes/index.tsx"
click node_searchpage "https://github.com/superagents-lab/jev-search/blob/main/src/routes/search.tsx"
click node_searchbox "https://github.com/superagents-lab/jev-search/blob/main/src/components/search-box.tsx"
click node_filters "https://github.com/superagents-lab/jev-search/blob/main/src/components/filters.tsx"
click node_askhook "https://github.com/superagents-lab/jev-search/blob/main/src/lib/use-ask.ts"
click node_results "https://github.com/superagents-lab/jev-search/blob/main/src/components/results.tsx"
click node_working "https://github.com/superagents-lab/jev-search/blob/main/src/components/working.tsx"
click node_pwa "https://github.com/superagents-lab/jev-search/blob/main/public/sw.js"
click node_api "https://github.com/superagents-lab/jev-search/blob/main/src/routes/api/ask.ts"
click node_validate "https://github.com/superagents-lab/jev-search/blob/main/src/lib/validate.ts"
click node_pipeline "https://github.com/superagents-lab/jev-search/blob/main/src/lib/pipeline.ts"
click node_candidates "https://github.com/superagents-lab/jev-search/blob/main/src/lib/candidates.ts"
click node_sources "https://github.com/superagents-lab/jev-search/blob/main/src/lib/sources.ts"
click node_judgeconfig "https://github.com/superagents-lab/jev-search/blob/main/src/lib/judge-config.ts"
click node_jev "https://github.com/superagents-lab/jev-search/blob/main/src/lib/typesafe.ts"
click node_searchapi "https://github.com/superagents-lab/jev-search/blob/main/src/lib/search1api.ts"
click node_cache "https://github.com/superagents-lab/jev-search/blob/main/src/lib/cache.ts"
click node_freshness "https://github.com/superagents-lab/jev-search/blob/main/src/lib/freshness.ts"
click node_merge "https://github.com/superagents-lab/jev-search/blob/main/src/lib/merge.ts"
click node_rank "https://github.com/superagents-lab/jev-search/blob/main/src/lib/rank.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_home,node_searchpage,node_searchbox,node_filters,node_askhook,node_results,node_working,node_pwa,node_user toneBlue
class node_api,node_validate,node_pipeline,node_candidates,node_sources toneAmber
class node_judgeconfig,node_jev,node_searchservice toneMint
class node_searchapi,node_cache,node_freshness,node_merge,node_rank toneRose
class node_jevservice toneIndigo
```

## Components

### Search experience

- [Home page](https://github.com/superagents-lab/jev-search/blob/main/src/routes/index.tsx): `src/routes/index.tsx`
- [Search page](https://github.com/superagents-lab/jev-search/blob/main/src/routes/search.tsx): `src/routes/search.tsx`
- [Query entry](https://github.com/superagents-lab/jev-search/blob/main/src/components/search-box.tsx): `src/components/search-box.tsx`
- [Editable filters](https://github.com/superagents-lab/jev-search/blob/main/src/components/filters.tsx): `src/components/filters.tsx`
- [Stream consumer](https://github.com/superagents-lab/jev-search/blob/main/src/lib/use-ask.ts): `src/lib/use-ask.ts`
- [Ranked results](https://github.com/superagents-lab/jev-search/blob/main/src/components/results.tsx): `src/components/results.tsx`
- [Search progress](https://github.com/superagents-lab/jev-search/blob/main/src/components/working.tsx): `src/components/working.tsx`
- [Offline app shell](https://github.com/superagents-lab/jev-search/blob/main/public/sw.js): `public/sw.js`

### Request workflow

- [Ask endpoint](https://github.com/superagents-lab/jev-search/blob/main/src/routes/api/ask.ts): `src/routes/api/ask.ts`
- [Request validation](https://github.com/superagents-lab/jev-search/blob/main/src/lib/validate.ts): `src/lib/validate.ts`
- [Search pipeline](https://github.com/superagents-lab/jev-search/blob/main/src/lib/pipeline.ts): `src/lib/pipeline.ts`
- [Query candidates](https://github.com/superagents-lab/jev-search/blob/main/src/lib/candidates.ts): `src/lib/candidates.ts`
- [Source definitions](https://github.com/superagents-lab/jev-search/blob/main/src/lib/sources.ts): `src/lib/sources.ts`

### Jev judgment

- [Provider selection](https://github.com/superagents-lab/jev-search/blob/main/src/lib/judge-config.ts): `src/lib/judge-config.ts`
- [Intent and ranking](https://github.com/superagents-lab/jev-search/blob/main/src/lib/typesafe.ts): `src/lib/typesafe.ts`

### Search and results

- [Search1API client](https://github.com/superagents-lab/jev-search/blob/main/src/lib/search1api.ts): `src/lib/search1api.ts`
- [Search cache](https://github.com/superagents-lab/jev-search/blob/main/src/lib/cache.ts): `src/lib/cache.ts`
- [Freshness handling](https://github.com/superagents-lab/jev-search/blob/main/src/lib/freshness.ts): `src/lib/freshness.ts`
- [URL result merging](https://github.com/superagents-lab/jev-search/blob/main/src/lib/merge.ts): `src/lib/merge.ts`
- [Ranking and clusters](https://github.com/superagents-lab/jev-search/blob/main/src/lib/rank.ts): `src/lib/rank.ts`

### Other components

- **Search user**
- **Jev provider services**
- **Search1API service**

## Connections

- Search user → Home page: opens (evidence: `src/routes/index.tsx`)
- Home page → Query entry: renders (evidence: `src/routes/index.tsx`)
- Query entry → Search page: navigates (evidence: `src/components/search-box.tsx`)
- Search page → Stream consumer: starts search (evidence: `src/routes/search.tsx`)
- Search page → Editable filters: renders (evidence: `src/routes/search.tsx`)
- Search page → Ranked results: renders (evidence: `src/routes/search.tsx`)
- Search page → Search progress: renders (evidence: `src/routes/search.tsx`)
- Stream consumer → Ask endpoint: posts and reads stream (evidence: `src/lib/use-ask.ts`)
- Ask endpoint → Request validation: validates request (evidence: `src/routes/api/ask.ts`)
- Ask endpoint → Search pipeline: runs (evidence: `src/routes/api/ask.ts`)
- Search pipeline → Query candidates: builds candidates (evidence: `src/lib/pipeline.ts`)
- Search pipeline → Source definitions: selects lanes (evidence: `src/lib/pipeline.ts`)
- Search pipeline → Intent and ranking: interprets and reranks (evidence: `src/lib/pipeline.ts`)
- Intent and ranking → Jev provider services: calls provider (evidence: `README.md`)
- Search pipeline → Search cache: checks cache (evidence: `src/lib/pipeline.ts`)
- Search pipeline → Search1API client: runs search lanes (evidence: `src/lib/pipeline.ts`)
- Search1API client → Search1API service: requests results (evidence: `src/lib/search1api.ts`)
- Search pipeline → Freshness handling: filters stale results (evidence: `src/lib/pipeline.ts`)
- Search pipeline → Ranking and clusters: uses ranked items (evidence: `src/lib/pipeline.ts`)
- Search pipeline → URL result merging: merges results (evidence: `src/lib/pipeline.ts`)
- Stream consumer → Ranked results: supplies streamed state (evidence: `src/routes/search.tsx`)
- Search user → Offline app shell: installs app (evidence: `README.md`)
- Provider selection → Intent and ranking: configures providers (evidence: `src/lib/judge-config.ts`)
