# heryinassociation/doclab architecture

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

- Interactive diagram: https://gitdiagram.com/heryinassociation/doclab
- Repository: https://github.com/heryinassociation/doclab

## Overview

doclab is a local literature-processing workbench: it ingests or adopts books, builds a calibrated hierarchical outline, and exports depth-based Markdown and indexes for knowledge extraction. The main workflow is orchestrated through the CLI and reused by the local HTTP interface and MCP wrapper. EPUB also has a standalone chapter-oriented converter. Several module responsibilities are documented in the CLI and README, but their implementation was not sampled; the graph omits uncertain internal wiring.

Main entry points: [`doclab.py`](https://github.com/heryinassociation/doclab/blob/main/doclab.py) (Command workflow), [`core/project.py`](https://github.com/heryinassociation/doclab/blob/main/core/project.py) (Book workspaces), [`core/ingest.py`](https://github.com/heryinassociation/doclab/blob/main/core/ingest.py) (Parsed blocks), [`core/server.py`](https://github.com/heryinassociation/doclab/blob/main/core/server.py) (Local workbench)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_cli["Command workflow<br/>[doclab.py]"]
  node_web["Local workbench<br/>[server.py]"]
  node_mcp["MCP tools<br/>[mcp_server.cjs]"]
end

subgraph group_intake["Book Intake"]
  node_mineru_api["MinerU client<br/>[mineru_api.py]"]
  node_ingest["Ingest and adopt<br/>[ingest.py]"]
  node_epub["EPUB parsing<br/>[epub.py]"]
  node_epub_standalone["Chapter converter<br/>[epub2md.py]"]
end

subgraph group_analysis["Structure Analysis"]
  node_pagecal["Page calibration<br/>[pagecal.py]"]
  node_outline["Outline builder<br/>[outline.py]"]
  node_manual["Manual corrections<br/>[manual.py]"]
  node_tocio["TOC exchange<br/>[tocio.py]"]
  node_audit["Outline audit<br/>[audit.py]"]
end

subgraph group_output["Export and Checks"]
  node_exporter["Markdown export<br/>[exporter.py]"]
  node_verify["Export verification<br/>[verify.py]"]
end

subgraph group_state["Project State"]
  node_project["Project registry<br/>[project.py]"]
  node_workspace[("Book workspaces<br/>[project.py]")]
  node_blocks["Parsed blocks<br/>[ingest.py]"]
end

node_reader(("Book operator"))
node_source["PDF or EPUB"]
node_mineru["MinerU API"]
node_markdown["Markdown and indexes"]

node_reader -->|"runs commands"| node_cli
node_reader -->|"uses interface"| node_web
node_reader -->|"calls tools"| node_mcp
node_mcp -->|"spawns CLI"| node_cli
node_web -->|"dispatches commands"| node_cli
node_cli -->|"ingests or adopts"| node_ingest
node_cli -->|"parses EPUB"| node_epub
node_cli -->|"calibrates pages"| node_pagecal
node_cli -->|"builds outline"| node_outline
node_cli -->|"audits outline"| node_audit
node_cli -->|"exports depth"| node_exporter
node_cli -->|"checks export"| node_verify
node_ingest -->|"requests OCR"| node_mineru_api
node_mineru_api -->|"uploads and polls"| node_mineru
node_mineru -->|"returns OCR results"| node_mineru_api
node_ingest -->|"records project"| node_workspace
node_ingest -->|"produces blocks"| node_blocks
node_epub -->|"records project"| node_workspace
node_epub_standalone -->|"reads EPUB"| node_source
node_epub_standalone -->|"writes chapters"| node_markdown
node_project -->|"resolves projects"| node_workspace
node_pagecal -->|"uses page blocks"| node_blocks
node_pagecal -->|"stores calibration"| node_workspace
node_outline -->|"builds from blocks"| node_blocks
node_outline -->|"stores tree"| node_workspace
node_manual -->|"stores edits"| node_workspace
node_tocio -->|"exchanges outline"| node_workspace
node_audit -->|"reads project data"| node_workspace
node_exporter -->|"uses content"| node_blocks
node_exporter -->|"reads outline and calibration"| node_workspace
node_exporter -->|"writes documents"| node_markdown
node_verify -->|"checks export state"| node_workspace
node_verify -->|"validates output"| node_markdown
node_web -->|"edits outline"| node_manual
node_web -->|"browses blocks"| node_blocks

click node_cli "https://github.com/heryinassociation/doclab/blob/main/doclab.py"
click node_web "https://github.com/heryinassociation/doclab/blob/main/core/server.py"
click node_mcp "https://github.com/heryinassociation/doclab/blob/main/mcp_server.cjs"
click node_mineru_api "https://github.com/heryinassociation/doclab/blob/main/core/mineru_api.py"
click node_ingest "https://github.com/heryinassociation/doclab/blob/main/core/ingest.py"
click node_epub "https://github.com/heryinassociation/doclab/blob/main/core/epub.py"
click node_epub_standalone "https://github.com/heryinassociation/doclab/blob/main/epub-to-markdown/epub2md.py"
click node_project "https://github.com/heryinassociation/doclab/blob/main/core/project.py"
click node_workspace "https://github.com/heryinassociation/doclab/blob/main/core/project.py"
click node_blocks "https://github.com/heryinassociation/doclab/blob/main/core/ingest.py"
click node_pagecal "https://github.com/heryinassociation/doclab/blob/main/core/pagecal.py"
click node_outline "https://github.com/heryinassociation/doclab/blob/main/core/outline.py"
click node_manual "https://github.com/heryinassociation/doclab/blob/main/core/manual.py"
click node_tocio "https://github.com/heryinassociation/doclab/blob/main/core/tocio.py"
click node_audit "https://github.com/heryinassociation/doclab/blob/main/core/audit.py"
click node_exporter "https://github.com/heryinassociation/doclab/blob/main/core/exporter.py"
click node_verify "https://github.com/heryinassociation/doclab/blob/main/core/verify.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_web,node_mcp toneBlue
class node_mineru_api,node_ingest,node_epub,node_epub_standalone toneAmber
class node_pagecal,node_outline,node_manual,node_tocio,node_audit,node_mineru toneMint
class node_exporter,node_verify toneRose
class node_project,node_workspace,node_blocks,node_reader,node_source,node_markdown toneIndigo
```

## Components

### Interfaces

- [Command workflow](https://github.com/heryinassociation/doclab/blob/main/doclab.py): `doclab.py`
- [Local workbench](https://github.com/heryinassociation/doclab/blob/main/core/server.py): `core/server.py`
- [MCP tools](https://github.com/heryinassociation/doclab/blob/main/mcp_server.cjs): `mcp_server.cjs`

### Book Intake

- [MinerU client](https://github.com/heryinassociation/doclab/blob/main/core/mineru_api.py): `core/mineru_api.py`
- [Ingest and adopt](https://github.com/heryinassociation/doclab/blob/main/core/ingest.py): `core/ingest.py`
- [EPUB parsing](https://github.com/heryinassociation/doclab/blob/main/core/epub.py): `core/epub.py`
- [Chapter converter](https://github.com/heryinassociation/doclab/blob/main/epub-to-markdown/epub2md.py): `epub-to-markdown/epub2md.py`

### Structure Analysis

- [Page calibration](https://github.com/heryinassociation/doclab/blob/main/core/pagecal.py): `core/pagecal.py`
- [Outline builder](https://github.com/heryinassociation/doclab/blob/main/core/outline.py): `core/outline.py`
- [Manual corrections](https://github.com/heryinassociation/doclab/blob/main/core/manual.py): `core/manual.py`
- [TOC exchange](https://github.com/heryinassociation/doclab/blob/main/core/tocio.py): `core/tocio.py`
- [Outline audit](https://github.com/heryinassociation/doclab/blob/main/core/audit.py): `core/audit.py`

### Export and Checks

- [Markdown export](https://github.com/heryinassociation/doclab/blob/main/core/exporter.py): `core/exporter.py`
- [Export verification](https://github.com/heryinassociation/doclab/blob/main/core/verify.py): `core/verify.py`

### Project State

- [Project registry](https://github.com/heryinassociation/doclab/blob/main/core/project.py): `core/project.py`
- [Book workspaces](https://github.com/heryinassociation/doclab/blob/main/core/project.py): `core/project.py`
- [Parsed blocks](https://github.com/heryinassociation/doclab/blob/main/core/ingest.py): `core/ingest.py`

### Other components

- **Book operator**
- **PDF or EPUB**
- **MinerU API**
- **Markdown and indexes**

## Connections

- Book operator → Command workflow: runs commands
- Book operator → Local workbench: uses interface
- Book operator → MCP tools: calls tools
- MCP tools → Command workflow: spawns CLI
- Local workbench → Command workflow: dispatches commands
- Command workflow → Ingest and adopt: ingests or adopts
- Command workflow → EPUB parsing: parses EPUB
- Command workflow → Page calibration: calibrates pages
- Command workflow → Outline builder: builds outline
- Command workflow → Outline audit: audits outline
- Command workflow → Markdown export: exports depth
- Command workflow → Export verification: checks export
- Ingest and adopt → MinerU client: requests OCR
- MinerU client → MinerU API: uploads and polls
- MinerU API → MinerU client: returns OCR results
- Ingest and adopt → Book workspaces: records project
- Ingest and adopt → Parsed blocks: produces blocks
- EPUB parsing → Book workspaces: records project
- Chapter converter → PDF or EPUB: reads EPUB
- Chapter converter → Markdown and indexes: writes chapters
- Project registry → Book workspaces: resolves projects
- Page calibration → Parsed blocks: uses page blocks
- Page calibration → Book workspaces: stores calibration
- Outline builder → Parsed blocks: builds from blocks
- Outline builder → Book workspaces: stores tree
- Manual corrections → Book workspaces: stores edits
- TOC exchange → Book workspaces: exchanges outline
- Outline audit → Book workspaces: reads project data
- Markdown export → Parsed blocks: uses content
- Markdown export → Book workspaces: reads outline and calibration
- Markdown export → Markdown and indexes: writes documents
- Export verification → Book workspaces: checks export state
- Export verification → Markdown and indexes: validates output
- Local workbench → Manual corrections: edits outline
- Local workbench → Parsed blocks: browses blocks