# datalab-to/chandra architecture

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

- Interactive diagram: https://gitdiagram.com/datalab-to/chandra
- Repository: https://github.com/datalab-to/chandra

## Overview

1. **What this repository is**
   - `chandra` is a Python OCR/document-intelligence package for turning images and PDFs into structured text outputs: Markdown, HTML, and JSON.
   - The core architectural idea is a document-to-structure pipeline, not just plain OCR: it preserves layout, tables, math, forms, images, and reading order.

2. **Primary execution modes**
   - There are two inference backends, and they define the main runtime boundary:
     - **HuggingFace local inference** for in-process model execution.
     - **vLLM remote/server inference** for faster or production-style deployment.
   - The README makes vLLM the default path, with HuggingFace as an alternative backend.

3. **Core library boundary**
   - The reusable logic lives under `chandra/`.
   - This is where the repository separates concerns into:
     - input handling,
     - prompt construction,
     - model backend adapters,
     - output formatting,
     - settings/configuration,
     - utility helpers.
   - That separation is important for a diagram: CLI, app, and server entrypoints are thin wrappers around this core package.

4. **Input subsystem**
   - `chandra/input.py` is the likely front door for files and document sources.
   - Based on the README, it supports single files and directories, PDF page ranges, batching, and optional extraction of embedded images.
   - This subsystem is responsible for normalizing document sources into per-page work units before inference.

5. **Prompting and task shaping**
   - `chandra/prompts.py` is the layer that converts a page or image into the instruction format expected by the model.
   - This is where document-intelligence specifics live: asking the model to produce structured HTML/Markdown/JSON and preserve layout relationships.
   - In architecture terms, this sits between normalized input pages and the model backend.

6. **Model abstraction layer**
   - `chandra/model/` is the main backend abstraction boundary.
   - `hf.py` and `vllm.py` implement the two inference paths, while `schema.py` and `util.py` support request/response shaping and backend-specific helpers.
   - This layer is what keeps the rest of the system backend-agnostic: the higher layers should not care whether inference is local or served over an API.

7. **Output subsystem**
   - `chandra/output.py` is where inference results become durable artifacts.
   - The README indicates each processed document emits a directory containing:
     - Markdown output,
     - HTML output,
     - metadata JSON,
     - and extracted images.
   - This is the persistence boundary of the pipeline: model outputs are transformed into user-facing files and metadata.

8. **Configuration and runtime settings**
   - `chandra/settings.py` and environment variables define runtime configuration such as model checkpoint, max output tokens, and vLLM endpoint details.
   - The README also mentions optional `local.env` support.
   - In a diagram, this is the control plane for deployment-specific behavior rather than document content flow.

9. **User-facing entrypoints**
   - `chandra/scripts/` contains the executable surfaces:
     - `cli.py` for command-line document processing,
     - `app.py` and `run_app.py` for the Streamlit app,
     - `screenshot_app.py` plus the HTML template for visual capture/debugging,
     - `vllm.py` for launching the vLLM server/container workflow.
   - These are orchestration layers over the core library, not the core OCR logic itself.

10. **Server/deployment path**
   - The `vllm` script indicates a deployment boundary where inference can be served as an API rather than embedded locally.
   - The README points to `VLLM_API_BASE`, `VLLM_MODEL_NAME`, and `VLLM_GPUS`, so the remote inference mode is explicitly configured and isolated from the CLI/app frontends.
   - This is the main scaling boundary for production or batch workloads.

11. **Data flow through the system**
   - Typical flow is:
     - user provides a PDF/image or a directory,
     - input is normalized into pages,
     - prompts are built for each page,
     - a backend runs inference,
     - outputs are parsed/structured,
     - final files are written per source document.
   - Optional branches include image extraction and inclusion/exclusion of headers and footers.

12. **Testing and validation**
   - `tests/integration/test_image_inference.py` shows at least one integration test path focused on end-to-end image inference.
   - This suggests the repository values backend-level correctness, not only unit tests.
   - `tests/conftest.py` likely centralizes fixtures for document/image inputs and backend setup.

13. **CI/CD and release flow**
   - `.github/workflows/integration.yml` and `publish.yml` indicate automated validation and package publishing.
   - The presence of `pyproject.toml`, `uv.lock`, and `.python-version` suggests a modern Python packaging/runtime workflow centered on reproducible installs.

14. **External dependencies that matter architecturally**
   - The repo’s main external integration points are HuggingFace Transformers and vLLM.
   - Those are not incidental libraries; they define the two primary inference architectures and directly affect latency, hardware requirements, and deployment shape.

15. **How to draw the architecture**
   - A good diagram would show:
     - CLI/Streamlit/vLLM launcher on the left,
     - the shared `chandra` core in the middle,
     - input/prompt/model/output/config as internal stages,
     - and two interchangeable backend boxes for HF and vLLM.
   - Output artifacts should be shown as a sink on the right: Markdown, HTML, JSON metadata, and extracted images.

Main entry points: [`chandra/model/__init__.py`](https://github.com/datalab-to/chandra/blob/master/chandra/model/__init__.py) (Model API), [`chandra/input.py`](https://github.com/datalab-to/chandra/blob/master/chandra/input.py) (Input), [`chandra/model/vllm.py`](https://github.com/datalab-to/chandra/blob/master/chandra/model/vllm.py) (vLLM), [`tests/integration/test_image_inference.py`](https://github.com/datalab-to/chandra/blob/master/tests/integration/test_image_inference.py) (Integration test)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entrypoints"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_app["App<br/>entrypoint<br/>[app.py]"]
  node_run_app["Run app<br/>launcher<br/>[run_app.py]"]
  node_screenshot_app["Screenshot<br/>tooling<br/>[screenshot_app.py]"]
  node_vllm_script["VLLM script<br/>launcher<br/>[vllm.py]"]
end

subgraph group_core["Core pipeline"]
  node_input["Input<br/>document I/O<br/>[input.py]"]
  node_prompts["Prompts<br/>task shaping<br/>[prompts.py]"]
  node_output["Output<br/>artifact writer<br/>[output.py]"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
  node_util["Util<br/>helpers<br/>[util.py]"]
end

subgraph group_model["Model layer"]
  node_model_api["Model API<br/>adapter facade<br/>[__init__.py]"]
  node_hf["HuggingFace<br/>local backend<br/>[hf.py]"]
  node_vllm["vLLM<br/>remote backend<br/>[vllm.py]"]
  node_schema["Schema<br/>request/response<br/>[schema.py]"]
  node_model_util["Model util<br/>backend helpers<br/>[util.py]"]
end

subgraph group_quality["Quality & release"]
  node_tests["Integration test<br/>validation"]
  node_conftest["Fixtures<br/>[conftest.py]"]
  node_workflows["Workflows<br/>ci/release<br/>[integration.yml]"]
end

node_cli -->|"loads docs"| node_input
node_app -->|"loads docs"| node_input
node_run_app -->|"starts"| node_app
node_screenshot_app -->|"captures"| node_app
node_vllm_script -->|"starts server"| node_vllm
node_input -->|"pages"| node_prompts
node_prompts -->|"requests"| node_model_api
node_model_api -->|"local path"| node_hf
node_model_api -->|"remote path"| node_vllm
node_hf -->|"uses"| node_schema
node_vllm -->|"uses"| node_schema
node_hf -->|"helpers"| node_model_util
node_vllm -->|"helpers"| node_model_util
node_model_api -->|"structured text"| node_output
node_settings -->|"configures"| node_model_api
node_settings -->|"endpoint config"| node_vllm_script
node_util -->|"supports"| node_input
node_util -->|"supports"| node_output
node_tests -->|"validates"| node_input
node_tests -->|"validates"| node_model_api
node_conftest -->|"fixtures"| node_tests
node_workflows -->|"runs"| node_tests

click node_cli "https://github.com/datalab-to/chandra/blob/master/chandra/scripts/cli.py"
click node_app "https://github.com/datalab-to/chandra/blob/master/chandra/scripts/app.py"
click node_run_app "https://github.com/datalab-to/chandra/blob/master/chandra/scripts/run_app.py"
click node_screenshot_app "https://github.com/datalab-to/chandra/blob/master/chandra/scripts/screenshot_app.py"
click node_vllm_script "https://github.com/datalab-to/chandra/blob/master/chandra/scripts/vllm.py"
click node_input "https://github.com/datalab-to/chandra/blob/master/chandra/input.py"
click node_prompts "https://github.com/datalab-to/chandra/blob/master/chandra/prompts.py"
click node_output "https://github.com/datalab-to/chandra/blob/master/chandra/output.py"
click node_settings "https://github.com/datalab-to/chandra/blob/master/chandra/settings.py"
click node_util "https://github.com/datalab-to/chandra/blob/master/chandra/util.py"
click node_model_api "https://github.com/datalab-to/chandra/blob/master/chandra/model/__init__.py"
click node_hf "https://github.com/datalab-to/chandra/blob/master/chandra/model/hf.py"
click node_vllm "https://github.com/datalab-to/chandra/blob/master/chandra/model/vllm.py"
click node_schema "https://github.com/datalab-to/chandra/blob/master/chandra/model/schema.py"
click node_model_util "https://github.com/datalab-to/chandra/blob/master/chandra/model/util.py"
click node_tests "https://github.com/datalab-to/chandra/blob/master/tests/integration/test_image_inference.py"
click node_conftest "https://github.com/datalab-to/chandra/blob/master/tests/conftest.py"
click node_workflows "https://github.com/datalab-to/chandra/blob/master/.github/workflows/integration.yml"

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_app,node_run_app,node_screenshot_app,node_vllm_script toneBlue
class node_input,node_prompts,node_output,node_settings,node_util toneAmber
class node_model_api,node_hf,node_vllm,node_schema,node_model_util toneMint
class node_tests,node_conftest,node_workflows toneRose
```

## Components

### Entrypoints

User-facing command, app, and server launch surfaces.

- [CLI](https://github.com/datalab-to/chandra/blob/master/chandra/scripts/cli.py): entrypoint · Command-line document processing entrypoint. · `chandra/scripts/cli.py`
- [App](https://github.com/datalab-to/chandra/blob/master/chandra/scripts/app.py): entrypoint · Streamlit UI entrypoint. · `chandra/scripts/app.py`
- [Run app](https://github.com/datalab-to/chandra/blob/master/chandra/scripts/run_app.py): launcher · Helper that starts the Streamlit application. · `chandra/scripts/run_app.py`
- [Screenshot](https://github.com/datalab-to/chandra/blob/master/chandra/scripts/screenshot_app.py): tooling · Visual capture and debugging surface for the app. · `chandra/scripts/screenshot_app.py`
- [VLLM script](https://github.com/datalab-to/chandra/blob/master/chandra/scripts/vllm.py): launcher · Launches or wires up the vLLM server workflow. · `chandra/scripts/vllm.py`

### Core pipeline

Document normalization, prompting, output, and runtime settings.

- [Input](https://github.com/datalab-to/chandra/blob/master/chandra/input.py): document I/O · Normalizes files, directories, page ranges, and embedded images into page work units. · `chandra/input.py`
- [Prompts](https://github.com/datalab-to/chandra/blob/master/chandra/prompts.py): task shaping · Builds page-level instructions for structured document output. · `chandra/prompts.py`
- [Output](https://github.com/datalab-to/chandra/blob/master/chandra/output.py): artifact writer · Writes Markdown, HTML, metadata JSON, and extracted images. · `chandra/output.py`
- [Settings](https://github.com/datalab-to/chandra/blob/master/chandra/settings.py): config · Runtime configuration and environment-driven defaults. · `chandra/settings.py`
- [Util](https://github.com/datalab-to/chandra/blob/master/chandra/util.py): helpers · Shared utility helpers used across the package. · `chandra/util.py`

### Model layer

Backend abstraction and inference implementations.

- [Model API](https://github.com/datalab-to/chandra/blob/master/chandra/model/__init__.py): adapter facade · Backend-agnostic interface for model execution. · `chandra/model/__init__.py`
- [HuggingFace](https://github.com/datalab-to/chandra/blob/master/chandra/model/hf.py): local backend · In-process inference path using Transformers/HuggingFace models. · `chandra/model/hf.py`
- [vLLM](https://github.com/datalab-to/chandra/blob/master/chandra/model/vllm.py): remote backend · Server-based inference path for production or scaled execution. · `chandra/model/vllm.py`
- [Schema](https://github.com/datalab-to/chandra/blob/master/chandra/model/schema.py): request/response · Shared request and response shaping for backend calls. · `chandra/model/schema.py`
- [Model util](https://github.com/datalab-to/chandra/blob/master/chandra/model/util.py): backend helpers · Backend-specific helpers and normalization logic. · `chandra/model/util.py`

### Quality & release

Tests and automation that validate and ship the package.

- [Integration test](https://github.com/datalab-to/chandra/blob/master/tests/integration/test_image_inference.py): validation · End-to-end image inference coverage. · `tests/integration/test_image_inference.py`
- [Fixtures](https://github.com/datalab-to/chandra/blob/master/tests/conftest.py): test fixtures · Shared testing fixtures for inputs and backend setup. · `tests/conftest.py`
- [Workflows](https://github.com/datalab-to/chandra/blob/master/.github/workflows/integration.yml): ci/release · Automated integration validation and package publishing. · `.github/workflows/integration.yml`

## Connections

- CLI → Input: loads docs · CLI begins by normalizing document sources.
- App → Input: loads docs · Streamlit app feeds the same input pipeline.
- Run app → App: starts · Launcher hands control to the app UI.
- Screenshot → App: captures · Screenshot tooling wraps the app for visual debugging.
- VLLM script → vLLM: starts server · Deployment script exposes the vLLM backend.
- Input → Prompts: pages · Normalized pages are converted into model instructions.
- Prompts → Model API: requests · Prompted page content enters the backend abstraction.
- Model API → HuggingFace: local path · Facade can dispatch to local HuggingFace inference.
- Model API → vLLM: remote path · Facade can dispatch to the server-backed vLLM path.
- HuggingFace → Schema: uses · Local backend shares request/response schema.
- vLLM → Schema: uses · Remote backend shares request/response schema.
- HuggingFace → Model util: helpers · Local backend relies on backend-specific utilities.
- vLLM → Model util: helpers · Remote backend relies on backend-specific utilities.
- Model API → Output: structured text · Backend results are persisted as user-facing artifacts.
- Settings → Model API: configures · Runtime settings select backend and inference behavior.
- Settings → VLLM script: endpoint config · Server launcher is driven by vLLM deployment settings.
- Util → Input: supports · Shared utilities assist document handling.
- Util → Output: supports · Shared utilities assist artifact writing.
- Integration test → Input: validates · Integration test exercises document ingestion and page handling.
- Integration test → Model API: validates · Integration test reaches the inference boundary.
- Fixtures → Integration test: fixtures · Shared fixtures support integration coverage.
- Workflows → Integration test: runs · CI workflow executes the integration test path.
