# vinayakbhat19/aigstverify architecture

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

- Interactive diagram: https://gitdiagram.com/vinayakbhat19/aigstverify
- Repository: https://github.com/vinayakbhat19/aigstverify

## Overview

GSTVision AI is a web-based GST invoice verification system. A user uploads an invoice; the backend extracts invoice fields, checks GST and amount compliance, classifies the invoice, assesses fraud risk, stores the result, and can generate a PDF report. The repository also contains a substantial synthetic-invoice generation package, represented as a separate capability. The app excerpt omits parts of the upload handler, so edges for orchestration rely on documented capabilities or are marked unverified; generation links are limited to references visible in sampled source.

Main entry points: [`app.py`](https://github.com/vinayakbhat19/aigstverify/blob/main/app.py) (FastAPI application), [`utils/llm_extractor.py`](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/llm_extractor.py) (Structured extraction), [`utils/gst_api.py`](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/gst_api.py) (GSTIN lookup), [`utils/product_classifier.py`](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/product_classifier.py) (Product classification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Application"]
  node_api["FastAPI application<br/>[app.py]"]
  node_ui["Upload and results UI"]
  node_reports["PDF reporting"]
end

subgraph group_extract["Invoice Extraction"]
  node_ocr["OCR processing<br/>[ocr.py]"]
  node_llm["Structured extraction<br/>[llm_extractor.py]"]
end

subgraph group_verify["Verification and Risk"]
  node_validator["Invoice validation<br/>[validator.py]"]
  node_amount["Amount validation"]
  node_gstapi["GSTIN lookup<br/>[gst_api.py]"]
  node_classifier["Product classification"]
  node_rates["GST rate check"]
  node_duplicates["Duplicate detection"]
  node_fraud["Fraud assessment<br/>[fraud.py]"]
  node_store[("Invoice database<br/>[database.py]")]
end

subgraph group_synth["Synthetic Invoice Data"]
  node_content["Invoice content<br/>[content.py]"]
  node_gstdata["GST reference data<br/>[gst.py]"]
  node_style["Invoice styling<br/>[style.py]"]
  node_render["Invoice rendering<br/>[render.py]"]
  node_augment["Image augmentation<br/>[augment.py]"]
end

node_user(("Invoice user"))
node_gemini{{"Gemini service"}}
node_gstservice{{"GST API service"}}

node_user -->|"uploads invoice"| node_api
node_api -->|"serves interface"| node_ui
node_api -.->|"extracts text"| node_ocr
node_api -.->|"extracts fields"| node_llm
node_api -.->|"validates invoice"| node_validator
node_api -.->|"checks amounts"| node_amount
node_api -->|"checks GSTIN"| node_gstapi
node_api -->|"classifies invoice"| node_classifier
node_api -->|"checks GST rate"| node_rates
node_api -.->|"checks duplicates"| node_duplicates
node_api -.->|"assesses risk"| node_fraud
node_api -->|"saves invoice"| node_store
node_api -.->|"generates report"| node_reports
node_llm -.->|"requests extraction"| node_gemini
node_classifier -.->|"requests category"| node_gemini
node_gstapi -.->|"queries GSTIN"| node_gstservice
node_api -.->|"reads duplicate state"| node_store
node_content -->|"uses reference data"| node_gstdata
node_style -->|"uses formatters"| node_content

click node_api "https://github.com/vinayakbhat19/aigstverify/blob/main/app.py"
click node_ui "https://github.com/vinayakbhat19/aigstverify/tree/main/templates"
click node_ocr "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/ocr.py"
click node_llm "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/llm_extractor.py"
click node_validator "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/validator.py"
click node_amount "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/amount_validator.py"
click node_gstapi "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/gst_api.py"
click node_classifier "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/product_classifier.py"
click node_rates "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/gst_rate_validator.py"
click node_duplicates "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/duplicate_detector.py"
click node_fraud "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/fraud.py"
click node_store "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/database.py"
click node_reports "https://github.com/vinayakbhat19/aigstverify/blob/main/utils/report_generator.py"
click node_content "https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/content.py"
click node_gstdata "https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/gst.py"
click node_style "https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/style.py"
click node_render "https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/render.py"
click node_augment "https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/augment.py"

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_api,node_ui,node_reports,node_user toneBlue
class node_ocr,node_llm toneAmber
class node_validator,node_amount,node_gstapi,node_classifier,node_rates,node_duplicates,node_fraud,node_store,node_gstservice toneMint
class node_content,node_gstdata,node_style,node_render,node_augment toneRose
class node_gemini toneIndigo
```

## Components

### Web Application

- [FastAPI application](https://github.com/vinayakbhat19/aigstverify/blob/main/app.py): `app.py`
- [Upload and results UI](https://github.com/vinayakbhat19/aigstverify/tree/main/templates): `templates`
- [PDF reporting](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/report_generator.py): `utils/report_generator.py`

### Invoice Extraction

- [OCR processing](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/ocr.py): `utils/ocr.py`
- [Structured extraction](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/llm_extractor.py): `utils/llm_extractor.py`

### Verification and Risk

- [Invoice validation](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/validator.py): `utils/validator.py`
- [Amount validation](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/amount_validator.py): `utils/amount_validator.py`
- [GSTIN lookup](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/gst_api.py): `utils/gst_api.py`
- [Product classification](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/product_classifier.py): `utils/product_classifier.py`
- [GST rate check](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/gst_rate_validator.py): `utils/gst_rate_validator.py`
- [Duplicate detection](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/duplicate_detector.py): `utils/duplicate_detector.py`
- [Fraud assessment](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/fraud.py): `utils/fraud.py`
- [Invoice database](https://github.com/vinayakbhat19/aigstverify/blob/main/utils/database.py): `utils/database.py`

### Synthetic Invoice Data

- [Invoice content](https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/content.py): `datagen/content.py`
- [GST reference data](https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/gst.py): `datagen/gst.py`
- [Invoice styling](https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/style.py): `datagen/style.py`
- [Invoice rendering](https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/render.py): `datagen/render.py`
- [Image augmentation](https://github.com/vinayakbhat19/aigstverify/blob/main/datagen/augment.py): `datagen/augment.py`

### Other components

- **Invoice user**
- **Gemini service**
- **GST API service**

## Connections

- Invoice user → FastAPI application: uploads invoice (evidence: `README.md`)
- FastAPI application → Upload and results UI: serves interface (evidence: `app.py`)
- FastAPI application → OCR processing: extracts text (evidence: `app.py`)
- FastAPI application → Structured extraction: extracts fields (evidence: `app.py`)
- FastAPI application → Invoice validation: validates invoice (evidence: `app.py`)
- FastAPI application → Amount validation: checks amounts (evidence: `app.py`)
- FastAPI application → GSTIN lookup: checks GSTIN (evidence: `app.py`)
- FastAPI application → Product classification: classifies invoice (evidence: `app.py`)
- FastAPI application → GST rate check: checks GST rate (evidence: `app.py`)
- FastAPI application → Duplicate detection: checks duplicates (evidence: `app.py`)
- FastAPI application → Fraud assessment: assesses risk (evidence: `app.py`)
- FastAPI application → Invoice database: saves invoice (evidence: `app.py`)
- FastAPI application → PDF reporting: generates report (evidence: `app.py`)
- Structured extraction → Gemini service: requests extraction
- Product classification → Gemini service: requests category
- GSTIN lookup → GST API service: queries GSTIN
- FastAPI application → Invoice database: reads duplicate state (evidence: `app.py`)
- Invoice content → GST reference data: uses reference data (evidence: `datagen/content.py`)
- Invoice styling → Invoice content: uses formatters (evidence: `datagen/style.py`)
