# dhavalpotdar/graph-convolution-on-structured-documents architecture

> Architecture diagram of the GitHub repository dhavalpotdar/graph-convolution-on-structured-documents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhavalpotdar/graph-convolution-on-structured-documents
- Repository: https://github.com/dhavalpotdar/graph-convolution-on-structured-documents

## Overview

##### Project type and purpose
- This is a research-oriented Python codebase that converts structured document layouts into graph representations and applies a (work-in-progress) Graph Convolutional Neural Network (GCN) for node-level classification.
- Key use case: information extraction from invoices, receipts, tables, etc., by treating layout entities as graph nodes and running GCNs over them.

##### File structure
- Top-level scripts and modules:
- `grapher.py` – builds a graph (nodes+edges) from OCR object maps
- `graph_operator.py` – constructs adjacency matrices, feature matrices for GCN
- `layers.py` – defines custom GCN layers in TensorFlow
- `models.py` – composes those layers into a trainable model
- `object_map_generation.py` – (optional) helper to generate or preprocess object maps
- `text_utils.py` – extracts textual features from OCR’d text
- `test_read.py` – example of reading/parsing input
- Supporting directories:
- `data/` – sample input `object_map.csv`
- `outputs/` – generated graph image (`object_tree.png/jpg`) and `connections.csv`
- `unit tests/` – module-specific tests for adjacency layers, graph operator, text utils
- Config/build files:
- `requirements.txt` – dependency list (TensorFlow 1.8, numpy, pandas, etc.)

##### Extract insights from the README
- Core pipeline:
2. `grapher.py` → link each object to nearest right/under neighbors → output graph image + CSV of connections
3. Build adjacency & feature matrices (`graph_operator.py` + `text_utils.py`)
4. Feed into GCN layers (`layers.py`) combined in `models.py` for node classification
- Model is TensorFlow 1.8, under active development.

##### Components
a. Input & Preprocessing
- External OCR Tool → `object_map.csv` (data folder)
- (Optional) `object_map_generation.py` for formatting/preprocessing
b. Graph Generation
- `grapher.py`
- Reads `object_map.csv`
- Computes nearest-neighbor links
- Outputs `connections.csv` + `object_tree.png` in `outputs/`
c. Feature & Adjacency Preparation
- `text_utils.py` – textual feature extraction (embeddings, counts)
- `graph_operator.py` – builds adjacency matrices and node feature matrices
d. Graph Convolutional Model
- `layers.py` – defines GraphConvLayer, ReLU, dropout, etc.
- `models.py` – composes layers into a forward pass, loss, training ops
e. Training & Inference
- TensorFlow session code (inside `models.py` or external script)
- Outputs node classification results
f. Testing & Validation
- `unit tests/` covering adjacency, graph operator, text utils
g. Supporting artifacts
- `requirements.txt`
- Example reader: `test_read.py`

##### Relationships & data flow
OCR Tool → object_map_generation (optional) → Grapher → Outputs (graph CSV & image) → Feature Extraction + Adjacency Builder → GCN Model → Predictions
- Side branch: unit tests target each module individually.

##### Architectural patterns & design principles
- Pipeline/ETL style: clear separation between data ingestion, transformation, and modeling
- Modular design: each major step is a separate Python module/script
- Test‐driven verification: each module has its own unit tests

##### Relevant technologies & dependencies
- Python 3.x, Pandas, NumPy
- TensorFlow 1.8 for model layers & training
- CSV and image output for graph visualization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Preprocessing
    subgraph "Input & Preprocessing"
        OCR["External OCR Tool"]:::data
        CSV["object_map.csv"]:::data
    end
    OCR --> CSV
    click CSV "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/data/object_map.csv"

    %% Preprocessing
    subgraph "Preprocessing"
        OMGen["object_map_generation.py"]:::etl
    end
    CSV --> OMGen
    click OMGen "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/object_map_generation.py"

    %% Graph Generation
    subgraph "Graph Generation"
        Grapher["grapher.py"]:::etl
        Connections["connections.csv"]:::data
        GraphImg["object_tree.png/jpg"]:::output
    end
    CSV --> Grapher
    OMGen --> Grapher
    Grapher --> Connections
    Grapher --> GraphImg
    click Grapher "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/grapher.py"
    click Connections "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/outputs/connections.csv"
    click GraphImg "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/tree/master/outputs/"

    %% Feature & Adjacency Preparation
    subgraph "Feature & Adjacency Preparation"
        TextUtils["text_utils.py"]:::etl
        GraphOp["graph_operator.py"]:::etl
    end
    Connections --> TextUtils
    Connections --> GraphOp
    TextUtils --> GraphOp
    click TextUtils "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/text_utils.py"
    click GraphOp "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/graph_operator.py"

    %% Graph Convolutional Model
    subgraph "Graph Convolutional Model"
        Layers["layers.py"]:::ml
        Models["models.py"]:::ml
    end
    GraphOp --> Layers
    GraphOp --> Models
    Layers --> Models
    click Layers "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/layers.py"
    click Models "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/models.py"

    %% Training & Inference Output
    Models --> Predictions["Node Classification Results"]:::output

    %% Example Reader
    CSV --> TestRead["test_read.py"]:::etl
    click TestRead "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/test_read.py"

    %% Dependency Specification
    Reqs["requirements.txt"]:::data
    click Reqs "https://github.com/dhavalpotdar/graph-convolution-on-structured-documents/blob/master/requirements.txt"

    %% Unit Tests
    subgraph "Unit Tests"
        subgraph "Adjacency Layer Tests"
            Adj1["adjacency_layer.py"]:::test
            Adj2["test_adjacency_layer.py"]:::test
        end
        subgraph "Graph Operator Tests"
            GOpTest["test_graph_operator.py"]:::test
            GOpReadTest["test_read.py"]:::test
        end
        subgraph "Text Utils Tests"
            TextTest["test_get_text_features.py"]:::test
        end
    end
    GraphOp -.-> Adj1
    GraphOp -.-> Adj2
    GraphOp -.-> GOpTest
    GraphOp -.-> GOpReadTest
    TextUtils -.-> TextTest

    %% Styles
    classDef data fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef etl fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef ml fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef output fill:#e0e0e0,stroke:#424242,color:#424242;
    classDef test fill:#f8bbd0,stroke:#880e4f,color:#880e4f,stroke-dasharray: 2 2;
```
