# pwronfounder/orca-data-instruct architecture

> Architecture diagram of the GitHub repository pwronfounder/orca-data-instruct, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pwronfounder/orca-data-instruct
- Repository: https://github.com/pwronfounder/orca-data-instruct

## Overview

##### Project type and purpose
- This is a Python-based command-line toolkit (“PDF Form Data Extractor”) whose sole purpose is to read PDF form documents, extract structured field data (section titles, field names, descriptions), and emit CSV or text outputs. It also includes a utility for slicing PDFs into page-ranges.

##### File structure
- Top-level scripts (pdf_parser.py, extract_fields_only.py, pdf_parser_pypdf2.py, extract_and_save_text.py, extract_text.py, create_partial_pdf.py) each implement a distinct extraction path or utility.
- The `pdfs/` folder holds sample input PDFs.
- The `output/` folder captures all generated CSVs, TXT files, debug logs and partial PDFs.
- `requirements.txt` declares external dependencies (`pdfminer.six`, `pdfplumber`, `PyPDF2`).
- A `tests/` folder verifies core parsing logic in `pdf_parser.py`.

##### README for additional insights
- The README confirms three extraction engines (pdfminer, pdfplumber, PyPDF2), unified parsing steps (identify “Figure X…” section markers, extract Field Name / Field Description pairs), and multiple output formats.
- It also documents command-line arguments and expected CSV schema (`Section`, `Field Name`, `Field Description`).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% File System
    subgraph "File System"
        PDFDir(("pdfs/")):::storage
        OutDir(("output/")):::storage
    end

    %% CLI Layer
    subgraph "CLI Layer"
        A1["pdf_parser.py\n(pdfminer engine)"]:::cli
        A2["extract_and_save_text.py\n(pdfplumber engine)"]:::cli
        A3["pdf_parser_pypdf2.py\n(PyPDF2 engine)"]:::cli
        A4["extract_fields_only.py"]:::cli
        A5["extract_text.py"]:::cli
    end

    %% Extraction Layer
    subgraph "Extraction Layer"
        E1["pdfminer.six"]:::process
        E2["pdfplumber"]:::process
        E3["PyPDF2"]:::process
    end

    %% Parser Layer
    subgraph "Parser Layer"
        P1["Core Parser Logic\n(Sections & Fields)"]:::process
    end

    %% Output Layer
    subgraph "Output Layer"
        O1["CSV Writer"]:::io
        O2["TXT Writer"]:::io
    end

    %% Utilities
    subgraph "Utilities"
        U1["create_partial_pdf.py\n(PDF slicing)"]:::util
    end

    %% Tests
    subgraph "Tests"
        T1["tests/test_pdf_parser.py"]:::test
    end

    %% Flow
    PDFDir --> A1
    PDFDir --> A2
    PDFDir --> A3
    PDFDir --> A4
    PDFDir --> A5

    A1 --> E1
    A2 --> E2
    A3 --> E3
    A4 --> E1
    A5 --> E1

    E1 --> P1
    E2 --> P1
    E3 --> P1

    P1 --> O1
    P1 --> O2
    O1 --> OutDir
    O2 --> OutDir

    PDFDir --> U1
    U1 --> OutDir

    T1 --> P1

    %% Click Events
    click A1 "https://github.com/pwronfounder/orca-data-instruct/blob/main/pdf_parser.py"
    click A2 "https://github.com/pwronfounder/orca-data-instruct/blob/main/extract_and_save_text.py"
    click A3 "https://github.com/pwronfounder/orca-data-instruct/blob/main/pdf_parser_pypdf2.py"
    click A4 "https://github.com/pwronfounder/orca-data-instruct/blob/main/extract_fields_only.py"
    click A5 "https://github.com/pwronfounder/orca-data-instruct/blob/main/extract_text.py"
    click U1 "https://github.com/pwronfounder/orca-data-instruct/blob/main/create_partial_pdf.py"
    click PDFDir "https://github.com/pwronfounder/orca-data-instruct/tree/main/pdfs/"
    click OutDir "https://github.com/pwronfounder/orca-data-instruct/tree/main/output/"
    click P1 "https://github.com/pwronfounder/orca-data-instruct/blob/main/pdf_parser.py"
    click T1 "https://github.com/pwronfounder/orca-data-instruct/blob/main/tests/test_pdf_parser.py"
    click Req "https://github.com/pwronfounder/orca-data-instruct/blob/main/requirements.txt"
    click Readme "https://github.com/pwronfounder/orca-data-instruct/blob/main/README.md"

    %% Additional nodes for config and docs
    Req["requirements.txt"]:::config
    Readme["README.md"]:::doc
    subgraph "Configuration & Documentation"
        Req
        Readme
    end

    %% Styles
    classDef storage fill:#a2d5c6,stroke:#333,stroke-width:1px,shape:cylinder
    classDef cli fill:#fff3b0,stroke:#f2a154,stroke-width:1px,shape:parallelogram
    classDef process fill:#84a9ac,stroke:#333,stroke-width:1px
    classDef io fill:#ffcad4,stroke:#333,stroke-width:1px,shape:cylinder
    classDef util fill:#cDB4DB,stroke:#333,stroke-width:1px
    classDef test fill:#e0e0e0,stroke-dasharray: 5 5
    classDef config fill:#ffd6a5,stroke:#333,stroke-width:1px
    classDef doc fill:#bde0fe,stroke:#333,stroke-width:1px
```
