# zai-org/glm-ocr architecture

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

- Interactive diagram: https://gitdiagram.com/zai-org/glm-ocr
- Repository: https://github.com/zai-org/glm-ocr

## Overview

##### Project Type and Purpose
- This is primarily an open-source OCR SDK and CLI tool (“glmocr” Python package) that also includes a full-stack demo application (a React frontend + Python backend).
- The SDK provides a modular OCR pipeline (dataloader, layout detection, OCR client, post-processing, result formatting), a CLI (`glmocr`), and a server mode (`python -m glmocr.server`).
- The “apps” folder contains a standalone backend REST API (FastAPI‐style) and a React/Vite frontend for file upload and OCR result display.

##### File-Structure Analysis
- Top level:
- `glmocr/` – core SDK modules (dataloader, pipeline, clients, server, utils, tests).
- `apps/backend/` – Python web app: REST endpoints under `app/api/`, core business logic under `app/core/`, DB layer (`app/db/`, `app/models/`, `app/repository/`), Pydantic schemas (`app/schemas/`), config/logging, Dockerfile.
- `apps/frontend/` – React/Vite web client: components (OCR UI, markdown preview), hooks, API client, routes, state store, Dockerfile, nginx config.
- `examples/` – CLI and SDK usage samples.
- CI/CD config (.github/workflows), Docker startup scripts (`start-docker.sh`, `start-local.sh`).

##### Key README Insights
- Modular pipeline: PageLoader → OCRClient → PP-DocLayout detector → parallel OCR → ResultFormatter.
- Two deployment modes: MaaS cloud API or self-hosted model server (vLLM/SGLang).
- CLI usage and Python API usage.
- Flask service example (`glmocr.server`).

##### Main Components
a. Clients
- CLI / Python SDK (CLI tool, script calls into `glmocr` library)
- React Web App (in `apps/frontend`)
b. Web Backend (`apps/backend`)
- API layer (`app/api/`): HTTP endpoints for task submission, system health
- Core pipeline orchestrator (`app/core/`): flows, steps, task manager, worker, retry/recovery, lock manager
- DB layer (`app/db/`, `app/models/`, `app/repository/`): persistence of tasks and results
c. OCR Pipeline (inside SDK or backend)
- PageLoader (from `glmocr/dataloader`)
- Layout Detector (PP-DocLayout via OCRClient)
- OCRClient (MaaS or self-hosted vLLM/SGLang)
- ResultFormatter (JSON/Markdown)
d. External Services
- Zhipu MaaS API (cloud) or vLLM / SGLang model server
- (Optionally) Docker / Nginx reverse proxy

##### Relationships and Data Flows
- User (CLI or browser) → HTTP/gRPC → Backend API → enqueues Task → Core pipeline orchestrator → PageLoader → Layout detection → Parallel OCR calls to external service → Postprocess & format → persist in DB → API returns JSON/Markdown → Client/Frontend renders result.
- In self-hosted mode, backend also contacts local vLLM/SGLang container.

##### Architectural Patterns & Principles
- Modular Pipeline Pattern (each stage is a pluggable step)
- MVC/Hexagonal style in backend (API / core logic / repository)
- Component-based UI (React + Vite)
- Containerized microservices (frontend, backend, model server) orchestrated via Docker scripts
- Configuration via YAML (config.yaml) and environment files

##### Technologies & Frameworks
- Python 3.12, FastAPI (or Flask), SQLAlchemy/Pydantic, uvicorn
- React, TypeScript, Vite, pnpm, Sonner UI components
- Docker, Nginx
- vLLM / SGLang for model serving
- PP-DocLayout-V3 for layout analysis

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        CLI["CLI / Python SDK"]:::sdk
        React["React Web App"]:::frontend
    end

    %% SDK Modules
    subgraph "SDK Modules"
        PL["PageLoader"]:::sdk
        LD["Layout Detector"]:::sdk
        OCSDK["OCRClient (MaaS/Self-Host)"]:::sdk
        PS["Pipeline Orchestrator"]:::sdk
        RFSDK["ResultFormatter"]:::sdk
    end

    %% Backend Layers
    subgraph "Backend API" 
        subgraph "API Layer"
            SysAPI["System API Endpoints"]:::backend
            TaskAPI["Task API Endpoints"]:::backend
        end
        subgraph "Core Pipeline & Task Mgmt"
            PF["Pipeline Flows"]:::backend
            TM["Task Manager & Worker"]:::backend
            LM["Lock & Recovery & Retry"]:::backend
            OCBE["OCR Client Abstraction"]:::backend
            subgraph "Pipeline Steps"
                PI["PDF→Image"]:::backend
                LOCR["Layout OCR"]:::backend
                MR["Merge Results"]:::backend
            end
        end
        DB["Database Layer"]:::backend
    end

    %% OCR Pipeline (combined view)
    subgraph "OCR Pipeline"
        PL --> LD --> OCSDK --> RFSDK
    end

    %% External Services
    subgraph "External OCR Services"
        MaaS["Zhipu MaaS API"]:::external
        vLLM["vLLM Model Server"]:::external
        SGLang["SGLang Model Server"]:::external
    end

    %% Frontend Pipeline
    CLI -->|uses SDK| PL
    CLI -->|server mode HTTP| SysAPI
    React -->|HTTP Request| TaskAPI

    %% Backend flow
    TaskAPI -->|enqueue task| PF
    PF --> TM
    TM --> LM
    TM --> PI
    PI --> LOCR
    LOCR --> OCSDK
    OCSDK --> MaaS
    OCSDK --> vLLM
    OCSDK --> SGLang
    LOCR --> MR
    MR --> RFSDK
    RFSDK --> DB
    DB -->|results| TaskAPI
    SysAPI -->|health| React

    %% Click Events - SDK
    click CLI "https://github.com/zai-org/glm-ocr/blob/main/glmocr/cli.py"
    click PL "https://github.com/zai-org/glm-ocr/blob/main/glmocr/dataloader/page_loader.py"
    click LD "https://github.com/zai-org/glm-ocr/blob/main/glmocr/layout/layout_detector.py"
    click OCSDK "https://github.com/zai-org/glm-ocr/blob/main/glmocr/ocr_client.py"
    click PS "https://github.com/zai-org/glm-ocr/blob/main/glmocr/pipeline/pipeline.py"
    click RFSDK "https://github.com/zai-org/glm-ocr/blob/main/glmocr/postprocess/result_formatter.py"
    click CLI "https://github.com/zai-org/glm-ocr/blob/main/glmocr/__main__.py"
    click CLI "https://github.com/zai-org/glm-ocr/blob/main/glmocr/api.py"
    click CLI "https://github.com/zai-org/glm-ocr/blob/main/glmocr/config.py"
    click LD "https://github.com/zai-org/glm-ocr/blob/main/glmocr/layout/base.py"
    click OCSDK "https://github.com/zai-org/glm-ocr/blob/main/glmocr/maas_client.py"
    click RFSDK "https://github.com/zai-org/glm-ocr/blob/main/glmocr/postprocess/base_post_processor.py"
    click PS "https://github.com/zai-org/glm-ocr/blob/main/glmocr/postprocess/result_formatter.py"

    %% Click Events - Server Entry
    click SysAPI "https://github.com/zai-org/glm-ocr/blob/main/glmocr/server.py"

    %% Click Events - Backend API
    click SysAPI "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/api/system.py"
    click TaskAPI "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/api/tasks.py"
    click PF "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/core/flows/pipeline_flow.py"
    click TM "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/core/task_manager.py"
    click LM "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/core/lock_manager.py"
    click LM "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/core/recovery_handler.py"
    click LM "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/core/retry_handler.py"
    click OCBE "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/core/ocr_client.py"
    click PI "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/core/steps/pdf_to_image.py"
    click LOCR "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/core/steps/layout_ocr.py"
    click MR "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/core/steps/merge_results.py"
    click DB "https://github.com/zai-org/glm-ocr/blob/main/apps/backend/app/db/database.py"

    %% Click Events - Frontend
    click React "https://github.com/zai-org/glm-ocr/blob/main/apps/frontend/src/main.tsx"
    click React "https://github.com/zai-org/glm-ocr/blob/main/apps/frontend/vite.config.ts"
    click React "https://github.com/zai-org/glm-ocr/blob/main/apps/frontend/index.html"

    %% Click Events - CI/CD & Docker
    click CLI "https://github.com/zai-org/glm-ocr/blob/main/examples/example.py"
    click CLI "https://github.com/zai-org/glm-ocr/tree/main/examples"
    click React "https://github.com/zai-org/glm-ocr/tree/main/apps/frontend/Dockerfile"
    click React "https://github.com/zai-org/glm-ocr/blob/main/apps/frontend/nginx.conf"

    %% Styles
    classDef frontend fill:#b3d4fc,stroke:#02457a,color:#000;
    classDef backend fill:#d4fcb3,stroke:#457a02,color:#000;
    classDef external fill:#fcdbb3,stroke:#7a4502,color:#000;
    classDef sdk fill:#e0e0e0,stroke:#5a5a5a,color:#000;
```
