# im-girisankar/ai-pdf-processor-local architecture

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

- Interactive diagram: https://gitdiagram.com/im-girisankar/ai-pdf-processor-local
- Repository: https://github.com/im-girisankar/ai-pdf-processor-local

## Overview

##### Project Type and Purpose
- This is a CLI-based, two-step document-processing tool.
- Purpose: 1) Convert plain-English criteria into structured rules (rules.json). 2) Apply those rules to a PDF using vision and text AI models to extract data and produce a Markdown report.

##### Main Components
a. User Interfaces & Inputs
- criteria.txt (user-defined extraction criteria)
- PDF file (user’s document to analyze)
b. Processing Scripts
- 1_create_rules.py (“Rule Creator”)
- 2_analyze_document.py (“Document Analyzer”)
c. Local Services & Libraries
- Ollama daemon (hosts the AI models)
- LLM model (e.g., llama3) for rule generation
- Vision model (e.g., llava) for PDF analysis
- Poppler utilities for PDF rendering
d. Data Artifacts
- rules.json (generated structured rules)
- <pdf_name>_analysis_report.md (final Markdown report)
e. Python Environment
- requirements.txt (dependencies: ollama SDK, poppler wrapper, etc.)

##### High-Level Workflow & Interactions
- Step 1: Rule Generation
1. User writes plain-English criteria in criteria.txt.
2. User runs `python 1_create_rules.py`.
3. Rule Creator script loads criteria.txt and calls the LLM (via Ollama API).
4. Ollama + llama3 model returns a structured rules.json.
5. rules.json is stored on disk.

- Step 2: Document Analysis
1. User runs `python 2_analyze_document.py`.
2. Script prompts for PDF file path.
3. Document Analyzer:
- Uses Poppler to convert PDF pages into images/text.
- Loads rules.json to know what data to extract.
- Calls the vision model (llava) via Ollama API to find and extract data from the rendered PDF.
4. Script assembles results and writes `<pdf_name>_analysis_report.md`.

##### Additional Architectural Notes
- 100% local processing: Ollama and Poppler are on-premise services.
- Dependency on the Python runtime and requirements.txt.
- Optionally, indicate error handling paths (e.g., missing PDF, model load failure).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Lane 1: User & Inputs
    subgraph "Lane 1: User & Inputs"
        direction TB
        criteria["criteria.txt"]:::input
        pdf["<pdf_name>.pdf"]:::input
    end

    %% Lane 2: Rule Creator (Step 1)
    subgraph "Lane 2: Step 1 - Rule Generation"
        direction TB
        rc[("Rule Creator\n1_create_rules.py")]:::process
    end

    %% Lane 3: Document Analyzer (Step 2)
    subgraph "Lane 3: Step 2 - Document Analysis"
        direction TB
        da[("Document Analyzer\n2_analyze_document.py")]:::process
    end

    %% Lane 4: Local AI Service & PDF Utils
    subgraph "Lane 4: Local Services & Libraries"
        direction TB
        ollama[(Ollama Daemon)]:::service
        llama3[(LLM Model\nllama3)]:::service
        llava[(Vision Model\nllava)]:::service
        poppler[(Poppler Utilities)]:::utils
    end

    %% Lane 5: Outputs
    subgraph "Lane 5: Outputs"
        direction TB
        rules["rules.json"]:::output
        report["<pdf_name>_analysis_report.md"]:::output
    end

    %% Connections Step 1
    criteria -->|"load criteria.txt"| rc
    rc -->|"JSON request"| ollama
    ollama -->|"invoke llama3"| llama3
    llama3 -->|"structured rules"| rules

    %% Connections Step 2
    pdf -->|"provide PDF path"| da
    da -->|"convert pages"| poppler
    da -->|"load rules.json"| rules
    da -->|"JSON+images"| ollama
    ollama -->|"invoke llava"| llava
    llava -->|"extracted data"| da
    da -->|"write report"| report

    %% Additional Dependencies
    requirements["requirements.txt"]:::deps
    README["README.md"]:::docs
    gitignore[".gitignore"]:::docs

    requirements --> rc
    requirements --> da

    %% Click Events
    click rc "https://github.com/im-girisankar/ai-pdf-processor-local/blob/main/1_create_rules.py"
    click da "https://github.com/im-girisankar/ai-pdf-processor-local/blob/main/2_analyze_document.py"
    click requirements "https://github.com/im-girisankar/ai-pdf-processor-local/blob/main/requirements.txt"
    click README "https://github.com/im-girisankar/ai-pdf-processor-local/blob/main/README.md"
    click gitignore "https://github.com/im-girisankar/ai-pdf-processor-local/blob/main/.gitignore"

    %% Styles
    classDef input fill:#b2f2bb,stroke:#2f8f44,stroke-width:2px
    classDef process fill:#aedcff,stroke:#2a6fbf,stroke-width:2px
    classDef service fill:#ffd8a8,stroke:#bf7310,stroke-width:2px
    classDef utils fill:#e9e9ef,stroke:#6b6b78,stroke-width:2px,stroke-dasharray: 5 5
    classDef output fill:#fff3bf,stroke:#ad8a00,stroke-width:2px
    classDef deps fill:#d0ebff,stroke:#339af0,stroke-width:2px
    classDef docs fill:#f1f3f5,stroke:#444,stroke-width:1px,stroke-dasharray: 2 2
```
