# ddbxl/tsp architecture

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

- Interactive diagram: https://gitdiagram.com/ddbxl/tsp
- Repository: https://github.com/ddbxl/tsp

## Overview

TSP turns local documents into cleaned, token-efficient Markdown, with page images and optional tables or OCR, then offers the results for copying or download. Users enter through the desktop CLI/GUI or browser. The browser runs the shared Python engine in a worker and provides batch controls and delivery options. The core and the format-specific reader and renderer are shown separately; some browser internals are represented at subsystem level because the excerpts are partial. Edges reflect cited source references or README descriptions.

Main entry points: [`src/tsp/core.py`](https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py) (Document engine), [`src/tsp/cli.py`](https://github.com/ddbxl/tsp/blob/main/src/tsp/cli.py) (CLI), [`web/bridge.py`](https://github.com/ddbxl/tsp/blob/main/web/bridge.py) (Browser downloads), [`src/tsp/gui.py`](https://github.com/ddbxl/tsp/blob/main/src/tsp/gui.py) (Desktop GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_desktop_gui["Desktop GUI<br/>[gui.py]"]
end

subgraph group_browser["Browser application"]
  node_browser_ui["Browser UI<br/>[app.js]"]
  node_browser_worker["Web worker<br/>[worker.js]"]
  node_browser_bridge["Pyodide bridge<br/>[bridge.py]"]
end

subgraph group_processing["Document processing"]
  node_engine["Document engine<br/>[core.py]"]
  node_office_reader["Office reader<br/>[office.py]"]
  node_pdf_analysis["PDF analysis<br/>[core.py]"]
  node_auto_advice["Automatic settings<br/>[core.py]"]
  node_table_extraction["Table extraction<br/>[core.py]"]
  node_figure_handling["Figure handling<br/>[core.py]"]
  node_ocr["OCR processing<br/>[core.py]"]
end

subgraph group_results["Result generation"]
  node_markdown["Markdown output<br/>[core.py]"]
  node_page_images["Page images<br/>[core.py]"]
  node_html_renderer["HTML rendering<br/>[render.py]"]
  node_browser_delivery["Browser downloads<br/>[bridge.py]"]
end

node_user(("Document user"))
node_local_files[("Local files")]
node_tesseract["Tesseract OCR"]

node_user -->|"runs command"| node_cli
node_user -->|"opens desktop app"| node_desktop_gui
node_user -->|"adds documents"| node_browser_ui
node_cli -->|"processes files"| node_engine
node_desktop_gui -->|"processes files"| node_engine
node_browser_ui -->|"sends requests"| node_browser_worker
node_browser_worker -->|"loads bridge"| node_browser_bridge
node_browser_worker -->|"calls processing API"| node_engine
node_browser_bridge -->|"processes documents"| node_engine
node_engine -->|"delegates office files"| node_office_reader
node_engine -->|"extracts and cleans"| node_pdf_analysis
node_user -->|"requests automatic mode"| node_auto_advice
node_cli -->|"requests inspection"| node_auto_advice
node_auto_advice -->|"sets processing options"| node_engine
node_engine -->|"extracts optional tables"| node_table_extraction
node_engine -->|"detects and saves figures"| node_figure_handling
node_engine -->|"recognizes scanned pages"| node_ocr
node_ocr -.->|"uses OCR engine"| node_tesseract
node_engine -->|"writes Markdown"| node_markdown
node_engine -->|"saves page images"| node_page_images
node_engine -->|"renders HTML output"| node_html_renderer
node_browser_bridge -->|"renders downloadable HTML"| node_html_renderer
node_browser_ui -->|"requests result actions"| node_browser_delivery
node_browser_delivery -->|"packages text"| node_markdown
node_browser_delivery -->|"builds HTML files"| node_html_renderer
node_browser_delivery -->|"returns download bundle"| node_local_files
node_cli -->|"writes results"| node_local_files
node_desktop_gui -->|"saves results"| node_local_files

click node_cli "https://github.com/ddbxl/tsp/blob/main/src/tsp/cli.py"
click node_desktop_gui "https://github.com/ddbxl/tsp/blob/main/src/tsp/gui.py"
click node_browser_ui "https://github.com/ddbxl/tsp/blob/main/web/app.js"
click node_browser_worker "https://github.com/ddbxl/tsp/blob/main/web/worker.js"
click node_browser_bridge "https://github.com/ddbxl/tsp/blob/main/web/bridge.py"
click node_engine "https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py"
click node_office_reader "https://github.com/ddbxl/tsp/blob/main/src/tsp/office.py"
click node_pdf_analysis "https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py"
click node_auto_advice "https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py"
click node_table_extraction "https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py"
click node_figure_handling "https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py"
click node_ocr "https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py"
click node_markdown "https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py"
click node_page_images "https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py"
click node_html_renderer "https://github.com/ddbxl/tsp/blob/main/src/tsp/render.py"
click node_browser_delivery "https://github.com/ddbxl/tsp/blob/main/web/bridge.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_desktop_gui,node_user toneBlue
class node_browser_ui,node_browser_worker,node_browser_bridge,node_local_files toneAmber
class node_engine,node_office_reader,node_pdf_analysis,node_auto_advice,node_table_extraction,node_figure_handling,node_ocr toneMint
class node_markdown,node_page_images,node_html_renderer,node_browser_delivery toneRose
class node_tesseract toneIndigo
```

## Components

### Desktop interfaces

- [CLI](https://github.com/ddbxl/tsp/blob/main/src/tsp/cli.py): `src/tsp/cli.py`
- [Desktop GUI](https://github.com/ddbxl/tsp/blob/main/src/tsp/gui.py): `src/tsp/gui.py`

### Browser application

- [Browser UI](https://github.com/ddbxl/tsp/blob/main/web/app.js): `web/app.js`
- [Web worker](https://github.com/ddbxl/tsp/blob/main/web/worker.js): `web/worker.js`
- [Pyodide bridge](https://github.com/ddbxl/tsp/blob/main/web/bridge.py): `web/bridge.py`

### Document processing

- [Document engine](https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py): `src/tsp/core.py`
- [Office reader](https://github.com/ddbxl/tsp/blob/main/src/tsp/office.py): `src/tsp/office.py`
- [PDF analysis](https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py): `src/tsp/core.py`
- [Automatic settings](https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py): `src/tsp/core.py`
- [Table extraction](https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py): `src/tsp/core.py`
- [Figure handling](https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py): `src/tsp/core.py`
- [OCR processing](https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py): `src/tsp/core.py`

### Result generation

- [Markdown output](https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py): `src/tsp/core.py`
- [Page images](https://github.com/ddbxl/tsp/blob/main/src/tsp/core.py): `src/tsp/core.py`
- [HTML rendering](https://github.com/ddbxl/tsp/blob/main/src/tsp/render.py): `src/tsp/render.py`
- [Browser downloads](https://github.com/ddbxl/tsp/blob/main/web/bridge.py): `web/bridge.py`

### Other components

- **Document user**
- **Local files**
- **Tesseract OCR**

## Connections

- Document user → CLI: runs command (evidence: `README.md`)
- Document user → Desktop GUI: opens desktop app (evidence: `README.md`)
- Document user → Browser UI: adds documents (evidence: `README.md`)
- CLI → Document engine: processes files (evidence: `src/tsp/cli.py`)
- Desktop GUI → Document engine: processes files (evidence: `src/tsp/gui.py`)
- Browser UI → Web worker: sends requests (evidence: `web/app.js`)
- Web worker → Pyodide bridge: loads bridge (evidence: `web/worker.js`)
- Web worker → Document engine: calls processing API (evidence: `web/worker.js`)
- Pyodide bridge → Document engine: processes documents (evidence: `web/bridge.py`)
- Document engine → Office reader: delegates office files (evidence: `src/tsp/core.py`)
- Document engine → PDF analysis: extracts and cleans (evidence: `README.md`)
- Document user → Automatic settings: requests automatic mode (evidence: `README.md`)
- CLI → Automatic settings: requests inspection (evidence: `src/tsp/cli.py`)
- Automatic settings → Document engine: sets processing options (evidence: `README.md`)
- Document engine → Table extraction: extracts optional tables (evidence: `README.md`)
- Document engine → Figure handling: detects and saves figures (evidence: `README.md`)
- Document engine → OCR processing: recognizes scanned pages (evidence: `README.md`)
- OCR processing → Tesseract OCR: uses OCR engine (evidence: `README.md`)
- Document engine → Markdown output: writes Markdown (evidence: `README.md`)
- Document engine → Page images: saves page images (evidence: `README.md`)
- Document engine → HTML rendering: renders HTML output (evidence: `src/tsp/core.py`)
- Pyodide bridge → HTML rendering: renders downloadable HTML (evidence: `web/bridge.py`)
- Browser UI → Browser downloads: requests result actions (evidence: `web/app.js`)
- Browser downloads → Markdown output: packages text (evidence: `web/bridge.py`)
- Browser downloads → HTML rendering: builds HTML files (evidence: `web/bridge.py`)
- Browser downloads → Local files: returns download bundle
- CLI → Local files: writes results (evidence: `README.md`)
- Desktop GUI → Local files: saves results (evidence: `README.md`)
