# adithya-s-k/omniparse architecture

> Architecture diagram of the GitHub repository adithya-s-k/omniparse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adithya-s-k/omniparse
- Repository: https://github.com/adithya-s-k/omniparse

## Overview

##### Project type and purpose
- OmniParse is primarily a backend-focused, monolithic Python service that ingests arbitrary unstructured data (documents, images, audio/video, web pages) and converts it into structured, GenAI-ready outputs via deep-learning models.
- It also provides a Python client SDK, a CLI for model download and server startup, and an ("interactive") Gradio UI.

##### File structure
- Top-level artifacts:
- server.py         – main FastAPI (or similar) HTTP server entrypoint
- download.py       – CLI to preload models
- Dockerfile        – containerization
- omniparse/        – core modules by domain (chunking, documents, extraction, image, media, web, models, utils)
- python-sdk/       – client library that wraps HTTP calls to the server
- docs/             – user/developer documentation & examples
- examples/         – Colab notebook for end-to-end demo
- The omniparse package follows a “router + handler + model” pattern: each subfolder (e.g., `omniparse/documents/router.py`, `omniparse/image/router.py`, `omniparse/media/router.py`, `omniparse/web/router.py`) registers endpoints, delegates to domain-specific processing modules, which in turn invoke preloaded DL models.

##### README for additional insights
- CLI flags `--documents`, `--media`, `--web` control which modules (and therefore which heavy models) are loaded into GPU memory at startup.
- Exposed REST endpoints under `/parse_document`, `/parse_media`, `/parse_image`, `/parse_website` correspond one-to-one to the routers.
- No persistent database is used – data flows in (file or URL), is processed in memory via models, and results are returned immediately.

##### Main components and interactions
a. Clients:
- Python SDK (`python-sdk/`)
- REST/HTTP clients (curl, Postman)
- CLI (`download.py`, `server.py` flags)
- Gradio UI (embedded or launched by server)
b. API Server Layer (`server.py` + FastAPI/Starlette):
- API Gateway accepts HTTP requests → dispatches to domain routers
c. Domain Routers & Handlers:
- Document Router
- Image Router
- Media Router
- Web Router
- (Optional) Sheets Router
d. Processing Modules:
- Chunking (`omniparse/chunking/`)
- Extraction (`omniparse/extraction/`)
- OCR & Layout (Surya OCR series, Florence-2)
- Whisper for audio/video transcription
- Web crawler (Selenium-based)
e. Model Manager & GPU Resource:
- Central loader orchestrates model fetch (via `download.py`) and maintains them in GPU memory (with caching)
f. File System & External Services:
- Local disk for temporary file storage
- Selenium / headless browser for web crawling
g. Output Layer:
- Structured Markdown / JSON returned over HTTP
- (Optionally) streamed back to Gradio UI or Python SDK

##### Architectural patterns & design principles
- Modular router pattern: clearly separated REST endpoints match to domain routers, simplifying adding new data-type support.
- Plugin-style model loading: CLI flags selectively load heavy models, reducing startup footprint.
- Separation of concerns: API layer vs. processing layer vs. model management.
- Stateless request handling: no database–the service is horizontally scalable (multiple container instances behind a load balancer).

##### Elements
- Clear labels: “API Gateway (FastAPI)”, “Document Router”, “Image Router”, “Model Manager”, “GPU Memory”, “Python SDK (client)”, “CLI”
- Client → API Gateway → Domain Router → Processing Module → Model Manager → GPU
- Model Manager → Processing Module → Router → Response → Client
- Blue rectangles for server internals (modules, routers)
- Orange for external clients (SDK, CLI, UI)
- Grey for external services (Selenium, local FS)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB
        API["API Gateway\n(server.py / FastAPI)"]:::server
        click API "https://github.com/adithya-s-k/omniparse/blob/main/server.py"
        subgraph "Domain Routers"
            direction TB
            DR["Document Router"]:::server
            click DR "https://github.com/adithya-s-k/omniparse/blob/main/omniparse/documents/router.py"
            IR["Image Router"]:::server
            click IR "https://github.com/adithya-s-k/omniparse/blob/main/omniparse/image/router.py"
            MR["Media Router"]:::server
            click MR "https://github.com/adithya-s-k/omniparse/blob/main/omniparse/media/router.py"
            WR["Web Router"]:::server
            click WR "https://github.com/adithya-s-k/omniparse/blob/main/omniparse/web/router.py"
            SR["Sheets Router (Optional)"]:::server
            click SR "https://github.com/adithya-s-k/omniparse/tree/main/omniparse/sheets/"
        end
        subgraph "Processing Modules"
            direction TB
            CH["Chunking Module"]:::server
            click CH "https://github.com/adithya-s-k/omniparse/tree/main/omniparse/chunking/"
            EX["Extraction Module"]:::server
            click EX "https://github.com/adithya-s-k/omniparse/tree/main/omniparse/extraction/"
            ISO["Image Proc & OCR"]:::server
            click ISO "https://github.com/adithya-s-k/omniparse/blob/main/omniparse/image/process.py"
            click ISO "https://github.com/adithya-s-k/omniparse/blob/main/omniparse/image/utils.py"
            MU["Media Utilities"]:::server
            click MU "https://github.com/adithya-s-k/omniparse/blob/main/omniparse/media/utils.py"
            WC["Web Crawler & Strategies"]:::server
            click WC "https://github.com/adithya-s-k/omniparse/blob/main/omniparse/web/web_crawler.py"
            click WC "https://github.com/adithya-s-k/omniparse/blob/main/omniparse/web/crawler_strategy.py"
        end
        subgraph "Model Manager & GPU"
            direction TB
            MM["Model Manager"]:::server
            click MM "https://github.com/adithya-s-k/omniparse/tree/main/omniparse/models/"
            GPU["GPU Memory\n(Model Storage)"]:::gpu
        end
    end

    %% External Clients and Services
    SDK["Python SDK (Client)"]:::client
    click SDK "https://github.com/adithya-s-k/omniparse/tree/main/python-sdk/"
    CLI["CLI Tool\n(download.py & flags)"]:::client
    click CLI "https://github.com/adithya-s-k/omniparse/blob/main/download.py"
    UI["Gradio UI"]:::client
    SEL["Selenium WebDriver"]:::service
    FS["Local File System"]:::service

    %% Connections
    SDK -->|"HTTP Request"| API
    CLI -->|"Start Server / Load Models"| API
    UI -->|"Interactive Calls"| API
    WR -->|"Uses WebDriver"| SEL
    FS -->|"Temp Storage"| CH
    FS -->|"Temp Storage"| EX

    API --> DR
    API --> IR
    API --> MR
    API --> WR
    API --> SR

    DR --> CH
    DR --> EX
    IR --> ISO
    MR --> MU
    MR --> EX
    WR --> WC

    CH --> MM
    EX --> MM
    ISO --> MM
    MU --> MM
    WC --> MM

    MM --> GPU

    %% Styles
    classDef server fill:#a8d0e6,stroke:#374785,color:#000;
    classDef gpu fill:#8ae234,stroke:#4e8c2e,color:#000,shape:cylinder;
    classDef client fill:#f6a609,stroke:#cc7b00,color:#000;
    classDef service fill:#cccccc,stroke:#888888,color:#000;
```
