# rojasantino/bank_document_classifier architecture

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

- Interactive diagram: https://gitdiagram.com/rojasantino/bank_document_classifier
- Repository: https://github.com/rojasantino/bank_document_classifier

## Overview

This repository is a bank-document classification and cheque-field extraction system. Its main workflow prepares labeled document images, trains and evaluates classifiers, then serves uploaded documents through a REST API or Streamlit dashboard. Classification can be supplemented with Grad-CAM explanations and OCR extraction. The graph includes documented capabilities whose implementation was not fully sampled; edges are limited to README statements and source-index references, so some internal runtime details remain unspecified.

Main entry points: [`config.py`](https://github.com/rojasantino/bank_document_classifier/blob/main/config.py) (Project configuration), [`api/main.py`](https://github.com/rojasantino/bank_document_classifier/blob/main/api/main.py) (REST API), [`src/gradcam.py`](https://github.com/rojasantino/bank_document_classifier/blob/main/src/gradcam.py) (Grad-CAM explanation), [`src/dataset.py`](https://github.com/rojasantino/bank_document_classifier/blob/main/src/dataset.py) (Dataset and splits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_raw[("Raw documents")]
  node_synthetic["Synthetic generator"]
  node_preprocess["Image preprocessing"]
  node_processed[("Processed documents")]
  node_dataset["Dataset and splits<br/>[dataset.py]"]
end

subgraph group_ml["Model lifecycle"]
  node_train["Model training<br/>[train.py]"]
  node_architectures["CNN architectures<br/>[transfer_models.py]"]
  node_customcnn["Custom CNN<br/>[custom_cnn.py]"]
  node_evaluate["Model evaluation<br/>[evaluate.py]"]
end

subgraph group_explain["Inference features"]
  node_gradcam["Grad-CAM explanation<br/>[gradcam.py]"]
  node_ocr["Cheque OCR extraction<br/>[ocr_extraction.py]"]
end

subgraph group_serve["User interfaces"]
  node_api["REST API<br/>[main.py]"]
  node_schemas["Response schemas<br/>[schemas.py]"]
  node_dashboard["Streamlit dashboard<br/>[streamlit_app.py]"]
  node_defaults["API web page<br/>[index.html]"]
end

subgraph group_state["Configuration and artifacts"]
  node_checkpoints[("Model checkpoints")]
  node_reports["Evaluation reports"]
  node_heatmaps[("Grad-CAM images")]
  node_config["Project configuration<br/>[config.py]"]
end

node_user(("Document user"))
node_tesseract["Tesseract OCR"]

node_user -->|"uploads document"| node_api
node_user -->|"selects document"| node_dashboard
node_synthetic -->|"generates images"| node_raw
node_raw -->|"preprocesses"| node_preprocess
node_preprocess -->|"writes images"| node_processed
node_processed -->|"loads preferred data"| node_dataset
node_raw -->|"loads fallback data"| node_dataset
node_dataset -->|"provides batches"| node_train
node_train -->|"builds models"| node_architectures
node_architectures -->|"constructs baseline"| node_customcnn
node_train -->|"saves checkpoints"| node_checkpoints
node_dataset -->|"provides test split"| node_evaluate
node_evaluate -->|"builds models"| node_architectures
node_evaluate -->|"loads checkpoints"| node_checkpoints
node_evaluate -->|"writes metrics"| node_reports
node_api -->|"loads classifier"| node_architectures
node_api -->|"requests explanation"| node_gradcam
node_api -->|"requests extraction"| node_ocr
node_api -->|"formats responses"| node_schemas
node_api -->|"serves page"| node_defaults
node_dashboard -->|"loads classifier"| node_architectures
node_dashboard -->|"runs explanation"| node_gradcam
node_dashboard -.->|"offers extraction"| node_ocr
node_gradcam -->|"builds model"| node_architectures
node_gradcam -->|"uses evaluation transforms"| node_dataset
node_gradcam -->|"loads checkpoint"| node_checkpoints
node_gradcam -->|"writes heatmap"| node_heatmaps
node_ocr -->|"uses image operations"| node_preprocess
node_ocr -->|"recognizes text"| node_tesseract
node_synthetic -->|"reads settings"| node_config
node_preprocess -->|"reads paths"| node_config
node_dataset -->|"reads classes and splits"| node_config
node_train -->|"reads settings"| node_config
node_evaluate -->|"reads settings"| node_config
node_api -->|"reads paths and classes"| node_config
node_dashboard -->|"reads paths and classes"| node_config
node_gradcam -->|"reads paths and classes"| node_config
node_ocr -->|"reads settings"| node_config

click node_raw "https://github.com/rojasantino/bank_document_classifier/tree/main/data/raw"
click node_synthetic "https://github.com/rojasantino/bank_document_classifier/blob/main/data/generate_synthetic_data.py"
click node_preprocess "https://github.com/rojasantino/bank_document_classifier/blob/main/src/data_preprocessing.py"
click node_processed "https://github.com/rojasantino/bank_document_classifier/tree/main/data/processed"
click node_dataset "https://github.com/rojasantino/bank_document_classifier/blob/main/src/dataset.py"
click node_train "https://github.com/rojasantino/bank_document_classifier/blob/main/src/train.py"
click node_architectures "https://github.com/rojasantino/bank_document_classifier/blob/main/src/models/transfer_models.py"
click node_customcnn "https://github.com/rojasantino/bank_document_classifier/blob/main/src/models/custom_cnn.py"
click node_checkpoints "https://github.com/rojasantino/bank_document_classifier/tree/main/outputs/models"
click node_evaluate "https://github.com/rojasantino/bank_document_classifier/blob/main/src/evaluate.py"
click node_reports "https://github.com/rojasantino/bank_document_classifier/tree/main/outputs/reports"
click node_api "https://github.com/rojasantino/bank_document_classifier/blob/main/api/main.py"
click node_schemas "https://github.com/rojasantino/bank_document_classifier/blob/main/api/schemas.py"
click node_dashboard "https://github.com/rojasantino/bank_document_classifier/blob/main/frontend/streamlit_app.py"
click node_gradcam "https://github.com/rojasantino/bank_document_classifier/blob/main/src/gradcam.py"
click node_heatmaps "https://github.com/rojasantino/bank_document_classifier/tree/main/outputs/gradcam"
click node_ocr "https://github.com/rojasantino/bank_document_classifier/blob/main/src/ocr_extraction.py"
click node_config "https://github.com/rojasantino/bank_document_classifier/blob/main/config.py"
click node_defaults "https://github.com/rojasantino/bank_document_classifier/blob/main/frontend/index.html"

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_raw,node_synthetic,node_preprocess,node_processed,node_dataset,node_user toneBlue
class node_train,node_architectures,node_customcnn,node_evaluate toneAmber
class node_gradcam,node_ocr toneMint
class node_api,node_schemas,node_dashboard,node_defaults toneRose
class node_checkpoints,node_reports,node_heatmaps,node_config,node_tesseract toneIndigo
```

## Components

### Data preparation

- [Raw documents](https://github.com/rojasantino/bank_document_classifier/tree/main/data/raw): `data/raw`
- [Synthetic generator](https://github.com/rojasantino/bank_document_classifier/blob/main/data/generate_synthetic_data.py): `data/generate_synthetic_data.py`
- [Image preprocessing](https://github.com/rojasantino/bank_document_classifier/blob/main/src/data_preprocessing.py): `src/data_preprocessing.py`
- [Processed documents](https://github.com/rojasantino/bank_document_classifier/tree/main/data/processed): `data/processed`
- [Dataset and splits](https://github.com/rojasantino/bank_document_classifier/blob/main/src/dataset.py): `src/dataset.py`

### Model lifecycle

- [Model training](https://github.com/rojasantino/bank_document_classifier/blob/main/src/train.py): `src/train.py`
- [CNN architectures](https://github.com/rojasantino/bank_document_classifier/blob/main/src/models/transfer_models.py): `src/models/transfer_models.py`
- [Custom CNN](https://github.com/rojasantino/bank_document_classifier/blob/main/src/models/custom_cnn.py): `src/models/custom_cnn.py`
- [Model evaluation](https://github.com/rojasantino/bank_document_classifier/blob/main/src/evaluate.py): `src/evaluate.py`

### Inference features

- [Grad-CAM explanation](https://github.com/rojasantino/bank_document_classifier/blob/main/src/gradcam.py): `src/gradcam.py`
- [Cheque OCR extraction](https://github.com/rojasantino/bank_document_classifier/blob/main/src/ocr_extraction.py): `src/ocr_extraction.py`

### User interfaces

- [REST API](https://github.com/rojasantino/bank_document_classifier/blob/main/api/main.py): `api/main.py`
- [Response schemas](https://github.com/rojasantino/bank_document_classifier/blob/main/api/schemas.py): `api/schemas.py`
- [Streamlit dashboard](https://github.com/rojasantino/bank_document_classifier/blob/main/frontend/streamlit_app.py): `frontend/streamlit_app.py`
- [API web page](https://github.com/rojasantino/bank_document_classifier/blob/main/frontend/index.html): `frontend/index.html`

### Configuration and artifacts

- [Model checkpoints](https://github.com/rojasantino/bank_document_classifier/tree/main/outputs/models): `outputs/models`
- [Evaluation reports](https://github.com/rojasantino/bank_document_classifier/tree/main/outputs/reports): `outputs/reports`
- [Grad-CAM images](https://github.com/rojasantino/bank_document_classifier/tree/main/outputs/gradcam): `outputs/gradcam`
- [Project configuration](https://github.com/rojasantino/bank_document_classifier/blob/main/config.py): `config.py`

### Other components

- **Document user**
- **Tesseract OCR**

## Connections

- Document user → REST API: uploads document (evidence: `README.md`)
- Document user → Streamlit dashboard: selects document (evidence: `README.md`)
- Synthetic generator → Raw documents: generates images (evidence: `README.md`)
- Raw documents → Image preprocessing: preprocesses (evidence: `README.md`)
- Image preprocessing → Processed documents: writes images (evidence: `README.md`)
- Processed documents → Dataset and splits: loads preferred data (evidence: `src/dataset.py`)
- Raw documents → Dataset and splits: loads fallback data (evidence: `src/dataset.py`)
- Dataset and splits → Model training: provides batches (evidence: `src/train.py`)
- Model training → CNN architectures: builds models (evidence: `src/train.py`)
- CNN architectures → Custom CNN: constructs baseline (evidence: `src/models/transfer_models.py`)
- Model training → Model checkpoints: saves checkpoints (evidence: `README.md`)
- Dataset and splits → Model evaluation: provides test split (evidence: `src/evaluate.py`)
- Model evaluation → CNN architectures: builds models (evidence: `src/evaluate.py`)
- Model evaluation → Model checkpoints: loads checkpoints (evidence: `src/evaluate.py`)
- Model evaluation → Evaluation reports: writes metrics (evidence: `README.md`)
- REST API → CNN architectures: loads classifier (evidence: `api/main.py`)
- REST API → Grad-CAM explanation: requests explanation (evidence: `api/main.py`)
- REST API → Cheque OCR extraction: requests extraction (evidence: `api/main.py`)
- REST API → Response schemas: formats responses (evidence: `api/main.py`)
- REST API → API web page: serves page (evidence: `api/main.py`)
- Streamlit dashboard → CNN architectures: loads classifier (evidence: `frontend/streamlit_app.py`)
- Streamlit dashboard → Grad-CAM explanation: runs explanation (evidence: `frontend/streamlit_app.py`)
- Streamlit dashboard → Cheque OCR extraction: offers extraction (evidence: `frontend/streamlit_app.py`)
- Grad-CAM explanation → CNN architectures: builds model (evidence: `src/gradcam.py`)
- Grad-CAM explanation → Dataset and splits: uses evaluation transforms (evidence: `src/gradcam.py`)
- Grad-CAM explanation → Model checkpoints: loads checkpoint (evidence: `README.md`)
- Grad-CAM explanation → Grad-CAM images: writes heatmap (evidence: `README.md`)
- Cheque OCR extraction → Image preprocessing: uses image operations (evidence: `src/ocr_extraction.py`)
- Cheque OCR extraction → Tesseract OCR: recognizes text (evidence: `README.md`)
- Synthetic generator → Project configuration: reads settings (evidence: `data/generate_synthetic_data.py`)
- Image preprocessing → Project configuration: reads paths (evidence: `src/data_preprocessing.py`)
- Dataset and splits → Project configuration: reads classes and splits (evidence: `src/dataset.py`)
- Model training → Project configuration: reads settings (evidence: `src/train.py`)
- Model evaluation → Project configuration: reads settings (evidence: `src/evaluate.py`)
- REST API → Project configuration: reads paths and classes (evidence: `api/main.py`)
- Streamlit dashboard → Project configuration: reads paths and classes (evidence: `frontend/streamlit_app.py`)
- Grad-CAM explanation → Project configuration: reads paths and classes (evidence: `src/gradcam.py`)
- Cheque OCR extraction → Project configuration: reads settings (evidence: `src/ocr_extraction.py`)
