# opendatalab/mineru architecture

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

- Interactive diagram: https://gitdiagram.com/opendatalab/mineru
- Repository: https://github.com/opendatalab/mineru

## Overview

MinerU parses documents across PDF, image, office, web, and ebook formats, using OCR/layout and specialized table, formula, and vision-language models, then exposes structured results and rendered formats. The main workflow is a user submitting a file through the CLI, API, or Gradio; a parser service manages the request and stored results. The Doclib server adds persistent ingestion, scanning, search, caching, and background work. Edges are limited to relationships shown in excerpts or the source index; links into unsampled parsing stages are marked unverified.

Main entry points: [`mineru/doclib/services/parse_svc.py`](https://github.com/opendatalab/mineru/blob/master/mineru/doclib/services/parse_svc.py) (Parse service), [`mineru/parser/api_client.py`](https://github.com/opendatalab/mineru/blob/master/mineru/parser/api_client.py) (API parser client), [`mineru/doclib/server.py`](https://github.com/opendatalab/mineru/blob/master/mineru/doclib/server.py) (Doclib HTTP API), [`mineru/parser/api_server.py`](https://github.com/opendatalab/mineru/blob/master/mineru/parser/api_server.py) (Parse API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[main.py]"]
  node_gradio["Gradio app<br/>[app.py]"]
  node_api["Doclib HTTP API<br/>[server.py]"]
end

subgraph group_library["Document library"]
  node_parse_service["Parse service<br/>[parse_svc.py]"]
  node_library_db[("Document database<br/>[db.py]")]
  node_ingest["File ingestion<br/>[ingest.py]"]
  node_scan["Scan and watch<br/>[scan_svc.py]"]
  node_search[("Full-text search<br/>[fts.py]")]
  node_config["Configuration<br/>[config.py]"]
  node_health["Parse server health"]
end

subgraph group_parsing["Parsing pipeline"]
  node_parser_client["API parser client<br/>[api_client.py]"]
  node_parser_base["Parser interface<br/>[base.py]"]
  node_api_server["Parse API server<br/>[api_server.py]"]
  node_filetypes["Format detection<br/>[filetypes.py]"]
  node_pdf_pipeline["PDF analysis<br/>[pipeline.py]"]
  node_other_formats["Other format analysis"]
end

subgraph group_models["Models and inference"]
  node_registry["Model registry<br/>[registry.py]"]
  node_layout["Layout and OCR"]
  node_table_models["Table recognition"]
  node_formula_models["Formula recognition"]
  node_vlm["Vision-language runtime"]
end

subgraph group_results["Results and rendering"]
  node_postprocess["Document postprocessing<br/>[document.py]"]
  node_render["Result rendering<br/>[api.py]"]
  node_html_render["HTML renderer<br/>[html.py]"]
end

node_user(("User"))
node_external_parse{{"Remote parse service"}}

node_user -->|"submits request"| node_cli
node_user -.->|"submits file"| node_gradio
node_user -.->|"sends request"| node_api
node_cli -->|"manages server"| node_api
node_gradio -->|"parses files"| node_parser_client
node_api -->|"delegates parsing"| node_parse_service
node_parse_service -->|"reads and writes"| node_library_db
node_parse_service -->|"submits parse"| node_parser_client
node_ingest -->|"ensures ingestion"| node_parse_service
node_parse_service -->|"indexes content"| node_search
node_api -.->|"serves search"| node_search
node_api -.->|"serves scans"| node_scan
node_config -.->|"configures"| node_parse_service
node_health -->|"checks remote API"| node_parser_client
node_parser_client -->|"implements"| node_parser_base
node_parser_client -->|"sends parse requests"| node_external_parse
node_api_server -->|"detects formats"| node_filetypes
node_api_server -.->|"runs PDF analysis"| node_pdf_pipeline
node_api_server -.->|"handles formats"| node_other_formats
node_pdf_pipeline -->|"uses inference"| node_vlm
node_pdf_pipeline -->|"extracts geometry"| node_layout
node_registry -->|"registers models"| node_table_models
node_registry -->|"selects runtime"| node_vlm
node_parser_client -->|"renders HTML"| node_html_render
node_postprocess -.->|"prepares results"| node_render
node_render -->|"renders HTML"| node_html_render

click node_cli "https://github.com/opendatalab/mineru/blob/master/mineru/cli/main.py"
click node_gradio "https://github.com/opendatalab/mineru/blob/master/mineru/kit/gradio/app.py"
click node_api "https://github.com/opendatalab/mineru/blob/master/mineru/doclib/server.py"
click node_parse_service "https://github.com/opendatalab/mineru/blob/master/mineru/doclib/services/parse_svc.py"
click node_library_db "https://github.com/opendatalab/mineru/blob/master/mineru/doclib/core/db.py"
click node_ingest "https://github.com/opendatalab/mineru/blob/master/mineru/doclib/background/ingest.py"
click node_scan "https://github.com/opendatalab/mineru/blob/master/mineru/doclib/services/scan_svc.py"
click node_search "https://github.com/opendatalab/mineru/blob/master/mineru/doclib/core/fts.py"
click node_config "https://github.com/opendatalab/mineru/blob/master/mineru/config.py"
click node_health "https://github.com/opendatalab/mineru/blob/master/mineru/doclib/background/parse_server_health.py"
click node_parser_client "https://github.com/opendatalab/mineru/blob/master/mineru/parser/api_client.py"
click node_parser_base "https://github.com/opendatalab/mineru/blob/master/mineru/parser/base.py"
click node_api_server "https://github.com/opendatalab/mineru/blob/master/mineru/parser/api_server.py"
click node_filetypes "https://github.com/opendatalab/mineru/blob/master/mineru/filetypes.py"
click node_pdf_pipeline "https://github.com/opendatalab/mineru/blob/master/mineru/backend/analysis/pdf/pipeline.py"
click node_other_formats "https://github.com/opendatalab/mineru/tree/master/mineru/backend/analysis"
click node_registry "https://github.com/opendatalab/mineru/blob/master/mineru/model/registry.py"
click node_layout "https://github.com/opendatalab/mineru/tree/master/mineru/model/layout"
click node_table_models "https://github.com/opendatalab/mineru/tree/master/mineru/model/table"
click node_formula_models "https://github.com/opendatalab/mineru/tree/master/mineru/model/mfr"
click node_vlm "https://github.com/opendatalab/mineru/tree/master/mineru/model/vlm"
click node_postprocess "https://github.com/opendatalab/mineru/blob/master/mineru/backend/postprocess/document.py"
click node_render "https://github.com/opendatalab/mineru/blob/master/mineru/render/api.py"
click node_html_render "https://github.com/opendatalab/mineru/blob/master/mineru/render/html.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_cli,node_gradio,node_api,node_user toneBlue
class node_parse_service,node_library_db,node_ingest,node_scan,node_search,node_config,node_health toneAmber
class node_parser_client,node_parser_base,node_api_server,node_filetypes,node_pdf_pipeline,node_other_formats toneMint
class node_registry,node_layout,node_table_models,node_formula_models,node_vlm toneRose
class node_postprocess,node_render,node_html_render,node_external_parse toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/opendatalab/mineru/blob/master/mineru/cli/main.py): `mineru/cli/main.py`
- [Gradio app](https://github.com/opendatalab/mineru/blob/master/mineru/kit/gradio/app.py): `mineru/kit/gradio/app.py`
- [Doclib HTTP API](https://github.com/opendatalab/mineru/blob/master/mineru/doclib/server.py): `mineru/doclib/server.py`

### Document library

- [Parse service](https://github.com/opendatalab/mineru/blob/master/mineru/doclib/services/parse_svc.py): `mineru/doclib/services/parse_svc.py`
- [Document database](https://github.com/opendatalab/mineru/blob/master/mineru/doclib/core/db.py): `mineru/doclib/core/db.py`
- [File ingestion](https://github.com/opendatalab/mineru/blob/master/mineru/doclib/background/ingest.py): `mineru/doclib/background/ingest.py`
- [Scan and watch](https://github.com/opendatalab/mineru/blob/master/mineru/doclib/services/scan_svc.py): `mineru/doclib/services/scan_svc.py`
- [Full-text search](https://github.com/opendatalab/mineru/blob/master/mineru/doclib/core/fts.py): `mineru/doclib/core/fts.py`
- [Configuration](https://github.com/opendatalab/mineru/blob/master/mineru/config.py): `mineru/config.py`
- [Parse server health](https://github.com/opendatalab/mineru/blob/master/mineru/doclib/background/parse_server_health.py): `mineru/doclib/background/parse_server_health.py`

### Parsing pipeline

- [API parser client](https://github.com/opendatalab/mineru/blob/master/mineru/parser/api_client.py): `mineru/parser/api_client.py`
- [Parser interface](https://github.com/opendatalab/mineru/blob/master/mineru/parser/base.py): `mineru/parser/base.py`
- [Parse API server](https://github.com/opendatalab/mineru/blob/master/mineru/parser/api_server.py): `mineru/parser/api_server.py`
- [Format detection](https://github.com/opendatalab/mineru/blob/master/mineru/filetypes.py): `mineru/filetypes.py`
- [PDF analysis](https://github.com/opendatalab/mineru/blob/master/mineru/backend/analysis/pdf/pipeline.py): `mineru/backend/analysis/pdf/pipeline.py`
- [Other format analysis](https://github.com/opendatalab/mineru/tree/master/mineru/backend/analysis): `mineru/backend/analysis`

### Models and inference

- [Model registry](https://github.com/opendatalab/mineru/blob/master/mineru/model/registry.py): `mineru/model/registry.py`
- [Layout and OCR](https://github.com/opendatalab/mineru/tree/master/mineru/model/layout): `mineru/model/layout`
- [Table recognition](https://github.com/opendatalab/mineru/tree/master/mineru/model/table): `mineru/model/table`
- [Formula recognition](https://github.com/opendatalab/mineru/tree/master/mineru/model/mfr): `mineru/model/mfr`
- [Vision-language runtime](https://github.com/opendatalab/mineru/tree/master/mineru/model/vlm): `mineru/model/vlm`

### Results and rendering

- [Document postprocessing](https://github.com/opendatalab/mineru/blob/master/mineru/backend/postprocess/document.py): `mineru/backend/postprocess/document.py`
- [Result rendering](https://github.com/opendatalab/mineru/blob/master/mineru/render/api.py): `mineru/render/api.py`
- [HTML renderer](https://github.com/opendatalab/mineru/blob/master/mineru/render/html.py): `mineru/render/html.py`

### Other components

- **User**
- **Remote parse service**

## Connections

- User → CLI commands: submits request (evidence: `mineru/cli/main.py`)
- User → Gradio app: submits file
- User → Doclib HTTP API: sends request
- CLI commands → Doclib HTTP API: manages server
- Gradio app → API parser client: parses files (evidence: `mineru/kit/gradio/app.py`)
- Doclib HTTP API → Parse service: delegates parsing (evidence: `mineru/doclib/server.py`)
- Parse service → Document database: reads and writes (evidence: `mineru/doclib/services/parse_svc.py`)
- Parse service → API parser client: submits parse (evidence: `mineru/doclib/services/parse_svc.py`)
- File ingestion → Parse service: ensures ingestion (evidence: `mineru/doclib/background/ingest.py`)
- Parse service → Full-text search: indexes content (evidence: `mineru/doclib/services/parse_svc.py`)
- Doclib HTTP API → Full-text search: serves search
- Doclib HTTP API → Scan and watch: serves scans
- Configuration → Parse service: configures (evidence: `mineru/doclib/services/parse_svc.py`)
- Parse server health → API parser client: checks remote API (evidence: `mineru/doclib/background/parse_server_health.py`)
- API parser client → Parser interface: implements (evidence: `mineru/parser/api_client.py`)
- API parser client → Remote parse service: sends parse requests (evidence: `mineru/parser/api_client.py`)
- Parse API server → Format detection: detects formats
- Parse API server → PDF analysis: runs PDF analysis
- Parse API server → Other format analysis: handles formats
- PDF analysis → Vision-language runtime: uses inference (evidence: `mineru/backend/analysis/pdf/pipeline.py`)
- PDF analysis → Layout and OCR: extracts geometry (evidence: `mineru/backend/analysis/pdf/pipeline.py`)
- Model registry → Table recognition: registers models (evidence: `mineru/model/registry.py`)
- Model registry → Vision-language runtime: selects runtime (evidence: `mineru/model/registry.py`)
- API parser client → HTML renderer: renders HTML (evidence: `mineru/parser/api_client.py`)
- Document postprocessing → Result rendering: prepares results
- Result rendering → HTML renderer: renders HTML (evidence: `mineru/render/html.py`)
