# kallunwillock/chibipdf architecture

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

- Interactive diagram: https://gitdiagram.com/kallunwillock/chibipdf
- Repository: https://github.com/kallunwillock/chibipdf

## Overview

1. **Repository scope**
   - This repo currently contains a single delivered component: **ChibiEx**.
   - The broader “ChibiPDF” suite is intended to include PDF generation too, but that part (**ChibiScribe**) is not present yet.
   - So the architecture here is a **self-contained VBA library** for PDF extraction, rendering, and OCR.

2. **Top-level structure**
   - `src/ChibiEx.cls` is the core implementation artifact.
   - There are no separate service folders, native DLLs, scripts, or build pipelines in the repo.
   - The library is meant to be imported/used directly from a VBA host application.

3. **Primary runtime boundary**
   - The consumer boundary is a **VBA host** such as Excel, Word, Access, Outlook, PowerPoint, or VB6-compatible environments.
   - ChibiEx runs inside the host process and exposes an object-oriented API to VBA code.
   - There is no standalone executable; this is an in-process automation/library component.

4. **Core subsystem: ChibiEx class**
   - `ChibiEx` is the central object that coordinates all functionality.
   - It likely manages document state, current page selection, output buffers, and OCR results behind one class interface.
   - The README shows it is used for both PDF operations and standalone OCR, so the class acts as a **facade** over multiple internal capabilities.

5. **Input types supported**
   - The library accepts **PDF files** for text extraction and rendering.
   - It also accepts **image inputs** for OCR: image files, HBITMAPs, `StdPicture`s, and in-memory streams.
   - This means the architecture is designed around multiple input adapters feeding a common recognition/rendering pipeline.

6. **PDF text extraction flow**
   - For searchable PDFs, text extraction can happen directly from the document content.
   - For scanned PDFs, the class automatically detects the image-based case and switches to OCR.
   - The key architectural behavior is that the caller uses the same `ExtractText` API regardless of PDF type; the class hides the routing decision internally.

7. **OCR pipeline**
   - OCR is done without external tools like Tesseract or Adobe Acrobat.
   - The OCR stage relies on the **Windows OCR engine** available on supported Windows versions.
   - For scanned PDFs, the flow is: PDF page → render page image → OCR in memory → return extracted text.
   - For standalone OCR, the flow is: image input → OCR engine → `ResultText`.

8. **Rendering subsystem**
   - ChibiEx can render PDF pages to **PNG files**, **byte arrays/memory**, **streams**, or **`StdPicture` objects**.
   - This is a distinct output path from text extraction and is likely used both for user-visible exports and as an internal step before OCR.
   - The API supports rendering all pages, a single page, a page range, or arbitrary page lists, which implies a page-oriented document model internally.

9. **Output surfaces and data flow**
   - The library produces two main kinds of outputs:
     - **Text**: returned as strings (`ExtractText`, `ExtractAllText`, `ResultText`)
     - **Images**: written to files or returned as in-memory picture/stream/byte representations
   - The data flow is deliberately in-memory where possible, especially for OCR of scanned PDFs, to avoid temporary files.

10. **Dependency and infrastructure boundaries**
   - The repo explicitly targets **no external dependencies**: no Acrobat, no GhostScript, no Tesseract, no custom DLLs.
   - The only meaningful external platform dependency is **Windows** plus the built-in OCR capability.
   - This makes the architecture suitable for locked-down enterprise environments where installing third-party software is difficult.

11. **Compatibility and platform model**
   - The project targets **VBA 7.0+**, **32-bit and 64-bit**, and Windows 10 build 10240+ or later.
   - The architecture must therefore use Windows/VBA-compatible interop patterns rather than native add-ins or unmanaged code.
   - The README credit to WinRT interop techniques suggests the implementation leans on modern Windows APIs while staying usable from VBA.

12. **What to draw in an architecture diagram**
   - Show a single **ChibiEx VBA class** at the center.
   - On the left, show inputs from the host application: PDF files and image sources.
   - Inside, show two main processing paths: **direct PDF text extraction** and **render → OCR**.
   - On the right, show outputs as text results and rendered images/streams/files.
   - Add one external platform dependency boundary only: **Windows OCR / Windows runtime APIs**.

Main entry points: [`src/ChibiEx.cls`](https://github.com/kallunwillock/chibipdf/blob/main/src/ChibiEx.cls) (ChibiEx)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["VBA Host"]
  node_vba_host["VBA Host<br/>caller"]
end

subgraph group_chibiex["ChibiEx"]
  node_chibiex_class["ChibiEx<br/>facade class<br/>[ChibiEx.cls]"]
  node_doc_state["Doc State<br/>document model"]
  node_api_surface["API Surface<br/>VBA methods"]
end

subgraph group_inputs["Inputs"]
  node_pdf_input["PDF Input<br/>document source"]
  node_image_input["Image Input<br/>image source"]
end

subgraph group_processing["Processing"]
  node_pdf_router["PDF Router<br/>routing logic"]
  node_text_extract["Text Extract"]
  node_scan_detect["Scan Detect<br/>page analysis"]
  node_page_render["Page Render<br/>renderer"]
  node_ocr_pipeline["OCR Pipeline<br/>recognition flow"]
  node_page_model["Page Model<br/>page selection"]
end

subgraph group_outputs["Outputs"]
  node_text_output["Text Output<br/>string results"]
  node_image_output["Image Output<br/>rendered results"]
end

subgraph group_platform["Platform"]
  node_windows_ocr{{"Windows OCR<br/>platform API"}}
  node_windows_host["Windows Host<br/>runtime boundary"]
end

node_vba_host -->|"uses"| node_chibiex_class
node_chibiex_class -->|"exposes"| node_api_surface
node_chibiex_class -->|"tracks"| node_doc_state
node_api_surface -->|"accepts"| node_pdf_input
node_api_surface -->|"accepts"| node_image_input
node_api_surface -->|"selects"| node_page_model
node_pdf_input -->|"feeds"| node_pdf_router
node_pdf_router -->|"direct path"| node_text_extract
node_pdf_router -->|"scan path"| node_scan_detect
node_scan_detect -->|"renders"| node_page_render
node_page_model -->|"controls"| node_page_render
node_page_model -->|"controls"| node_text_extract
node_page_render -->|"inputs"| node_ocr_pipeline
node_image_input -->|"feeds"| node_ocr_pipeline
node_ocr_pipeline -->|"calls"| node_windows_ocr
node_windows_ocr -->|"runs on"| node_windows_host
node_text_extract -->|"returns"| node_text_output
node_ocr_pipeline -->|"returns"| node_text_output
node_page_render -->|"returns"| node_image_output

click node_chibiex_class "https://github.com/kallunwillock/chibipdf/blob/main/src/ChibiEx.cls"

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_vba_host toneBlue
class node_chibiex_class,node_doc_state,node_api_surface toneAmber
class node_pdf_input,node_image_input toneMint
class node_pdf_router,node_text_extract,node_scan_detect,node_page_render,node_ocr_pipeline,node_page_model toneRose
class node_text_output,node_image_output toneIndigo
class node_windows_ocr,node_windows_host toneTeal
```

## Components

### VBA Host

Excel, Word, Access, Outlook, VB6-compatible callers

- **VBA Host**: caller · In-process VBA application that creates and uses ChibiEx

### ChibiEx

Single in-process VBA library class

- [ChibiEx](https://github.com/kallunwillock/chibipdf/blob/main/src/ChibiEx.cls): facade class · Central object exposing PDF extraction, rendering, and OCR · `src/ChibiEx.cls`
- **Doc State**: document model · Tracks current file, page selection, and working state
- **API Surface**: VBA methods · Object-oriented entry points such as extract and render operations

### Inputs

PDF and image sources accepted by the library

- **PDF Input**: document source · PDF files supplied for text extraction or rendering
- **Image Input**: image source · Files, HBITMAPs, StdPictures, and streams for OCR

### Processing

Document routing, rendering, and OCR flow

- **PDF Router**: routing logic · Chooses direct extraction or scan-to-OCR path
- **Text Extract**: pdf text extraction · Reads searchable PDF text directly from document content
- **Scan Detect**: page analysis · Identifies scanned or image-based PDF pages
- **Page Render**: renderer · Renders PDF pages to images in memory or file targets
- **OCR Pipeline**: recognition flow · Converts rendered page images or standalone images into text
- **Page Model**: page selection · Handles single pages, ranges, and page lists

### Outputs

Text and image result surfaces

- **Text Output**: string results · ExtractText, ExtractAllText, and ResultText outputs
- **Image Output**: rendered results · PNG files, byte arrays, streams, and StdPicture objects

### Platform

Windows OCR and runtime APIs

- **Windows OCR**: platform API · Built-in Windows OCR and WinRT-backed runtime services
- **Windows Host**: runtime boundary · Supported Windows 10+ platform providing in-process APIs

## Connections

- VBA Host → ChibiEx: uses · Host application instantiates and calls the VBA class
- ChibiEx → API Surface: exposes · Public methods provide extraction, rendering, and OCR entry points
- ChibiEx → Doc State: tracks · Maintains current document and working state
- API Surface → PDF Input: accepts · PDF files are supplied through the public API
- API Surface → Image Input: accepts · Image sources are supplied for standalone OCR
- API Surface → Page Model: selects · Operations can target pages, ranges, or page lists
- PDF Input → PDF Router: feeds · PDF content enters the routing decision
- PDF Router → Text Extract: direct path · Searchable PDFs go to direct text extraction
- PDF Router → Scan Detect: scan path · Scanned PDFs are identified for OCR handling
- Scan Detect → Page Render: renders · Image-based pages are rendered before OCR
- Page Model → Page Render: controls · Rendering honors page selection and paging mode
- Page Model → Text Extract: controls · Extraction can target specific pages or ranges
- Page Render → OCR Pipeline: inputs · Rendered page images are passed to OCR
- Image Input → OCR Pipeline: feeds · Standalone images bypass PDF rendering and go directly to OCR
- OCR Pipeline → Windows OCR: calls · OCR relies on the built-in Windows engine
- Windows OCR → Windows Host: runs on · OCR is available through the supported Windows runtime
- Text Extract → Text Output: returns · Direct extraction produces text results
- OCR Pipeline → Text Output: returns · OCR produces ResultText and other string outputs
- Page Render → Image Output: returns · Rendering produces files and in-memory image representations