# nanonets/docstrange architecture

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

- Interactive diagram: https://gitdiagram.com/nanonets/docstrange
- Repository: https://github.com/nanonets/docstrange

## Overview

##### Project Type and Purpose
- **Type**: A Python-based, full-stack library + CLI + optional self-hosted Web UI for document conversion and extraction.
- **Purpose**: Ingest PDFs, images, Office docs, and URLs → run OCR + layout detection → convert to Markdown, JSON, CSV, HTML → deliver via CLI, Python API, Web UI, or cloud API.

##### File Structure
- **Core Library**: `docstrange/`
- `cli.py` → CLI entry point
- `web_app.py`, `static/`, `templates/` → Flask-based Web UI
- `config.py`, `exceptions.py`, `result.py`, `utils/` → shared utilities
- **Pipeline**: `docstrange/pipeline/`
- `layout_detector`, `ocr_service`, `model_downloader`, `nanonets_processor`, `neural_document_processor`
- **Processors**: `docstrange/processors/`
- Format-specific processors: PDF, image, Excel, DOCX, PPTX, HTML, TXT, URL, Cloud, GPU
- **Services**: `docstrange/services/`
- `auth_service.py`, `ollama_service.py` → cloud authentication, local LLM service
- **MCP Server Module**: `mcp_server_module/`
- `server.py`, `__main__.py` → Claude Desktop integration microservice
- **Scripts & Examples**: `scripts/`, `examples/`, plus tests in `tests/`

##### Key Insights from README
- Dual processing modes: **Cloud API** vs. **Local CPU/GPU**
- Multi-stage pipeline: **Ingestion → Layout Detection → OCR → Formatting/Cleaning → (Optional) Structured Extraction**
- Interfaces: **Python API**, **CLI**, **Local Web UI**, **MCP Server** for Claude Desktop

a. **User Interfaces**
- CLI (`cli.py`)
- Python Library (`DocumentExtractor` API)
- Web UI (Flask app: `web_app.py` + static + templates)
- MCP Server (`mcp_server_module/server.py`)
b. **Core Pipeline**
- Ingestion Layer → dispatches file by type to appropriate `processors/` module
- OCR & Layout Detection (`ocr_service`, `layout_detector`)
- Model Management (`model_downloader`, GPU utils)
- Processors (PDF, image, DOCX, PPTX, XLSX, HTML, TXT, URL, cell)
- Structured Extraction (LLM via `ollama_service` or cloud model)
c. **Services & External Dependencies**
- Cloud API (NanoNets, Claude, optionally other OCR providers)
- Ollama local LLM
d. **Output Layer**
- `ConversionResult` methods: `.extract_markdown()`, `.extract_data()`, `.extract_html()`, `.extract_csv()`, `.extract_text()`

##### Relationships & Data Flows
1. **User** invokes **CLI** or **Web UI** or **Python API**.
2. The front-end component calls into `DocumentExtractor`.
3. `DocumentExtractor` loads **config** → chooses **cloud** or **local** mode.
4. File is passed to **Ingestion**, which picks the right **processor**.
5. Processor calls into **OCR Service** and **Layout Detector**.
6. Cleaned text flows to **Formatter** (Markdown/HTML) or **Structured Extractor** (LLM).
7. Output is returned to user interface or written to file.
8. Optionally, for Claude Desktop, MCP Server runs independently to handle token-aware chunking.

##### Architectural Patterns & Principles
- **Modular Pipeline**: clear separation of ingestion, processing, and formatting
- **Strategy Pattern**: different `processors/` selected at runtime based on input type
- **Adapter/Facade**: `DocumentExtractor` as a single façade to hide pipeline complexity
- **Client-Server**: Web UI and MCP server run as server processes
- **Dependency Injection**: configurable OCR, LLM, GPU vs. CPU modes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces
    subgraph "Interfaces"
        CLI["CLI Interface"]:::interface
        PythonAPI["DocumentExtractor API"]:::interface
        WebUIClient["Web UI Client (Browser)"]:::interface
        ClaudeClient["Claude Desktop"]:::interface
    end

    %% Servers
    subgraph "Servers"
        WebServer["Flask Web App"]:::interface
        MCPServer["MCP Server"]:::interface
    end

    %% Core Pipeline
    subgraph "Core Pipeline"
        Config["Configuration Module"]:::core
        Exceptions["Exception Definitions"]:::core
        Layout["Layout Detector"]:::core
        OCR["OCR Service"]:::core
        ModelDL["Model Downloader"]:::core
        Nano["NanoNets Cloud OCR Adapter"]:::core
        NeuralProc["Neural Document Processor"]:::core
        subgraph "Processors"
            BaseProc["Base Processor"]:::core
            PDF["PDF Processor"]:::core
            Image["Image Processor"]:::core
            DOCX["DOCX Processor"]:::core
            PPTX["PPTX Processor"]:::core
            XLSX["Excel Processor"]:::core
            HTML["HTML Processor"]:::core
            TXT["Text Processor"]:::core
            URLP["URL Processor"]:::core
            CloudProc["Cloud-Fallback Processor"]:::core
            GPUProc["GPU-Optimized Processor"]:::core
        end
        GPUUtils["GPU Utility Functions"]:::core
    end

    %% External Services
    subgraph "External Services"
        Auth["Auth Service"]:::service
        Ollama["Ollama Local LLM"]:::service
        CloudOCR["NanoNets Cloud API"]:::service
    end

    %% Outputs
    subgraph "Outputs"
        ResultModel["ConversionResult"]:::output
        Formats["Markdown/HTML/CSV/JSON/Text"]:::output
    end

    %% Connections - Interfaces to Servers/API
    CLI -->|invokes| PythonAPI
    WebUIClient -->|HTTP Request| WebServer
    ClaudeClient -->|gRPC/HTTP| MCPServer
    WebServer -->|calls| PythonAPI
    MCPServer -->|calls| PythonAPI

    %% API to Core
    PythonAPI -->|loads| Config
    PythonAPI -->|uses| Exceptions
    PythonAPI -->|starts| BaseProc
    Config -->|fetches models| ModelDL

    %% Processing Flow
    BaseProc -->|dispatch| PDF
    BaseProc -->|dispatch| Image
    BaseProc -->|dispatch| DOCX
    BaseProc -->|dispatch| PPTX
    BaseProc -->|dispatch| XLSX
    BaseProc -->|dispatch| HTML
    BaseProc -->|dispatch| TXT
    BaseProc -->|dispatch| URLP
    BaseProc -->|dispatch| CloudProc
    BaseProc -->|dispatch| GPUProc

    PDF -->|extract| Layout
    Image -->|extract| Layout
    DOCX -->|extract| Layout
    PPTX -->|extract| Layout
    XLSX -->|extract| Layout
    HTML -->|extract| Layout
    TXT -->|extract| Layout
    URLP -->|fetch & extract| Layout

    Layout -->|layout data| OCR
    OCR -->|text data| Nano
    Nano -->|OCR result| OCR
    OCR -->|passes text| NeuralProc
    NeuralProc -->|structured data| ResultModel

    %% Services connections
    Auth -->|provides tokens| CloudOCR
    OCR -->|calls| CloudOCR
    NeuralProc -->|calls| Ollama

    %% Final Output
    NeuralProc -->|to result| ResultModel
    ResultModel -->|formats| Formats

    %% Click Events
    click CLI "https://github.com/nanonets/docstrange/blob/main/docstrange/cli.py"
    click PythonAPI "https://github.com/nanonets/docstrange/blob/main/docstrange/extractor.py"
    click Config "https://github.com/nanonets/docstrange/blob/main/docstrange/config.py"
    click Exceptions "https://github.com/nanonets/docstrange/blob/main/docstrange/exceptions.py"
    click Layout "https://github.com/nanonets/docstrange/blob/main/docstrange/pipeline/layout_detector.py"
    click OCR "https://github.com/nanonets/docstrange/blob/main/docstrange/pipeline/ocr_service.py"
    click ModelDL "https://github.com/nanonets/docstrange/blob/main/docstrange/pipeline/model_downloader.py"
    click Nano "https://github.com/nanonets/docstrange/blob/main/docstrange/pipeline/nanonets_processor.py"
    click NeuralProc "https://github.com/nanonets/docstrange/blob/main/docstrange/pipeline/neural_document_processor.py"
    click BaseProc "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/base.py"
    click PDF "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/pdf_processor.py"
    click Image "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/image_processor.py"
    click DOCX "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/docx_processor.py"
    click PPTX "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/pptx_processor.py"
    click XLSX "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/excel_processor.py"
    click HTML "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/html_processor.py"
    click TXT "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/txt_processor.py"
    click URLP "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/url_processor.py"
    click CloudProc "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/cloud_processor.py"
    click GPUProc "https://github.com/nanonets/docstrange/blob/main/docstrange/processors/gpu_processor.py"
    click Auth "https://github.com/nanonets/docstrange/blob/main/docstrange/services/auth_service.py"
    click Ollama "https://github.com/nanonets/docstrange/blob/main/docstrange/services/ollama_service.py"
    click WebServer "https://github.com/nanonets/docstrange/blob/main/docstrange/web_app.py"
    click GPUUtils "https://github.com/nanonets/docstrange/blob/main/docstrange/utils/gpu_utils.py"
    click ResultModel "https://github.com/nanonets/docstrange/blob/main/docstrange/result.py"
    click MCPServer "https://github.com/nanonets/docstrange/blob/main/mcp_server_module/server.py"

    %% Styles
    classDef interface fill:#B3D4FF,stroke:#0366d6,color:#0366d6
    classDef core fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10
    classDef service fill:#FFE8A1,stroke:#CC7A00,color:#CC7A00
    classDef output fill:#E0E0E0,stroke:#858585,color:#333
```
