# spacedust10/finance-analyser-using-local-llms architecture

> Architecture diagram of the GitHub repository spacedust10/finance-analyser-using-local-llms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spacedust10/finance-analyser-using-local-llms
- Repository: https://github.com/spacedust10/finance-analyser-using-local-llms

## Overview

##### Project type and purpose
- This is a single-machine, data-driven analytics tool with a GUI (Streamlit app) for on-device personal financial analysis.
- It ingests user CSVs, processes and classifies transactions via a local LLM (Ollama’s Llama3.1), computes metrics, and renders interactive visualizations, all without any external cloud dependency.

##### File structure
- Top-level Python modules:
- app.py          → the Streamlit entrypoint (UI layer)
- file_processor.py → CSV ingestion & cleaning
- transaction_classifier.py → LLM invocation & category assignment
- financial_metrics.py → calculation of income/expense/saving rates
- visualization.py → chart building (Plotly/Streamlit)
- finance_dashboard.py → UI layout & components orchestration
- requirements.txt holds your Python/LLM/visualization dependencies.
- No separate “backend” or “frontend” folders—this is a single-runtime application.

##### Key README insights
- Local LLM integration: all inference via Ollama API, model pulled on-device
- Streamlit GUI: handles file upload, real-time display, user interactions

a. Main components
1. Streamlit UI (app.py + finance_dashboard.py)
2. File Processor (file_processor.py)
3. LLM Classification Service (transaction_classifier.py calls Ollama Llama3.1)
4. Metrics Engine (financial_metrics.py)
5. Visualization Module (visualization.py + Plotly)
6. Local Data Store (in-memory DataFrame objects; optionally temp CSV)
b. Relationships & data flow
- User uploads CSV → Streamlit UI passes file to File Processor
- File Processor emits cleaned DataFrame → handed to Classification Service
- Classification Service labels transactions → enriched DataFrame
- Enriched data flows into Metrics Engine → computes aggregates/trends
- Results passed to Visualization Module → charts rendered back in UI
- Throughout, Local Data Store persists intermediate datasets in memory
c. Architectural patterns & design principles
- Pipeline pattern: sequential transformation steps
- Single-process modular design: clear separation of concerns by Python module
- On-device compute & privacy-by-design (no external data transfer)
d. Key technologies/frameworks
- Streamlit for UI & user interaction
- Pandas for in-memory data manipulation
- Ollama LLM API (llama3.1) for transaction classification
- Plotly for interactive visualizations

##### Detail
- Functions or classes inside each module if space allows
- Optional: add usage scenario notes (e.g., “Step 2: LLM categorization may take 2–3s per 1000 rows”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "On-Device Boundary"
        style On-Device Boundary stroke-dasharray: 5 5
        U["User CSV Upload"]:::input
        UIApp["Streamlit UI<br/>(app.py,<br/>finance_dashboard.py)"]:::ui
        FileProc["File Processor<br/>(file_processor.py)"]:::processing
        Classifier["LLM Classification Service<br/>(transaction_classifier.py)"]:::processing
        Llama["Ollama LLM Service<br/>(Llama3.1)"]:::llm
        Metrics["Metrics Engine<br/>(financial_metrics.py)"]:::processing
        Viz["Visualization Module<br/>(visualization.py)"]:::processing
        DataStore["In-Memory Data Store"]:::store
    end

    U -->|"Raw CSV"| FileProc
    FileProc -->|"Cleaned DataFrame"| DataStore
    DataStore --> Classifier
    Classifier -->|"LLM Inference Request"| Llama
    Llama -->|"LLM Response"| Classifier
    Classifier -->|"Labeled DataFrame"| DataStore
    DataStore --> Metrics
    Metrics -->|"Metrics JSON"| DataStore
    DataStore --> Viz
    Viz -->|"Plotly Figures"| UIApp
    UIApp --> U

    ext1["requirements.txt"]:::docs
    ext2["README.md"]:::docs
    ext1 -.-> UIApp
    ext2 -.-> FileProc

    click UIApp "https://github.com/spacedust10/finance-analyser-using-local-llms/blob/master/app.py"
    click UIApp "https://github.com/spacedust10/finance-analyser-using-local-llms/blob/master/finance_dashboard.py"
    click FileProc "https://github.com/spacedust10/finance-analyser-using-local-llms/blob/master/file_processor.py"
    click Classifier "https://github.com/spacedust10/finance-analyser-using-local-llms/blob/master/transaction_classifier.py"
    click Metrics "https://github.com/spacedust10/finance-analyser-using-local-llms/blob/master/financial_metrics.py"
    click Viz "https://github.com/spacedust10/finance-analyser-using-local-llms/blob/master/visualization.py"
    click ext1 "https://github.com/spacedust10/finance-analyser-using-local-llms/blob/master/requirements.txt"
    click ext2 "https://github.com/spacedust10/finance-analyser-using-local-llms/blob/master/README.md"

    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#000,stroke-width:1px
    classDef llm fill:#FFA500,stroke:#000,stroke-width:1px
    classDef store fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef input fill:#E0FFFF,stroke:#000,stroke-width:1px
    classDef docs fill:#F5F5DC,stroke:#000,stroke-width:1px
```
