# nerdprog/prompt_lab architecture

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

- Interactive diagram: https://gitdiagram.com/nerdprog/prompt_lab
- Repository: https://github.com/nerdprog/prompt_lab

## Overview

PromptLab is a web application for iteratively optimizing prompts: users submit a task, confirm extracted intent, and receive ranked prompts with a PDF report. Its central service coordinates rubric creation, candidate generation, bandit selection, Performer runs, Judge scoring, feedback-driven refinement, and final evaluation while tracking session state. The README documents additional capabilities such as intent-fidelity scoring, provider health checks, cancellation, and progress reporting. Relationships below are based on the README and SOURCE INDEX references; unsampled implementation details are not inferred beyond those references.

Main entry points: [`app/services/optimizer/optimization_service.py`](https://github.com/nerdprog/prompt_lab/blob/main/app/services/optimizer/optimization_service.py) (Optimization service), [`app/api/routes_optimization.py`](https://github.com/nerdprog/prompt_lab/blob/main/app/api/routes_optimization.py) (Optimization API), [`app/core/config.py`](https://github.com/nerdprog/prompt_lab/blob/main/app/core/config.py) (Runtime configuration), [`app/static/js/app.js`](https://github.com/nerdprog/prompt_lab/blob/main/app/static/js/app.js) (Browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_web_ui["Browser UI<br/>[app.js]"]
  node_page["Web page<br/>[index.html]"]
  node_api["Optimization API"]
end

subgraph group_orchestration["Optimization workflow"]
  node_schemas["Task schemas<br/>[task.py]"]
  node_validation["Input validation<br/>[validation.py]"]
  node_service["Optimization service"]
  node_understanding["Task understanding"]
  node_rubric["Rubric generation"]
  node_candidates["Candidate generation"]
  node_feedback["Feedback optimization"]
  node_insights["Session insights<br/>[insight_store.py]"]
end

subgraph group_evaluation["Prompt evaluation"]
  node_fidelity["Intent fidelity<br/>[intent_fidelity.py]"]
  node_selector["UCB selector<br/>[ucb.py]"]
end

subgraph group_providers["Model providers"]
  node_performer["Performer model<br/>[performer.py]"]
  node_judge["Judge model<br/>[judge.py]"]
  node_optimizer_model["Optimizer model<br/>[optimizer.py]"]
  node_provider_health["Provider health<br/>[health.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_session["Session and reporting"]
  node_session_store[("In-memory sessions<br/>[session_state.py]")]
  node_report["PDF report"]
end

node_user(("User"))
node_llm_services{{"External LLM providers"}}

node_user -->|"submits task"| node_web_ui
node_web_ui -.->|"uses page"| node_page
node_web_ui -->|"calls API"| node_api
node_api -->|"dispatches optimization"| node_service
node_api -->|"reads session"| node_session_store
node_api -->|"checks providers"| node_provider_health
node_api -->|"serves report"| node_report
node_service -->|"validates prompt"| node_validation
node_service -->|"extracts intent"| node_understanding
node_understanding -->|"creates intent"| node_schemas
node_service -->|"builds rubric"| node_rubric
node_service -->|"generates candidates"| node_candidates
node_candidates -->|"requests prompts"| node_optimizer_model
node_candidates -->|"checks fidelity"| node_fidelity
node_service -->|"selects candidates"| node_selector
node_service -->|"executes prompts"| node_performer
node_service -->|"evaluates responses"| node_judge
node_service -->|"refines candidates"| node_feedback
node_service -->|"updates insights"| node_insights
node_feedback -->|"uses evidence"| node_insights
node_service -->|"updates session"| node_session_store
node_service -->|"creates report"| node_report
node_performer -->|"calls Gemini"| node_llm_services
node_optimizer_model -->|"calls Gemini"| node_llm_services
node_judge -->|"calls Groq"| node_llm_services
node_provider_health -->|"probes providers"| node_llm_services
node_performer -->|"reads settings"| node_config
node_optimizer_model -->|"reads settings"| node_config
node_judge -->|"reads settings"| node_config
node_provider_health -->|"reads settings"| node_config

click node_web_ui "https://github.com/nerdprog/prompt_lab/blob/main/app/static/js/app.js"
click node_page "https://github.com/nerdprog/prompt_lab/blob/main/app/templates/index.html"
click node_api "https://github.com/nerdprog/prompt_lab/blob/main/app/api/routes_optimization.py"
click node_schemas "https://github.com/nerdprog/prompt_lab/blob/main/app/schemas/task.py"
click node_validation "https://github.com/nerdprog/prompt_lab/blob/main/app/utils/validation.py"
click node_service "https://github.com/nerdprog/prompt_lab/blob/main/app/services/optimizer/optimization_service.py"
click node_understanding "https://github.com/nerdprog/prompt_lab/blob/main/app/services/intent/task_understanding.py"
click node_rubric "https://github.com/nerdprog/prompt_lab/blob/main/app/services/rubric/rubric_generator.py"
click node_candidates "https://github.com/nerdprog/prompt_lab/blob/main/app/services/optimizer/candidate_generator.py"
click node_feedback "https://github.com/nerdprog/prompt_lab/blob/main/app/services/optimizer/feedback_optimizer.py"
click node_insights "https://github.com/nerdprog/prompt_lab/blob/main/app/services/insights/insight_store.py"
click node_fidelity "https://github.com/nerdprog/prompt_lab/blob/main/app/services/intent/intent_fidelity.py"
click node_selector "https://github.com/nerdprog/prompt_lab/blob/main/app/services/selector/ucb.py"
click node_performer "https://github.com/nerdprog/prompt_lab/blob/main/app/services/llm/performer.py"
click node_judge "https://github.com/nerdprog/prompt_lab/blob/main/app/services/llm/judge.py"
click node_optimizer_model "https://github.com/nerdprog/prompt_lab/blob/main/app/services/llm/optimizer.py"
click node_provider_health "https://github.com/nerdprog/prompt_lab/blob/main/app/services/providers/health.py"
click node_config "https://github.com/nerdprog/prompt_lab/blob/main/app/core/config.py"
click node_session_store "https://github.com/nerdprog/prompt_lab/blob/main/app/state/session_state.py"
click node_report "https://github.com/nerdprog/prompt_lab/blob/main/app/services/pdf/report_generator.py"

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_web_ui,node_page,node_api,node_user toneBlue
class node_schemas,node_validation,node_service,node_understanding,node_rubric,node_candidates,node_feedback,node_insights toneAmber
class node_fidelity,node_selector toneMint
class node_performer,node_judge,node_optimizer_model,node_provider_health,node_config toneRose
class node_session_store,node_report,node_llm_services toneIndigo
```

## Components

### Web interface

- [Browser UI](https://github.com/nerdprog/prompt_lab/blob/main/app/static/js/app.js): `app/static/js/app.js`
- [Web page](https://github.com/nerdprog/prompt_lab/blob/main/app/templates/index.html): `app/templates/index.html`
- [Optimization API](https://github.com/nerdprog/prompt_lab/blob/main/app/api/routes_optimization.py): `app/api/routes_optimization.py`

### Optimization workflow

- [Task schemas](https://github.com/nerdprog/prompt_lab/blob/main/app/schemas/task.py): `app/schemas/task.py`
- [Input validation](https://github.com/nerdprog/prompt_lab/blob/main/app/utils/validation.py): `app/utils/validation.py`
- [Optimization service](https://github.com/nerdprog/prompt_lab/blob/main/app/services/optimizer/optimization_service.py): `app/services/optimizer/optimization_service.py`
- [Task understanding](https://github.com/nerdprog/prompt_lab/blob/main/app/services/intent/task_understanding.py): `app/services/intent/task_understanding.py`
- [Rubric generation](https://github.com/nerdprog/prompt_lab/blob/main/app/services/rubric/rubric_generator.py): `app/services/rubric/rubric_generator.py`
- [Candidate generation](https://github.com/nerdprog/prompt_lab/blob/main/app/services/optimizer/candidate_generator.py): `app/services/optimizer/candidate_generator.py`
- [Feedback optimization](https://github.com/nerdprog/prompt_lab/blob/main/app/services/optimizer/feedback_optimizer.py): `app/services/optimizer/feedback_optimizer.py`
- [Session insights](https://github.com/nerdprog/prompt_lab/blob/main/app/services/insights/insight_store.py): `app/services/insights/insight_store.py`

### Prompt evaluation

- [Intent fidelity](https://github.com/nerdprog/prompt_lab/blob/main/app/services/intent/intent_fidelity.py): `app/services/intent/intent_fidelity.py`
- [UCB selector](https://github.com/nerdprog/prompt_lab/blob/main/app/services/selector/ucb.py): `app/services/selector/ucb.py`

### Model providers

- [Performer model](https://github.com/nerdprog/prompt_lab/blob/main/app/services/llm/performer.py): `app/services/llm/performer.py`
- [Judge model](https://github.com/nerdprog/prompt_lab/blob/main/app/services/llm/judge.py): `app/services/llm/judge.py`
- [Optimizer model](https://github.com/nerdprog/prompt_lab/blob/main/app/services/llm/optimizer.py): `app/services/llm/optimizer.py`
- [Provider health](https://github.com/nerdprog/prompt_lab/blob/main/app/services/providers/health.py): `app/services/providers/health.py`
- [Runtime configuration](https://github.com/nerdprog/prompt_lab/blob/main/app/core/config.py): `app/core/config.py`

### Session and reporting

- [In-memory sessions](https://github.com/nerdprog/prompt_lab/blob/main/app/state/session_state.py): `app/state/session_state.py`
- [PDF report](https://github.com/nerdprog/prompt_lab/blob/main/app/services/pdf/report_generator.py): `app/services/pdf/report_generator.py`

### Other components

- **User**
- **External LLM providers**

## Connections

- User → Browser UI: submits task (evidence: `README.md`)
- Browser UI → Web page: uses page
- Browser UI → Optimization API: calls API (evidence: `README.md`)
- Optimization API → Optimization service: dispatches optimization (evidence: `app/api/routes_optimization.py`)
- Optimization API → In-memory sessions: reads session (evidence: `app/api/routes_optimization.py`)
- Optimization API → Provider health: checks providers (evidence: `app/api/routes_optimization.py`)
- Optimization API → PDF report: serves report (evidence: `app/api/routes_optimization.py`)
- Optimization service → Input validation: validates prompt (evidence: `app/services/optimizer/optimization_service.py`)
- Optimization service → Task understanding: extracts intent (evidence: `app/services/optimizer/optimization_service.py`)
- Task understanding → Task schemas: creates intent (evidence: `app/services/intent/task_understanding.py`)
- Optimization service → Rubric generation: builds rubric (evidence: `app/services/optimizer/optimization_service.py`)
- Optimization service → Candidate generation: generates candidates (evidence: `app/services/optimizer/optimization_service.py`)
- Candidate generation → Optimizer model: requests prompts (evidence: `app/services/optimizer/candidate_generator.py`)
- Candidate generation → Intent fidelity: checks fidelity (evidence: `app/services/optimizer/candidate_generator.py`)
- Optimization service → UCB selector: selects candidates (evidence: `app/services/optimizer/optimization_service.py`)
- Optimization service → Performer model: executes prompts (evidence: `app/services/optimizer/optimization_service.py`)
- Optimization service → Judge model: evaluates responses (evidence: `app/services/optimizer/optimization_service.py`)
- Optimization service → Feedback optimization: refines candidates (evidence: `app/services/optimizer/optimization_service.py`)
- Optimization service → Session insights: updates insights (evidence: `app/services/optimizer/optimization_service.py`)
- Feedback optimization → Session insights: uses evidence (evidence: `app/services/optimizer/feedback_optimizer.py`)
- Optimization service → In-memory sessions: updates session (evidence: `app/services/optimizer/optimization_service.py`)
- Optimization service → PDF report: creates report (evidence: `app/services/optimizer/optimization_service.py`)
- Performer model → External LLM providers: calls Gemini (evidence: `README.md`)
- Optimizer model → External LLM providers: calls Gemini (evidence: `README.md`)
- Judge model → External LLM providers: calls Groq (evidence: `README.md`)
- Provider health → External LLM providers: probes providers (evidence: `app/services/providers/health.py`)
- Performer model → Runtime configuration: reads settings (evidence: `app/services/llm/performer.py`)
- Optimizer model → Runtime configuration: reads settings (evidence: `app/services/llm/optimizer.py`)
- Judge model → Runtime configuration: reads settings (evidence: `app/services/llm/judge.py`)
- Provider health → Runtime configuration: reads settings (evidence: `app/services/providers/health.py`)
