# pushpak1203/vat architecture

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

- Interactive diagram: https://gitdiagram.com/pushpak1203/vat
- Repository: https://github.com/pushpak1203/vat

## Overview

VAT Chain Auditor is a Python CLI for evidence-grounded cross-border VAT audits. A user supplies transaction JSON or an invoice image; the CLI invokes the orchestrator, which normalizes input, classifies the transaction, assesses risk and anomalies, applies VAT rules, optionally retrieves legal evidence and runs LLM reasoning, calibrates confidence, and returns an audit result. The graph preserves the documented operating modes and optional Gemma capability. Relationships are limited to calls visible in excerpts or the source index; several documented capabilities have no sampled implementation details.

Main entry points: [`pipeline/orchestrator.py`](https://github.com/pushpak1203/vat/blob/main/pipeline/orchestrator.py) (Audit orchestrator), [`pipeline/vat_rules_engine.py`](https://github.com/pushpak1203/vat/blob/main/pipeline/vat_rules_engine.py) (Rules engine), [`rag/retriever.py`](https://github.com/pushpak1203/vat/blob/main/rag/retriever.py) (Legal retriever), [`main.py`](https://github.com/pushpak1203/vat/blob/main/main.py) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and orchestration"]
  node_cli["CLI entry<br/>[main.py]"]
  node_orchestrator["Audit orchestrator<br/>[orchestrator.py]"]
  node_input_schema["Transaction schema<br/>[schema.py]"]
end

subgraph group_analysis["Transaction analysis"]
  node_ocr["Invoice extraction<br/>[ocr_extraction.py]"]
  node_layoutlm["LayoutLM extractor"]
  node_classifier["Transaction classifier"]
  node_deberta["DeBERTa classifier"]
  node_risk["Risk scoring<br/>[risk_scoring.py]"]
  node_lightgbm["LightGBM model<br/>[lightgbm_model.py]"]
  node_anomaly["Anomaly detection"]
end

subgraph group_rules["VAT rules"]
  node_rules_engine["Rules engine"]
  node_eu_rules["EU VAT rules<br/>[eu_vat_rules.py]"]
  node_uk_rules["UK VAT rules<br/>[uk_vat_rules.py]"]
  node_oss["OSS/IOSS handling"]
  node_exemptions["VAT exemptions<br/>[exemptions.py]"]
end

subgraph group_evidence["Legal evidence"]
  node_legal_facade["Legal RAG facade<br/>[legal_rag.py]"]
  node_retriever["Legal retriever<br/>[retriever.py]"]
  node_embedder["Legal embedder<br/>[embedder.py]"]
  node_vector_store[("Vector store<br/>[vector_store.py]")]
  node_reranker["Evidence reranker<br/>[reranker.py]"]
end

subgraph group_reasoning["Reasoning and results"]
  node_reasoner["LLM reasoning<br/>[llm_reasoning.py]"]
  node_model_loader["Model loader<br/>[model_loader.py]"]
  node_gemma["Optional Gemma<br/>[gemma_optional.py]"]
  node_calibrator["Confidence calibration"]
  node_result["Audit result<br/>[schema.py]"]
end

node_user(("Auditor"))

node_user -->|"supplies input"| node_cli
node_cli -->|"runs audit"| node_orchestrator
node_orchestrator -->|"validates input"| node_input_schema
node_orchestrator -->|"extracts invoices"| node_ocr
node_ocr -->|"uses layout model"| node_layoutlm
node_orchestrator -->|"classifies transaction"| node_classifier
node_classifier -->|"delegates classification"| node_deberta
node_orchestrator -->|"detects anomalies"| node_anomaly
node_orchestrator -->|"scores risk"| node_risk
node_risk -->|"uses model"| node_lightgbm
node_orchestrator -->|"evaluates rules"| node_rules_engine
node_rules_engine -->|"checks scheme"| node_oss
node_rules_engine -->|"checks exemption"| node_exemptions
node_rules_engine -->|"routes UK cases"| node_uk_rules
node_rules_engine -->|"routes other cases"| node_eu_rules
node_orchestrator -->|"requests evidence"| node_legal_facade
node_legal_facade -->|"delegates retrieval"| node_retriever
node_retriever -->|"embeds query"| node_embedder
node_retriever -->|"searches vectors"| node_vector_store
node_retriever -->|"reranks candidates"| node_reranker
node_orchestrator -->|"requests reasoning"| node_reasoner
node_reasoner -->|"loads language model"| node_model_loader
node_orchestrator -->|"calibrates confidence"| node_calibrator
node_orchestrator -->|"builds audit result"| node_result
node_model_loader -.->|"optional integration"| node_gemma

click node_cli "https://github.com/pushpak1203/vat/blob/main/main.py"
click node_orchestrator "https://github.com/pushpak1203/vat/blob/main/pipeline/orchestrator.py"
click node_input_schema "https://github.com/pushpak1203/vat/blob/main/utils/schema.py"
click node_ocr "https://github.com/pushpak1203/vat/blob/main/pipeline/ocr_extraction.py"
click node_layoutlm "https://github.com/pushpak1203/vat/blob/main/models/layoutlmv3_extractor.py"
click node_classifier "https://github.com/pushpak1203/vat/blob/main/pipeline/transaction_classifier.py"
click node_deberta "https://github.com/pushpak1203/vat/blob/main/models/deberta_classifier.py"
click node_risk "https://github.com/pushpak1203/vat/blob/main/pipeline/risk_scoring.py"
click node_lightgbm "https://github.com/pushpak1203/vat/blob/main/models/lightgbm_model.py"
click node_anomaly "https://github.com/pushpak1203/vat/blob/main/pipeline/anomaly_detection.py"
click node_rules_engine "https://github.com/pushpak1203/vat/blob/main/pipeline/vat_rules_engine.py"
click node_eu_rules "https://github.com/pushpak1203/vat/blob/main/vat_rules/eu_vat_rules.py"
click node_uk_rules "https://github.com/pushpak1203/vat/blob/main/vat_rules/uk_vat_rules.py"
click node_oss "https://github.com/pushpak1203/vat/blob/main/vat_rules/oss_ioss_handler.py"
click node_exemptions "https://github.com/pushpak1203/vat/blob/main/vat_rules/exemptions.py"
click node_legal_facade "https://github.com/pushpak1203/vat/blob/main/pipeline/legal_rag.py"
click node_retriever "https://github.com/pushpak1203/vat/blob/main/rag/retriever.py"
click node_embedder "https://github.com/pushpak1203/vat/blob/main/rag/embedder.py"
click node_vector_store "https://github.com/pushpak1203/vat/blob/main/rag/vector_store.py"
click node_reranker "https://github.com/pushpak1203/vat/blob/main/rag/reranker.py"
click node_reasoner "https://github.com/pushpak1203/vat/blob/main/pipeline/llm_reasoning.py"
click node_model_loader "https://github.com/pushpak1203/vat/blob/main/models/model_loader.py"
click node_gemma "https://github.com/pushpak1203/vat/blob/main/models/gemma_optional.py"
click node_calibrator "https://github.com/pushpak1203/vat/blob/main/pipeline/confidence_calibration.py"
click node_result "https://github.com/pushpak1203/vat/blob/main/utils/schema.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_cli,node_orchestrator,node_input_schema toneBlue
class node_ocr,node_layoutlm,node_classifier,node_deberta,node_risk,node_lightgbm,node_anomaly toneAmber
class node_rules_engine,node_eu_rules,node_uk_rules,node_oss,node_exemptions toneMint
class node_legal_facade,node_retriever,node_embedder,node_vector_store,node_reranker toneRose
class node_reasoner,node_model_loader,node_gemma,node_calibrator,node_result,node_user toneIndigo
```

## Components

### CLI and orchestration

- [CLI entry](https://github.com/pushpak1203/vat/blob/main/main.py): `main.py`
- [Audit orchestrator](https://github.com/pushpak1203/vat/blob/main/pipeline/orchestrator.py): `pipeline/orchestrator.py`
- [Transaction schema](https://github.com/pushpak1203/vat/blob/main/utils/schema.py): `utils/schema.py`

### Transaction analysis

- [Invoice extraction](https://github.com/pushpak1203/vat/blob/main/pipeline/ocr_extraction.py): `pipeline/ocr_extraction.py`
- [LayoutLM extractor](https://github.com/pushpak1203/vat/blob/main/models/layoutlmv3_extractor.py): `models/layoutlmv3_extractor.py`
- [Transaction classifier](https://github.com/pushpak1203/vat/blob/main/pipeline/transaction_classifier.py): `pipeline/transaction_classifier.py`
- [DeBERTa classifier](https://github.com/pushpak1203/vat/blob/main/models/deberta_classifier.py): `models/deberta_classifier.py`
- [Risk scoring](https://github.com/pushpak1203/vat/blob/main/pipeline/risk_scoring.py): `pipeline/risk_scoring.py`
- [LightGBM model](https://github.com/pushpak1203/vat/blob/main/models/lightgbm_model.py): `models/lightgbm_model.py`
- [Anomaly detection](https://github.com/pushpak1203/vat/blob/main/pipeline/anomaly_detection.py): `pipeline/anomaly_detection.py`

### VAT rules

- [Rules engine](https://github.com/pushpak1203/vat/blob/main/pipeline/vat_rules_engine.py): `pipeline/vat_rules_engine.py`
- [EU VAT rules](https://github.com/pushpak1203/vat/blob/main/vat_rules/eu_vat_rules.py): `vat_rules/eu_vat_rules.py`
- [UK VAT rules](https://github.com/pushpak1203/vat/blob/main/vat_rules/uk_vat_rules.py): `vat_rules/uk_vat_rules.py`
- [OSS/IOSS handling](https://github.com/pushpak1203/vat/blob/main/vat_rules/oss_ioss_handler.py): `vat_rules/oss_ioss_handler.py`
- [VAT exemptions](https://github.com/pushpak1203/vat/blob/main/vat_rules/exemptions.py): `vat_rules/exemptions.py`

### Legal evidence

- [Legal RAG facade](https://github.com/pushpak1203/vat/blob/main/pipeline/legal_rag.py): `pipeline/legal_rag.py`
- [Legal retriever](https://github.com/pushpak1203/vat/blob/main/rag/retriever.py): `rag/retriever.py`
- [Legal embedder](https://github.com/pushpak1203/vat/blob/main/rag/embedder.py): `rag/embedder.py`
- [Vector store](https://github.com/pushpak1203/vat/blob/main/rag/vector_store.py): `rag/vector_store.py`
- [Evidence reranker](https://github.com/pushpak1203/vat/blob/main/rag/reranker.py): `rag/reranker.py`

### Reasoning and results

- [LLM reasoning](https://github.com/pushpak1203/vat/blob/main/pipeline/llm_reasoning.py): `pipeline/llm_reasoning.py`
- [Model loader](https://github.com/pushpak1203/vat/blob/main/models/model_loader.py): `models/model_loader.py`
- [Optional Gemma](https://github.com/pushpak1203/vat/blob/main/models/gemma_optional.py): `models/gemma_optional.py`
- [Confidence calibration](https://github.com/pushpak1203/vat/blob/main/pipeline/confidence_calibration.py): `pipeline/confidence_calibration.py`
- [Audit result](https://github.com/pushpak1203/vat/blob/main/utils/schema.py): `utils/schema.py`

### Other components

- **Auditor**

## Connections

- Auditor → CLI entry: supplies input (evidence: `README.md`)
- CLI entry → Audit orchestrator: runs audit (evidence: `main.py`)
- Audit orchestrator → Transaction schema: validates input (evidence: `pipeline/orchestrator.py`)
- Audit orchestrator → Invoice extraction: extracts invoices (evidence: `pipeline/orchestrator.py`)
- Invoice extraction → LayoutLM extractor: uses layout model (evidence: `pipeline/ocr_extraction.py`)
- Audit orchestrator → Transaction classifier: classifies transaction (evidence: `pipeline/orchestrator.py`)
- Transaction classifier → DeBERTa classifier: delegates classification (evidence: `pipeline/transaction_classifier.py`)
- Audit orchestrator → Anomaly detection: detects anomalies (evidence: `pipeline/orchestrator.py`)
- Audit orchestrator → Risk scoring: scores risk (evidence: `pipeline/orchestrator.py`)
- Risk scoring → LightGBM model: uses model (evidence: `pipeline/risk_scoring.py`)
- Audit orchestrator → Rules engine: evaluates rules (evidence: `pipeline/orchestrator.py`)
- Rules engine → OSS/IOSS handling: checks scheme (evidence: `pipeline/vat_rules_engine.py`)
- Rules engine → VAT exemptions: checks exemption (evidence: `pipeline/vat_rules_engine.py`)
- Rules engine → UK VAT rules: routes UK cases (evidence: `pipeline/vat_rules_engine.py`)
- Rules engine → EU VAT rules: routes other cases (evidence: `pipeline/vat_rules_engine.py`)
- Audit orchestrator → Legal RAG facade: requests evidence (evidence: `pipeline/orchestrator.py`)
- Legal RAG facade → Legal retriever: delegates retrieval (evidence: `pipeline/legal_rag.py`)
- Legal retriever → Legal embedder: embeds query (evidence: `rag/retriever.py`)
- Legal retriever → Vector store: searches vectors (evidence: `rag/retriever.py`)
- Legal retriever → Evidence reranker: reranks candidates (evidence: `rag/retriever.py`)
- Audit orchestrator → LLM reasoning: requests reasoning (evidence: `pipeline/orchestrator.py`)
- LLM reasoning → Model loader: loads language model (evidence: `pipeline/llm_reasoning.py`)
- Audit orchestrator → Confidence calibration: calibrates confidence (evidence: `pipeline/orchestrator.py`)
- Audit orchestrator → Audit result: builds audit result (evidence: `pipeline/orchestrator.py`)
- Model loader → Optional Gemma: optional integration (evidence: `models/gemma_optional.py`)
