# mohanish3/eval-atlas architecture

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

- Interactive diagram: https://gitdiagram.com/mohanish3/eval-atlas
- Repository: https://github.com/mohanish3/eval-atlas

## Overview

Eval Atlas is a browser-based LLM evaluation dashboard. Users create or upload an eval set, configure a run and model providers, then inspect streamed question results and category-level accuracy. A second workflow runs prompt research: select a target model and research model, iterate and score candidate prompts, inspect trials, and promote the best prompt. The tree and excerpts establish the research route’s orchestration and SSE handling; several main-evaluation and persistence connections are inferred only at the subsystem level, so uncertain internal calls are omitted.

Main entry points: [`backend/src/routes/promptResearch.ts`](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/routes/promptResearch.ts) (Research routes), [`frontend/src/App.tsx`](https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/App.tsx) (App routes), [`frontend/src/pages/EvalResearch.tsx`](https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/pages/EvalResearch.tsx) (Research view), [`backend/src/server.ts`](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/server.ts) (Express server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_app["App routes<br/>[App.tsx]"]
  node_eval_pages["Eval pages"]
  node_research_page["Research view<br/>[EvalResearch.tsx]"]
  node_eval_stream["Run stream hook<br/>[useEvalStream.ts]"]
  node_research_stream["Research stream hook"]
  node_client_store["Run state<br/>[useEvalStore.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API"]
  node_server["Express server<br/>[server.ts]"]
  node_eval_routes["Eval routes<br/>[evals.ts]"]
  node_research_routes["Research routes<br/>[promptResearch.ts]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_sets["Eval sets<br/>[evals.ts]"]
  node_eval_runner["Eval runner<br/>[runner.ts]"]
  node_scorer["Answer scorer<br/>[scorer.ts]"]
  node_providers{{"Model adapters"}}
end

subgraph group_research["Prompt research"]
  node_research_runner["Research loop"]
  node_research_budget["Research budget<br/>[researchBudget.ts]"]
  node_sse["SSE registry<br/>[sseManager.ts]"]
end

subgraph group_storage["Persistence"]
  node_eval_store[("Eval fallback store<br/>[fallbackStore.ts]")]
  node_research_store[("Research store")]
  node_postgres[("PostgreSQL<br/>[connection.ts]")]
end

node_user(("Browser user"))
node_model_services{{"LLM providers"}}

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_eval_pages
node_app -->|"routes to"| node_research_page
node_eval_pages -->|"requests data"| node_api_client
node_research_page -->|"loads and promotes"| node_api_client
node_research_page -->|"subscribes"| node_research_stream
node_eval_stream -->|"updates results"| node_client_store
node_research_stream -->|"receives events"| node_sse
node_api_client -->|"HTTP requests"| node_server
node_server -->|"mounts routes"| node_eval_routes
node_server -->|"mounts routes"| node_research_routes
node_eval_routes -->|"runs evaluations"| node_eval_runner
node_eval_runner -->|"scores answers"| node_scorer
node_eval_runner -->|"queries models"| node_providers
node_providers -->|"sends prompts"| node_model_services
node_research_routes -->|"loads memory set"| node_eval_store
node_research_routes -->|"loads eval set"| node_postgres
node_research_routes -->|"resolves budget"| node_research_budget
node_research_routes -->|"creates and reads runs"| node_research_store
node_research_routes -->|"starts asynchronously"| node_research_runner
node_research_routes -->|"registers stream clients"| node_sse
node_research_runner -->|"persists research"| node_research_store
node_research_runner -->|"broadcasts trials"| node_sse
node_research_store -->|"persists runs"| node_postgres

click node_app "https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/App.tsx"
click node_eval_pages "https://github.com/mohanish3/eval-atlas/tree/main/frontend/src/pages"
click node_research_page "https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/pages/EvalResearch.tsx"
click node_eval_stream "https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/hooks/useEvalStream.ts"
click node_research_stream "https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/hooks/useResearchStream.ts"
click node_client_store "https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/store/useEvalStore.ts"
click node_api_client "https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/services/api.ts"
click node_server "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/server.ts"
click node_eval_routes "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/routes/evals.ts"
click node_research_routes "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/routes/promptResearch.ts"
click node_eval_sets "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/routes/evals.ts"
click node_eval_runner "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/runner.ts"
click node_scorer "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/scorer.ts"
click node_providers "https://github.com/mohanish3/eval-atlas/tree/main/backend/src/evals/adapters"
click node_research_runner "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/promptResearchRunner.ts"
click node_research_budget "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/researchBudget.ts"
click node_sse "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/sseManager.ts"
click node_eval_store "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/fallbackStore.ts"
click node_research_store "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/promptResearchStore.ts"
click node_postgres "https://github.com/mohanish3/eval-atlas/blob/main/backend/src/db/connection.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_eval_pages,node_research_page,node_eval_stream,node_research_stream,node_client_store,node_api_client,node_user toneBlue
class node_server,node_eval_routes,node_research_routes toneAmber
class node_eval_sets,node_eval_runner,node_scorer,node_providers toneMint
class node_research_runner,node_research_budget,node_sse toneRose
class node_eval_store,node_research_store,node_postgres,node_model_services toneIndigo
```

## Components

### Dashboard

- [App routes](https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Eval pages](https://github.com/mohanish3/eval-atlas/tree/main/frontend/src/pages): `frontend/src/pages`
- [Research view](https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/pages/EvalResearch.tsx): `frontend/src/pages/EvalResearch.tsx`
- [Run stream hook](https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/hooks/useEvalStream.ts): `frontend/src/hooks/useEvalStream.ts`
- [Research stream hook](https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/hooks/useResearchStream.ts): `frontend/src/hooks/useResearchStream.ts`
- [Run state](https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/store/useEvalStore.ts): `frontend/src/store/useEvalStore.ts`
- [API client](https://github.com/mohanish3/eval-atlas/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API

- [Express server](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Eval routes](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/routes/evals.ts): `backend/src/routes/evals.ts`
- [Research routes](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/routes/promptResearch.ts): `backend/src/routes/promptResearch.ts`

### Evaluation

- [Eval sets](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/routes/evals.ts): `backend/src/routes/evals.ts`
- [Eval runner](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/runner.ts): `backend/src/evals/runner.ts`
- [Answer scorer](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/scorer.ts): `backend/src/evals/scorer.ts`
- [Model adapters](https://github.com/mohanish3/eval-atlas/tree/main/backend/src/evals/adapters): `backend/src/evals/adapters`

### Prompt research

- [Research loop](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/promptResearchRunner.ts): `backend/src/evals/promptResearchRunner.ts`
- [Research budget](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/researchBudget.ts): `backend/src/evals/researchBudget.ts`
- [SSE registry](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/sseManager.ts): `backend/src/evals/sseManager.ts`

### Persistence

- [Eval fallback store](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/fallbackStore.ts): `backend/src/evals/fallbackStore.ts`
- [Research store](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/evals/promptResearchStore.ts): `backend/src/evals/promptResearchStore.ts`
- [PostgreSQL](https://github.com/mohanish3/eval-atlas/blob/main/backend/src/db/connection.ts): `backend/src/db/connection.ts`

### Other components

- **Browser user**
- **LLM providers**

## Connections

- Browser user → App routes: uses
- App routes → Eval pages: routes to
- App routes → Research view: routes to
- Eval pages → API client: requests data
- Research view → API client: loads and promotes
- Research view → Research stream hook: subscribes
- Run stream hook → Run state: updates results
- Research stream hook → SSE registry: receives events
- API client → Express server: HTTP requests
- Express server → Eval routes: mounts routes
- Express server → Research routes: mounts routes
- Eval routes → Eval runner: runs evaluations
- Eval runner → Answer scorer: scores answers
- Eval runner → Model adapters: queries models
- Model adapters → LLM providers: sends prompts
- Research routes → Eval fallback store: loads memory set
- Research routes → PostgreSQL: loads eval set
- Research routes → Research budget: resolves budget
- Research routes → Research store: creates and reads runs
- Research routes → Research loop: starts asynchronously
- Research routes → SSE registry: registers stream clients
- Research loop → Research store: persists research
- Research loop → SSE registry: broadcasts trials
- Research store → PostgreSQL: persists runs