# ertugrulmutlu/promptledger architecture

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

## Overview

PromptLedger is a local-first prompt version-control tool: developers add and inspect prompt versions, compare or review changes, attach release labels and markers, and optionally record external evaluation results and apply regression gates. The CLI and Python API use a core ledger backed by SQLite; a local HTTP dashboard presents read-only prompt history and evaluation data. The graph preserves review, rendering, evaluation, and dashboard capabilities documented in the README. Several source excerpts are partial, so only evidenced calls are connected; dashboard browser/API wiring is documented at a high level.

Main entry points: [`src/promptledger/core.py`](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py) (Ledger Operations), [`src/promptledger/cli.py`](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/cli.py) (CLI), [`src/promptledger/dashboard/server.py`](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/dashboard/server.py) (HTTP Server), [`src/promptledger/dashboard/api.py`](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/dashboard/api.py) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_streamlit_ui["Legacy UI<br/>[ui.py]"]
end

subgraph group_ledger["Prompt Ledger"]
  node_ledger_core["Ledger Operations<br/>[core.py]"]
  node_sqlite[("SQLite Store<br/>[db.py]")]
  node_prompt_history["Version History<br/>[core.py]"]
  node_labels_markers["Labels &amp; Markers<br/>[core.py]"]
  node_search_export["Search &amp; Export<br/>[core.py]"]
end

subgraph group_assessment["Review &amp; Evaluation"]
  node_diff_review["Diff &amp; Review<br/>[core.py]"]
  node_review_logic["Review Summaries<br/>[review.py]"]
  node_rendering["Review Rendering<br/>[render.py]"]
  node_eval_runs["Evaluation Runs<br/>[evaluation.py]"]
  node_regression_gates["Regression Gates<br/>[evaluation.py]"]
end

subgraph group_dashboard["Local Dashboard"]
  node_dashboard_server["HTTP Server<br/>[server.py]"]
  node_dashboard_api["Dashboard API<br/>[api.py]"]
  node_dashboard_client["Dashboard Browser<br/>[app.js]"]
end

node_developer(("Developer"))
node_python_client(("Python Client"))
node_browser_user(("Browser User"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"calls ledger"| node_ledger_core
node_python_client -->|"calls API"| node_python_api
node_python_api -->|"exposes operations"| node_ledger_core
node_cli -.->|"launches optional UI"| node_streamlit_ui
node_ledger_core -->|"manages versions"| node_prompt_history
node_ledger_core -->|"manages pointers"| node_labels_markers
node_ledger_core -->|"supports queries"| node_search_export
node_ledger_core -->|"reads and writes"| node_sqlite
node_ledger_core -->|"compares versions"| node_diff_review
node_ledger_core -->|"builds summaries"| node_review_logic
node_rendering -->|"renders results"| node_review_logic
node_ledger_core -->|"uses renderers"| node_rendering
node_ledger_core -->|"records and compares"| node_eval_runs
node_ledger_core -.->|"checks policies"| node_regression_gates
node_developer -->|"opens dashboard"| node_dashboard_server
node_dashboard_server -->|"routes requests"| node_dashboard_api
node_dashboard_api -->|"queries ledger"| node_ledger_core
node_dashboard_api -->|"lists evaluations"| node_eval_runs
node_browser_user -->|"views workspace"| node_dashboard_client
node_dashboard_server -->|"serves static files"| node_dashboard_client

click node_cli "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/cli.py"
click node_python_api "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/__init__.py"
click node_streamlit_ui "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/ui.py"
click node_ledger_core "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py"
click node_sqlite "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/db.py"
click node_prompt_history "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py"
click node_labels_markers "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py"
click node_search_export "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py"
click node_diff_review "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py"
click node_review_logic "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/review.py"
click node_rendering "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/render.py"
click node_eval_runs "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/evaluation.py"
click node_regression_gates "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/evaluation.py"
click node_dashboard_server "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/dashboard/server.py"
click node_dashboard_api "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/dashboard/api.py"
click node_dashboard_client "https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/dashboard/static/app.js"

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_cli,node_python_api,node_streamlit_ui,node_python_client,node_browser_user toneBlue
class node_ledger_core,node_sqlite,node_prompt_history,node_labels_markers,node_search_export toneAmber
class node_diff_review,node_review_logic,node_rendering,node_eval_runs,node_regression_gates toneMint
class node_dashboard_server,node_dashboard_api,node_dashboard_client toneRose
class node_developer toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/cli.py): `src/promptledger/cli.py`
- [Python API](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/__init__.py): `src/promptledger/__init__.py`
- [Legacy UI](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/ui.py): `src/promptledger/ui.py`

### Prompt Ledger

- [Ledger Operations](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py): `src/promptledger/core.py`
- [SQLite Store](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/db.py): `src/promptledger/db.py`
- [Version History](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py): `src/promptledger/core.py`
- [Labels & Markers](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py): `src/promptledger/core.py`
- [Search & Export](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py): `src/promptledger/core.py`

### Review & Evaluation

- [Diff & Review](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/core.py): `src/promptledger/core.py`
- [Review Summaries](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/review.py): `src/promptledger/review.py`
- [Review Rendering](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/render.py): `src/promptledger/render.py`
- [Evaluation Runs](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/evaluation.py): `src/promptledger/evaluation.py`
- [Regression Gates](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/evaluation.py): `src/promptledger/evaluation.py`

### Local Dashboard

- [HTTP Server](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/dashboard/server.py): `src/promptledger/dashboard/server.py`
- [Dashboard API](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/dashboard/api.py): `src/promptledger/dashboard/api.py`
- [Dashboard Browser](https://github.com/ertugrulmutlu/promptledger/blob/main/src/promptledger/dashboard/static/app.js): `src/promptledger/dashboard/static/app.js`

### Other components

- **Developer**
- **Python Client**
- **Browser User**

## Connections

- Developer → CLI: runs commands (evidence: `README.md`)
- CLI → Ledger Operations: calls ledger (evidence: `src/promptledger/cli.py`)
- Python Client → Python API: calls API (evidence: `README.md`)
- Python API → Ledger Operations: exposes operations (evidence: `src/promptledger/__init__.py`)
- CLI → Legacy UI: launches optional UI (evidence: `src/promptledger/cli.py`)
- Ledger Operations → Version History: manages versions (evidence: `README.md`)
- Ledger Operations → Labels & Markers: manages pointers (evidence: `README.md`)
- Ledger Operations → Search & Export: supports queries (evidence: `README.md`)
- Ledger Operations → SQLite Store: reads and writes (evidence: `src/promptledger/core.py`)
- Ledger Operations → Diff & Review: compares versions (evidence: `src/promptledger/core.py`)
- Ledger Operations → Review Summaries: builds summaries (evidence: `src/promptledger/core.py`)
- Review Rendering → Review Summaries: renders results (evidence: `src/promptledger/render.py`)
- Ledger Operations → Review Rendering: uses renderers (evidence: `src/promptledger/core.py`)
- Ledger Operations → Evaluation Runs: records and compares (evidence: `src/promptledger/core.py`)
- Ledger Operations → Regression Gates: checks policies (evidence: `README.md`)
- Developer → HTTP Server: opens dashboard (evidence: `README.md`)
- HTTP Server → Dashboard API: routes requests (evidence: `src/promptledger/dashboard/server.py`)
- Dashboard API → Ledger Operations: queries ledger (evidence: `src/promptledger/dashboard/api.py`)
- Dashboard API → Evaluation Runs: lists evaluations (evidence: `src/promptledger/dashboard/api.py`)
- Browser User → Dashboard Browser: views workspace (evidence: `README.md`)
- HTTP Server → Dashboard Browser: serves static files (evidence: `README.md`)
