# vizbapu/spendsense-ai architecture

> Architecture diagram of the GitHub repository vizbapu/spendsense-ai, 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/vizbapu/spendsense-ai
- Repository: https://github.com/vizbapu/spendsense-ai

## Overview

SpendSense is an early-stage bank-statement categorizer and anomaly detector, but the sampled runtime currently implements CSV upload and transaction persistence, health checks, and a synthetic-data generator. The frontend is still the default Vite/React starter screen; no browser-to-API integration or categorization/anomaly runtime is shown. The Ollama integration is currently a health check, not a categorization call. Edges below reflect the sampled calls and README; unsampled planned capabilities are not represented as working components.

Main entry points: [`backend/app/api/uploads.py`](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/api/uploads.py) (Upload endpoints), [`backend/app/api/health.py`](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/api/health.py) (Health endpoint), [`backend/app/services/ingest.py`](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/services/ingest.py) (Transaction ingest), [`backend/app/db/session.py`](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/db/session.py) (DB sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_web_entry["React entry<br/>[main.tsx]"]
  node_web_app["Starter screen<br/>[App.tsx]"]
end

subgraph group_api["API"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_upload_api["Upload endpoints<br/>[uploads.py]"]
  node_health_api["Health endpoint<br/>[health.py]"]
end

subgraph group_ingestion["Statement ingestion"]
  node_csv_parser["CSV validation<br/>[csv_formats.py]"]
  node_ingest["Transaction ingest<br/>[ingest.py]"]
  node_normalizer["Merchant normalizer<br/>[normalizer.py]"]
  node_generator["Synthetic data generator<br/>[generate_data.py]"]
end

subgraph group_storage["Persistence"]
  node_db_session["DB sessions<br/>[session.py]"]
  node_db_models["Upload and transaction models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_operations["Operations"]
  node_config["Settings<br/>[config.py]"]
  node_ollama["Ollama service"]
end

node_user(("User"))

node_web_entry -->|"renders"| node_web_app
node_user -->|"uploads CSV"| node_upload_api
node_api_app -->|"registers"| node_health_api
node_api_app -->|"registers"| node_upload_api
node_upload_api -->|"parses CSV"| node_csv_parser
node_upload_api -->|"saves rows"| node_ingest
node_upload_api -->|"requests session"| node_db_session
node_upload_api -->|"loads upload"| node_db_models
node_ingest -->|"normalizes merchants"| node_normalizer
node_ingest -->|"creates records"| node_db_models
node_db_session -->|"reads database URL"| node_config
node_db_session -.->|"connects"| node_postgres
node_ingest -.->|"writes transactions"| node_postgres
node_health_api -->|"checks database"| node_db_session
node_health_api -->|"reads settings"| node_config
node_health_api -->|"checks availability"| node_ollama

click node_web_entry "https://github.com/vizbapu/spendsense-ai/blob/main/frontend/src/main.tsx"
click node_web_app "https://github.com/vizbapu/spendsense-ai/blob/main/frontend/src/App.tsx"
click node_api_app "https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/main.py"
click node_upload_api "https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/api/uploads.py"
click node_health_api "https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/api/health.py"
click node_csv_parser "https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/services/csv_formats.py"
click node_ingest "https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/services/ingest.py"
click node_normalizer "https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/services/normalizer.py"
click node_generator "https://github.com/vizbapu/spendsense-ai/blob/main/backend/scripts/generate_data.py"
click node_db_session "https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/db/session.py"
click node_db_models "https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/db/models.py"
click node_config "https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/config.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_web_entry,node_web_app,node_user toneBlue
class node_api_app,node_upload_api,node_health_api toneAmber
class node_csv_parser,node_ingest,node_normalizer,node_generator toneMint
class node_db_session,node_db_models,node_postgres toneRose
class node_config,node_ollama toneIndigo
```

## Components

### Web client

- [React entry](https://github.com/vizbapu/spendsense-ai/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Starter screen](https://github.com/vizbapu/spendsense-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### API

- [FastAPI app](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Upload endpoints](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/api/uploads.py): `backend/app/api/uploads.py`
- [Health endpoint](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/api/health.py): `backend/app/api/health.py`

### Statement ingestion

- [CSV validation](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/services/csv_formats.py): `backend/app/services/csv_formats.py`
- [Transaction ingest](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/services/ingest.py): `backend/app/services/ingest.py`
- [Merchant normalizer](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/services/normalizer.py): `backend/app/services/normalizer.py`
- [Synthetic data generator](https://github.com/vizbapu/spendsense-ai/blob/main/backend/scripts/generate_data.py): `backend/scripts/generate_data.py`

### Persistence

- [DB sessions](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Upload and transaction models](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- **PostgreSQL**

### Operations

- [Settings](https://github.com/vizbapu/spendsense-ai/blob/main/backend/app/config.py): `backend/app/config.py`
- **Ollama service**

### Other components

- **User**

## Connections

- React entry → Starter screen: renders (evidence: `frontend/src/main.tsx`)
- User → Upload endpoints: uploads CSV (evidence: `backend/app/api/uploads.py`)
- FastAPI app → Health endpoint: registers (evidence: `backend/app/main.py`)
- FastAPI app → Upload endpoints: registers (evidence: `backend/app/main.py`)
- Upload endpoints → CSV validation: parses CSV (evidence: `backend/app/api/uploads.py`)
- Upload endpoints → Transaction ingest: saves rows (evidence: `backend/app/api/uploads.py`)
- Upload endpoints → DB sessions: requests session (evidence: `backend/app/api/uploads.py`)
- Upload endpoints → Upload and transaction models: loads upload (evidence: `backend/app/api/uploads.py`)
- Transaction ingest → Merchant normalizer: normalizes merchants (evidence: `backend/app/services/ingest.py`)
- Transaction ingest → Upload and transaction models: creates records (evidence: `backend/app/services/ingest.py`)
- DB sessions → Settings: reads database URL (evidence: `backend/app/db/session.py`)
- DB sessions → PostgreSQL: connects
- Transaction ingest → PostgreSQL: writes transactions
- Health endpoint → DB sessions: checks database (evidence: `backend/app/api/health.py`)
- Health endpoint → Settings: reads settings (evidence: `backend/app/api/health.py`)
- Health endpoint → Ollama service: checks availability (evidence: `backend/app/api/health.py`)
