# crzyc0d3r/ocr-eval-playground architecture

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

- Interactive diagram: https://gitdiagram.com/crzyc0d3r/ocr-eval-playground
- Repository: https://github.com/crzyc0d3r/ocr-eval-playground

## Overview

Open-Source OCR Playground lets an engineer compare local OCR engines against a document’s ground truth. The workflow starts in the Streamlit UI or headless CLI: load a bundled sample or supply an image and transcription, select available engines (with offline mocks as fallback), then evaluate each output with text metrics and an optional G-Eval judge. Results are combined into a composite score, ranked, and rendered as a leaderboard. The graph preserves the five documented real-engine adapters and both judge paths; adapter-to-registry wiring is documented in the registry excerpt, while UI/CLI behavior is excerpted directly.

Main entry points: [`ocreval/engines/__init__.py`](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/__init__.py) (Engine registry), [`ocreval/evaluator.py`](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/evaluator.py) (Evaluation orchestrator), [`app.py`](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/app.py) (Streamlit UI), [`run_eval.py`](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/run_eval.py) (Headless CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_cli["Headless CLI<br/>[run_eval.py]"]
  node_samples["Sample loader<br/>[samples.py]"]
  node_document["Document model<br/>[config.py]"]
end

subgraph group_ocr["OCR engines"]
  node_registry["Engine registry<br/>[__init__.py]"]
  node_engine_base["Engine runtime<br/>[base.py]"]
  node_mock["Mock OCR tiers<br/>[mock.py]"]
  node_chandra["Chandra adapter<br/>[chandra.py]"]
  node_deepseek["DeepSeek adapter<br/>[deepseek_ocr.py]"]
  node_qwen["Qwen3-VL adapter<br/>[qwen3_vl.py]"]
  node_dots["dots.ocr adapter<br/>[dots_ocr.py]"]
  node_granite["Granite adapter<br/>[granite_docling.py]"]
end

subgraph group_scoring["Evaluation"]
  node_evaluator["Evaluation orchestrator<br/>[evaluator.py]"]
  node_text_metrics["Text metrics<br/>[text_metrics.py]"]
  node_judge_select["Judge selection<br/>[geval.py]"]
  node_geval["G-Eval judge<br/>[geval.py]"]
  node_mock_judge["Mock judge<br/>[geval.py]"]
  node_score_model["Score and composite<br/>[config.py]"]
end

subgraph group_results["Results"]
  node_report["Leaderboard formatter<br/>[report.py]"]
  node_leaderboard["Ranked results<br/>[evaluator.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_streamlit
node_user -->|"runs"| node_cli
node_streamlit -->|"loads samples"| node_samples
node_samples -->|"creates"| node_document
node_streamlit -->|"creates uploads"| node_document
node_cli -->|"loads document"| node_samples
node_cli -->|"creates input"| node_document
node_streamlit -->|"selects engines"| node_registry
node_cli -->|"resolves engines"| node_registry
node_registry -->|"falls back to"| node_mock
node_registry -->|"registers"| node_chandra
node_registry -->|"registers"| node_deepseek
node_registry -->|"registers"| node_qwen
node_registry -->|"registers"| node_dots
node_registry -->|"registers"| node_granite
node_streamlit -->|"evaluates"| node_evaluator
node_cli -->|"evaluates"| node_evaluator
node_evaluator -->|"resolves defaults"| node_registry
node_evaluator -->|"runs engines"| node_engine_base
node_engine_base -->|"accepts input"| node_document
node_mock -->|"reads text"| node_document
node_evaluator -->|"computes metrics"| node_text_metrics
node_evaluator -->|"selects judge"| node_judge_select
node_judge_select -->|"chooses when configured"| node_geval
node_judge_select -->|"falls back to"| node_mock_judge
node_mock_judge -->|"uses metrics"| node_text_metrics
node_evaluator -->|"computes composite"| node_score_model
node_evaluator -->|"ranks scores"| node_leaderboard
node_streamlit -->|"formats rows"| node_report
node_cli -->|"formats output"| node_report
node_report -->|"renders"| node_leaderboard
node_streamlit -->|"displays"| node_leaderboard
node_cli -->|"prints"| node_leaderboard

click node_streamlit "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/app.py"
click node_cli "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/run_eval.py"
click node_samples "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/samples.py"
click node_document "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/config.py"
click node_registry "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/__init__.py"
click node_engine_base "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/base.py"
click node_mock "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/mock.py"
click node_chandra "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/chandra.py"
click node_deepseek "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/deepseek_ocr.py"
click node_qwen "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/qwen3_vl.py"
click node_dots "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/dots_ocr.py"
click node_granite "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/granite_docling.py"
click node_evaluator "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/evaluator.py"
click node_text_metrics "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/metrics/text_metrics.py"
click node_judge_select "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/metrics/geval.py"
click node_geval "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/metrics/geval.py"
click node_mock_judge "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/metrics/geval.py"
click node_score_model "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/config.py"
click node_report "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/report.py"
click node_leaderboard "https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/evaluator.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_streamlit,node_cli,node_samples,node_document,node_user toneBlue
class node_registry,node_engine_base,node_mock,node_chandra,node_deepseek,node_qwen,node_dots,node_granite toneAmber
class node_evaluator,node_text_metrics,node_judge_select,node_geval,node_mock_judge,node_score_model toneMint
class node_report,node_leaderboard toneRose
```

## Components

### User entry

- [Streamlit UI](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/app.py): `app.py`
- [Headless CLI](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/run_eval.py): `run_eval.py`
- [Sample loader](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/samples.py): `ocreval/samples.py`
- [Document model](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/config.py): `ocreval/config.py`

### OCR engines

- [Engine registry](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/__init__.py): `ocreval/engines/__init__.py`
- [Engine runtime](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/base.py): `ocreval/engines/base.py`
- [Mock OCR tiers](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/mock.py): `ocreval/engines/mock.py`
- [Chandra adapter](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/chandra.py): `ocreval/engines/chandra.py`
- [DeepSeek adapter](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/deepseek_ocr.py): `ocreval/engines/deepseek_ocr.py`
- [Qwen3-VL adapter](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/qwen3_vl.py): `ocreval/engines/qwen3_vl.py`
- [dots.ocr adapter](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/dots_ocr.py): `ocreval/engines/dots_ocr.py`
- [Granite adapter](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/engines/granite_docling.py): `ocreval/engines/granite_docling.py`

### Evaluation

- [Evaluation orchestrator](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/evaluator.py): `ocreval/evaluator.py`
- [Text metrics](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/metrics/text_metrics.py): `ocreval/metrics/text_metrics.py`
- [Judge selection](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/metrics/geval.py): `ocreval/metrics/geval.py`
- [G-Eval judge](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/metrics/geval.py): `ocreval/metrics/geval.py`
- [Mock judge](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/metrics/geval.py): `ocreval/metrics/geval.py`
- [Score and composite](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/config.py): `ocreval/config.py`

### Results

- [Leaderboard formatter](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/report.py): `ocreval/report.py`
- [Ranked results](https://github.com/crzyc0d3r/ocr-eval-playground/blob/main/ocreval/evaluator.py): `ocreval/evaluator.py`

### Other components

- **User**

## Connections

- User → Streamlit UI: uses (evidence: `app.py`)
- User → Headless CLI: runs (evidence: `run_eval.py`)
- Streamlit UI → Sample loader: loads samples (evidence: `app.py`)
- Sample loader → Document model: creates (evidence: `ocreval/samples.py`)
- Streamlit UI → Document model: creates uploads (evidence: `app.py`)
- Headless CLI → Sample loader: loads document (evidence: `run_eval.py`)
- Headless CLI → Document model: creates input (evidence: `run_eval.py`)
- Streamlit UI → Engine registry: selects engines (evidence: `app.py`)
- Headless CLI → Engine registry: resolves engines (evidence: `run_eval.py`)
- Engine registry → Mock OCR tiers: falls back to (evidence: `ocreval/engines/__init__.py`)
- Engine registry → Chandra adapter: registers (evidence: `ocreval/engines/__init__.py`)
- Engine registry → DeepSeek adapter: registers (evidence: `ocreval/engines/__init__.py`)
- Engine registry → Qwen3-VL adapter: registers (evidence: `ocreval/engines/__init__.py`)
- Engine registry → dots.ocr adapter: registers (evidence: `ocreval/engines/__init__.py`)
- Engine registry → Granite adapter: registers (evidence: `ocreval/engines/__init__.py`)
- Streamlit UI → Evaluation orchestrator: evaluates (evidence: `app.py`)
- Headless CLI → Evaluation orchestrator: evaluates (evidence: `run_eval.py`)
- Evaluation orchestrator → Engine registry: resolves defaults (evidence: `ocreval/evaluator.py`)
- Evaluation orchestrator → Engine runtime: runs engines (evidence: `ocreval/evaluator.py`)
- Engine runtime → Document model: accepts input (evidence: `ocreval/engines/base.py`)
- Mock OCR tiers → Document model: reads text (evidence: `ocreval/engines/mock.py`)
- Evaluation orchestrator → Text metrics: computes metrics (evidence: `ocreval/evaluator.py`)
- Evaluation orchestrator → Judge selection: selects judge (evidence: `ocreval/evaluator.py`)
- Judge selection → G-Eval judge: chooses when configured (evidence: `ocreval/metrics/geval.py`)
- Judge selection → Mock judge: falls back to (evidence: `ocreval/metrics/geval.py`)
- Mock judge → Text metrics: uses metrics (evidence: `ocreval/metrics/geval.py`)
- Evaluation orchestrator → Score and composite: computes composite (evidence: `ocreval/evaluator.py`)
- Evaluation orchestrator → Ranked results: ranks scores (evidence: `ocreval/evaluator.py`)
- Streamlit UI → Leaderboard formatter: formats rows (evidence: `app.py`)
- Headless CLI → Leaderboard formatter: formats output (evidence: `run_eval.py`)
- Leaderboard formatter → Ranked results: renders (evidence: `ocreval/report.py`)
- Streamlit UI → Ranked results: displays (evidence: `app.py`)
- Headless CLI → Ranked results: prints (evidence: `run_eval.py`)
