# shivang1244/ai-financial-sms-expenses-tracker-app- architecture

> Architecture diagram of the GitHub repository shivang1244/ai-financial-sms-expenses-tracker-app-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shivang1244/ai-financial-sms-expenses-tracker-app-
- Repository: https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-

## Overview

This repository is the Python backend for an AI financial-SMS expense tracker; the Android client is described in the README but is not present in the tree. The main workflow is Android-submitted SMS and coordinates → transaction filtering → location enrichment and LLM-based field extraction → persistence, with a separate transaction-history API. The graph distinguishes the predictor’s helper layers, MySQL access, and external geocoding/LLM services. Relationships are based on the excerpts and README; unsampled client implementation is not represented.

Main entry points: [`app.py`](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/app.py) (FastAPI endpoints), [`predictor.py`](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/predictor.py) (SMS predictor), [`transaction_repository.py`](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/transaction_repository.py) (Transaction repository), [`geo_utils.py`](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/geo_utils.py) (Reverse geocoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_api["FastAPI endpoints<br/>[app.py]"]
  node_memory[("Memory fallback<br/>[app.py]")]
end

subgraph group_processing["Transaction processing"]
  node_predictor["SMS predictor<br/>[predictor.py]"]
  node_filter["SMS filtering<br/>[utils.py]"]
  node_extractor["LLM extraction<br/>[predictor.py]"]
end

subgraph group_integrations["External enrichment"]
  node_geo["Reverse geocoder<br/>[geo_utils.py]"]
  node_llmclient["LLM request client<br/>[llm_models.py]"]
end

subgraph group_storage["Persistence"]
  node_repository["Transaction repository"]
  node_connector["MySQL connector<br/>[db.py]"]
end

node_android(("Android app"))
node_openrouter["OpenRouter API"]
node_osm["OpenStreetMap geocoder"]
node_mysql[("MySQL database")]

node_android -->|"submits SMS"| node_api
node_api -->|"processes SMS"| node_predictor
node_predictor -->|"checks transaction"| node_filter
node_predictor -->|"geocodes coordinates"| node_geo
node_geo -->|"reverse geocodes"| node_osm
node_predictor -->|"extracts fields"| node_extractor
node_extractor -->|"requests prediction"| node_llmclient
node_llmclient -->|"sends prompt"| node_openrouter
node_api -->|"saves transaction"| node_repository
node_api -->|"fetches history"| node_repository
node_repository -->|"opens connection"| node_connector
node_connector -->|"connects"| node_mysql
node_api -->|"stores fallback"| node_memory
node_api -->|"returns results"| node_android

click node_api "https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/app.py"
click node_memory "https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/app.py"
click node_predictor "https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/predictor.py"
click node_filter "https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/utils.py"
click node_geo "https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/geo_utils.py"
click node_extractor "https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/predictor.py"
click node_llmclient "https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/llm_models.py"
click node_repository "https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/transaction_repository.py"
click node_connector "https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/db.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_memory toneBlue
class node_predictor,node_filter,node_extractor,node_mysql toneAmber
class node_geo,node_llmclient,node_openrouter toneMint
class node_repository,node_connector toneRose
class node_android,node_osm toneIndigo
```

## Components

### API and orchestration

- [FastAPI endpoints](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/app.py): `app.py`
- [Memory fallback](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/app.py): `app.py`

### Transaction processing

- [SMS predictor](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/predictor.py): `predictor.py`
- [SMS filtering](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/utils.py): `utils.py`
- [LLM extraction](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/predictor.py): `predictor.py`

### External enrichment

- [Reverse geocoder](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/geo_utils.py): `geo_utils.py`
- [LLM request client](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/llm_models.py): `llm_models.py`

### Persistence

- [Transaction repository](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/transaction_repository.py): `transaction_repository.py`
- [MySQL connector](https://github.com/shivang1244/ai-financial-sms-expenses-tracker-app-/blob/main/db.py): `db.py`

### Other components

- **Android app**
- **OpenRouter API**
- **OpenStreetMap geocoder**
- **MySQL database**

## Connections

- Android app → FastAPI endpoints: submits SMS (evidence: `README.md`)
- FastAPI endpoints → SMS predictor: processes SMS (evidence: `app.py`)
- SMS predictor → SMS filtering: checks transaction (evidence: `predictor.py`)
- SMS predictor → Reverse geocoder: geocodes coordinates (evidence: `predictor.py`)
- Reverse geocoder → OpenStreetMap geocoder: reverse geocodes (evidence: `geo_utils.py`)
- SMS predictor → LLM extraction: extracts fields (evidence: `predictor.py`)
- LLM extraction → LLM request client: requests prediction (evidence: `predictor.py`)
- LLM request client → OpenRouter API: sends prompt (evidence: `llm_models.py`)
- FastAPI endpoints → Transaction repository: saves transaction (evidence: `app.py`)
- FastAPI endpoints → Transaction repository: fetches history (evidence: `app.py`)
- Transaction repository → MySQL connector: opens connection (evidence: `transaction_repository.py`)
- MySQL connector → MySQL database: connects (evidence: `db.py`)
- FastAPI endpoints → Memory fallback: stores fallback (evidence: `app.py`)
- FastAPI endpoints → Android app: returns results (evidence: `README.md`)