# k250076-glitch/paisapal architecture

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

- Interactive diagram: https://gitdiagram.com/k250076-glitch/paisapal
- Repository: https://github.com/k250076-glitch/paisapal

## Overview

PaisaPal is a menu-driven expense categorizer and budget planner. A user enters or imports transactions; the app cleans expense text, predicts a category for expenses, accepts corrections, and records the transactions and budgets. It can convert foreign currencies to PKR, report monthly spending and budget status, and produce charts or compare classifiers. The excerpts show the menu orchestrating these capabilities and the main module dependencies. Some menu handlers and analysis/plot calls are omitted from the excerpts, so those links are included only where the README documents them.

Main entry points: [`src/main.py`](https://github.com/k250076-glitch/paisapal/blob/main/src/main.py) (Menu and workflows), [`src/data_io.py`](https://github.com/k250076-glitch/paisapal/blob/main/src/data_io.py) (File I/O and validation), [`src/plots.py`](https://github.com/k250076-glitch/paisapal/blob/main/src/plots.py) (Charts and confusion matrix), [`src/models.py`](https://github.com/k250076-glitch/paisapal/blob/main/src/models.py) (Transactions and ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Console app"]
  node_menu["Menu and workflows<br/>[main.py]"]
  node_file_io["File I/O and validation<br/>[data_io.py]"]
  node_currency_conversion["Currency conversion<br/>[api_client.py]"]
  node_rate_cache[("Exchange-rate cache")]
end

subgraph group_categorization["Categorization"]
  node_text_cleaning["Text cleaning<br/>[text_utils.py]"]
  node_classifier["Category classifier<br/>[classifier.py]"]
  node_training_notes["Training notes"]
  node_corrections["Category corrections"]
end

subgraph group_ledger["Ledger and budgets"]
  node_transaction_models["Transactions and ledger<br/>[models.py]"]
  node_budget["Monthly budgets<br/>[models.py]"]
  node_ledger_files[("Saved ledger and budgets")]
  node_sample_ledger["Sample ledger<br/>[ledger_sample.csv]"]
end

subgraph group_insights["Analysis and charts"]
  node_analysis["Spending analysis<br/>[analysis.py]"]
  node_charts["Charts and confusion matrix<br/>[plots.py]"]
  node_chart_files["Generated charts"]
end

node_user(("User"))
node_rates_service{{"Exchange-rate service"}}

node_user -->|"enters transactions"| node_menu
node_menu -->|"cleans notes"| node_text_cleaning
node_menu -->|"predicts categories"| node_classifier
node_classifier -->|"cleans training notes"| node_text_cleaning
node_menu -->|"creates transactions"| node_transaction_models
node_menu -->|"sets and checks"| node_budget
node_menu -->|"loads and saves"| node_file_io
node_file_io -->|"reads and writes"| node_ledger_files
node_file_io -->|"loads initially"| node_sample_ledger
node_file_io -->|"loads labels"| node_training_notes
node_file_io -->|"loads saved corrections"| node_corrections
node_menu -->|"converts foreign expenses"| node_currency_conversion
node_currency_conversion -->|"fetches rates"| node_rates_service
node_currency_conversion -->|"reads and writes cache"| node_rate_cache
node_menu -->|"summarizes spending"| node_analysis
node_menu -->|"requests charts"| node_charts
node_charts -->|"saves charts"| node_chart_files
node_classifier -->|"loads datasets"| node_file_io
node_transaction_models -->|"uses validation"| node_file_io
node_analysis -->|"analyzes records"| node_transaction_models
node_charts -->|"uses monthly data"| node_analysis
node_charts -->|"uses categories"| node_transaction_models

click node_menu "https://github.com/k250076-glitch/paisapal/blob/main/src/main.py"
click node_text_cleaning "https://github.com/k250076-glitch/paisapal/blob/main/src/text_utils.py"
click node_classifier "https://github.com/k250076-glitch/paisapal/blob/main/src/classifier.py"
click node_transaction_models "https://github.com/k250076-glitch/paisapal/blob/main/src/models.py"
click node_budget "https://github.com/k250076-glitch/paisapal/blob/main/src/models.py"
click node_file_io "https://github.com/k250076-glitch/paisapal/blob/main/src/data_io.py"
click node_ledger_files "https://github.com/k250076-glitch/paisapal/tree/main/data/processed"
click node_sample_ledger "https://github.com/k250076-glitch/paisapal/blob/main/data/raw/ledger_sample.csv"
click node_training_notes "https://github.com/k250076-glitch/paisapal/blob/main/data/raw/expenses_labelled.csv"
click node_corrections "https://github.com/k250076-glitch/paisapal/tree/main/data/processed"
click node_currency_conversion "https://github.com/k250076-glitch/paisapal/blob/main/src/api_client.py"
click node_rate_cache "https://github.com/k250076-glitch/paisapal/tree/main/data/processed"
click node_analysis "https://github.com/k250076-glitch/paisapal/blob/main/src/analysis.py"
click node_charts "https://github.com/k250076-glitch/paisapal/blob/main/src/plots.py"
click node_chart_files "https://github.com/k250076-glitch/paisapal/tree/main/outputs/figures"

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_menu,node_file_io,node_currency_conversion,node_rate_cache,node_user toneBlue
class node_text_cleaning,node_classifier,node_training_notes,node_corrections toneAmber
class node_transaction_models,node_budget,node_ledger_files,node_sample_ledger toneMint
class node_analysis,node_charts,node_chart_files toneRose
class node_rates_service toneIndigo
```

## Components

### Console app

- [Menu and workflows](https://github.com/k250076-glitch/paisapal/blob/main/src/main.py): `src/main.py`
- [File I/O and validation](https://github.com/k250076-glitch/paisapal/blob/main/src/data_io.py): `src/data_io.py`
- [Currency conversion](https://github.com/k250076-glitch/paisapal/blob/main/src/api_client.py): `src/api_client.py`
- [Exchange-rate cache](https://github.com/k250076-glitch/paisapal/tree/main/data/processed): `data/processed`

### Categorization

- [Text cleaning](https://github.com/k250076-glitch/paisapal/blob/main/src/text_utils.py): `src/text_utils.py`
- [Category classifier](https://github.com/k250076-glitch/paisapal/blob/main/src/classifier.py): `src/classifier.py`
- [Training notes](https://github.com/k250076-glitch/paisapal/blob/main/data/raw/expenses_labelled.csv): `data/raw/expenses_labelled.csv`
- [Category corrections](https://github.com/k250076-glitch/paisapal/tree/main/data/processed): `data/processed`

### Ledger and budgets

- [Transactions and ledger](https://github.com/k250076-glitch/paisapal/blob/main/src/models.py): `src/models.py`
- [Monthly budgets](https://github.com/k250076-glitch/paisapal/blob/main/src/models.py): `src/models.py`
- [Saved ledger and budgets](https://github.com/k250076-glitch/paisapal/tree/main/data/processed): `data/processed`
- [Sample ledger](https://github.com/k250076-glitch/paisapal/blob/main/data/raw/ledger_sample.csv): `data/raw/ledger_sample.csv`

### Analysis and charts

- [Spending analysis](https://github.com/k250076-glitch/paisapal/blob/main/src/analysis.py): `src/analysis.py`
- [Charts and confusion matrix](https://github.com/k250076-glitch/paisapal/blob/main/src/plots.py): `src/plots.py`
- [Generated charts](https://github.com/k250076-glitch/paisapal/tree/main/outputs/figures): `outputs/figures`

### Other components

- **User**
- **Exchange-rate service**

## Connections

- User → Menu and workflows: enters transactions (evidence: `README.md`)
- Menu and workflows → Text cleaning: cleans notes (evidence: `README.md`)
- Menu and workflows → Category classifier: predicts categories (evidence: `src/main.py`)
- Category classifier → Text cleaning: cleans training notes (evidence: `src/classifier.py`)
- Menu and workflows → Transactions and ledger: creates transactions (evidence: `src/main.py`)
- Menu and workflows → Monthly budgets: sets and checks (evidence: `src/main.py`)
- Menu and workflows → File I/O and validation: loads and saves (evidence: `src/main.py`)
- File I/O and validation → Saved ledger and budgets: reads and writes
- File I/O and validation → Sample ledger: loads initially
- File I/O and validation → Training notes: loads labels (evidence: `src/data_io.py`)
- File I/O and validation → Category corrections: loads saved corrections
- Menu and workflows → Currency conversion: converts foreign expenses (evidence: `src/main.py`)
- Currency conversion → Exchange-rate service: fetches rates (evidence: `src/api_client.py`)
- Currency conversion → Exchange-rate cache: reads and writes cache (evidence: `src/api_client.py`)
- Menu and workflows → Spending analysis: summarizes spending (evidence: `README.md`)
- Menu and workflows → Charts and confusion matrix: requests charts (evidence: `README.md`)
- Charts and confusion matrix → Generated charts: saves charts (evidence: `src/plots.py`)
- Category classifier → File I/O and validation: loads datasets (evidence: `src/classifier.py`)
- Transactions and ledger → File I/O and validation: uses validation (evidence: `src/models.py`)
- Spending analysis → Transactions and ledger: analyzes records (evidence: `src/analysis.py`)
- Charts and confusion matrix → Spending analysis: uses monthly data (evidence: `src/plots.py`)
- Charts and confusion matrix → Transactions and ledger: uses categories (evidence: `src/plots.py`)
