# 🏛️ RasgaPDF Architecture & Technical Design

RasgaPDF was designed with a single uncompromising mission: **deliver 2D physical spatial PDF layout analysis at native hardware speed with sub-millisecond latencies**.

---

## 1. High-Level Architecture Diagram

```mermaid
flowchart TD
    INPUT["Input PDF File / Buffer"] --> CORE["RasgaPDF Core (Rust)"]
    
    subgraph CORE["RasgaPDF High-Performance Engine"]
        MUPDF["MuPDF C-Binding"] --> PARALLEL["Rayon Parallel Pipeline"]
        PARALLEL --> PAGE_WORKER["Page Geometric Deconstruction"]
        PAGE_WORKER --> SPAN_EXTRACT["Physical Spans & Bounding Boxes"]
        PAGE_WORKER --> GRAPHICS["Embedded Images & Vector Paths (opt-in)"]
        SPAN_EXTRACT --> BUCKET_SORT["Y-Bucket & X-Order Spatial Sort"]
        BUCKET_SORT --> TABLE_DETECTOR["2D Column Projection Table Detector"]
        TABLE_DETECTOR --> SERIALIZER["Zero-Copy Serde JSON Serializer"]
        GRAPHICS --> SERIALIZER
    end
    
    SERIALIZER --> FFI["C-ABI FFI Layer (librasgapdf.so / .dll / .dylib)"]
    
    subgraph BINDINGS["Multi-Language Polyglot Bindings"]
        FFI --> PY["Python (ctypes / PyO3)"]
        FFI --> NODE["Node.js (koffi / CLI)"]
        FFI --> GO["Go (cgo)"]
        FFI --> CS["C# / .NET 8 (P/Invoke)"]
        CORE --> CLI["Standalone CLI Binary"]
    end
```

---

## 2. Core Principles

### A. Zero Guesswork, Exact Geometry
Standard PDF parsers attempt to guess Markdown headers (`# Header`), indentation, or bullet points using fragile heuristics. When applied to multi-column newspapers, medical records, or invoices, these heuristics fail catastrophically.

RasgaPDF returns **exact 2D physical bounds**:
- `x0, y0, x1, y1` (top-left to bottom-right).
- Real typography: Font name, font size, character count.
- Structured table cells with row and column indices.

### B. Embarrassingly Parallel Parsing (`rayon`)
PDF pages are completely independent data structures. RasgaPDF spawns worker threads matching your CPU core count using `rayon::into_par_iter()`. A 100-page document processes simultaneously across all available CPU threads with linear scalability.

### C. Unified C-ABI Polyglot Architecture
Rather than reimplementing geometric algorithms in 5 different languages, RasgaPDF maintains a single source of truth in **Rust (C99 ABI)**. The resulting shared library exports clean, thread-safe functions that can be imported by Python, JavaScript, Go, C#, Java, or C++ with zero friction.

### D. Graphics Without Pixel Bloat (opt-in)
Embedded images and vector paths are extracted in the same per-page worker, but only when requested (`extract_images` / `extract_drawings`). Image **bytes are never inlined in the JSON**: the tree carries metadata (dimensions, colour space, filter, byte length, SHA-256, placement `bbox`) and the original encoded stream is written to disk (`--extract-images DIR`) or returned as `Vec<u8>` by the Rust API. This keeps documents with large scans as light as text-only ones.

### E. Local DTOs Instead of `mupdf::page::StextPage`
MuPDF's structured-text JSON emits image blocks (`{"type":"image","bbox":{…}}`) **without** the `lines` field, which the upstream `StextPage` type requires. RasgaPDF deserializes into its own minimal DTOs (`RawStextPage`/`RawBlock`/`RawLine`/`RawFont`) where every field is optional. This tolerates image and structure blocks and prevents a single unusual block from silently emptying an entire page.