# madhuryapasan/personal-finance-advisor architecture

> Architecture diagram of the GitHub repository madhuryapasan/personal-finance-advisor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/madhuryapasan/personal-finance-advisor
- Repository: https://github.com/madhuryapasan/personal-finance-advisor

## Overview

##### Project Type & Purpose
- This is a full-stack Python application combining a Streamlit UI (app.py, app_pages/, pages/) with a REST API backend (api/main.py using FastAPI/uvicorn).
- It uses Google OAuth for authentication, issues JWTs, and exposes endpoints to categorize expenses, set/track budgets, and plan saving goals.
- NLP/text-classification models live in models/ (expense_income_category & expense_income_type), and there is an offline training pipeline in models/train/.

##### Main Components
A. Frontend (Streamlit)
- Files: app.py, app_pages/tmp.py, pages/*.py
- Responsibilities: Google sign-in, capture user input, display charts/forms, copy JWT from the “expenceCat” page, call backend endpoints.
B. Authentication Service
- controller/helpers/auth.py
- Responsibilities: validate JWTs on each API request, extract user info, reject unauthorized calls.
C. Backend API (FastAPI)
- File: api/main.py
- Endpoints: /health, /predict, /create_goal, /track_goal, /set_budget
- Responsibilities: route incoming HTTP calls, invoke controllers, return JSON responses.
D. Controller Layer
- Directory: controller/helpers/
- budgetTrackerSuggestion.py
- savinggoalplannersummerization.py
- llmTools.py (wrapper around OLLAMA/OpenAI)
- auth.py
- Responsibilities: orchestrate business logic, call the right Agent, handle input/output transformation.
E. Agents
- Directory: agents/
- ExpenseCategorizer.py
- BudgetTracker.py
- SavingGoalPlanner.py
- Responsibilities: implement domain logic (e.g. categorize a transaction, suggest budgets, plan savings), call llmTools or local models as needed.
F. Local ML Models
- Directories under models/expense_income_category and models/expense_income_type
- Format: spaCy textcat models with tokenizer, vocab, model weights/config.
- Responsibilities: classify transaction text into category & type.
G. External LLM Service
- Accessed via llmTools.py (calls OLLAMA or another local LLM endpoint) for budget/saving-goal prompts.
H. Offline Training Pipeline
- Directory: models/train/
- Contains: Jupyter notebook (train.ipynb), CSV dataset, produces/updates the models/ directories.

##### Relationships & Data Flows
1. User → Streamlit UI → Google OAuth → receives JWT.
2. Streamlit UI → HTTP (with “Authorization: Bearer <JWT>”) → FastAPI endpoint.
3. FastAPI → auth helper → validate JWT → route to controller helper.
4. Controller helper → calls appropriate Agent.
- If classification: Agent loads spaCy model from models/… and returns category/type.
- If suggestion/planner: Agent uses llmTools → calls local LLM → processes completion.
5. Agent → returns result → Controller → FastAPI → JSON response → Streamlit UI → user.
6. Offline: Dataset → Train notebook → retrained spaCy models → update models/ folder.

##### Architectural Patterns & Principles
- Layered architecture:
[Presentation: Streamlit] → [API Layer: FastAPI] → [Controller: helpers] → [Domain: Agents] → [Data/AI: Models & LLM]
- Clear separation of concerns (UI vs. auth vs. routing vs. business logic vs. ML inference).
- Stateless REST endpoints with JWT-based auth middleware.
- Extensibility: add new Agents/controllers without touching UI or API router.
- Offline training separated from runtime inference.

##### Technologies & Frameworks
- Python 3.x
- Streamlit (UI)
- FastAPI + Uvicorn (API)
- spaCy textcat (local models)
- OLLAMA or OpenAI (LLM service) via llmTools
- Google-Auth / OAuth2 for user sign-in
- JWT for session management
- Jupyter notebooks for training

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        App["app.py"]:::presentation
        Tmp["app_pages/tmp.py"]:::presentation
        Home["pages/home.py"]:::presentation
        ExpCat["pages/expenceCat.py"]:::presentation
    end

    %% Authentication Service
    subgraph "Authentication Service"
        AuthService["Google OAuth & JWT"]:::auth
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        API["FastAPI Server\napi/main.py\nEndpoints:\n/health, /predict,\n/create_goal,\n/track_goal,\n/set_budget"]:::api
        subgraph "Controller Layer"
            direction TB
            AuthCtrl["auth.py"]:::controller
            BudgetCtrl["budgetTrackerSuggestion.py"]:::controller
            SavingCtrl["savinggoalplannersummerization.py"]:::controller
            LLMTool["llmTools.py"]:::controller
        end
    end

    %% Business Logic
    subgraph "Business Logic (Agents)"
        direction TB
        ExpenseAgent["ExpenseCategorizer.py"]:::business
        BudgetAgent["BudgetTracker.py"]:::business
        SavingAgent["SavingGoalPlanner.py"]:::business
    end

    %% On-Device ML Models
    subgraph "On-Device ML Models"
        direction TB
        CatModel["models/expense_income_category/"]:::ml
        TypeModel["models/expense_income_type/"]:::ml
    end

    %% External LLM Service
    ExternalLLM(("External LLM Service")):::llm

    %% Offline Training Pipeline
    subgraph "Offline Training Pipeline"
        direction TB
        TrainNotebook["models/train/Expense Categorizer/train.ipynb"]:::offline
        Dataset["models/train/Expense Categorizer/expenses_income_dataset.csv"]:::offline
    end

    %% Data Flows
    App -->|"Google OAuth"| AuthService
    AuthService -->|"JWT Token"| App
    App -->|"HTTP/REST + Bearer JWT"| API

    API -->|"middleware validate JWT"| AuthCtrl
    API -->|"POST /predict"| ExpenseAgent
    API -->|"POST /set_budget"| BudgetCtrl
    API -->|"POST /create_goal\n/track_goal"| SavingCtrl

    AuthCtrl -->|passes user info| API

    BudgetCtrl -->|calls| BudgetAgent
    SavingCtrl -->|calls| SavingAgent
    LLMTool -->|invokes| ExternalLLM

    ExpenseAgent -->|textcat inference| CatModel
    ExpenseAgent -->|textcat inference| TypeModel

    BudgetAgent -->|uses llmTools| LLMTool
    SavingAgent -->|uses llmTools| LLMTool

    %% Offline training flow
    TrainNotebook -.->|updates models| CatModel
    TrainNotebook -.->|updates models| TypeModel
    Dataset -.-> TrainNotebook

    %% Click Events
    click App "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/app.py"
    click Tmp "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/app_pages/tmp.py"
    click Home "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/pages/home.py"
    click ExpCat "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/pages/expenceCat.py"
    click AuthCtrl "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/controller/helpers/auth.py"
    click BudgetCtrl "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/controller/helpers/budgetTrackerSuggestion.py"
    click SavingCtrl "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/controller/helpers/savinggoalplannersummerization.py"
    click LLMTool "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/controller/helpers/llmTools.py"
    click API "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/api/main.py"
    click ExpenseAgent "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/agents/ExpenseCategorizer.py"
    click BudgetAgent "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/agents/BudgetTracker.py"
    click SavingAgent "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/agents/SavingGoalPlanner.py"
    click CatModel "https://github.com/madhuryapasan/personal-finance-advisor/tree/main/models/expense_income_category/"
    click TypeModel "https://github.com/madhuryapasan/personal-finance-advisor/tree/main/models/expense_income_type/"
    click TrainNotebook "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/models/train/Expense Categorizer/train.ipynb"
    click Dataset "https://github.com/madhuryapasan/personal-finance-advisor/blob/main/models/train/Expense Categorizer/expenses_income_dataset.csv"

    %% Styles
    classDef presentation fill:#D0E6F8,stroke:#0366d6,color:#0366d6;
    classDef auth fill:#F8D0D0,stroke:#d62728,color:#d62728;
    classDef api fill:#D0F8D0,stroke:#2ca02c,color:#2ca02c;
    classDef controller fill:#E2F8D0,stroke:#98df8a,color:#98df8a;
    classDef business fill:#FBF3C0,stroke:#ff7f0e,color:#ff7f0e;
    classDef ml fill:#F8E0C0,stroke:#ffbb78,color:#ffbb78;
    classDef llm fill:#E7C0F8,stroke:#9467bd,color:#9467bd;
    classDef offline fill:#F0F0F0,stroke:#7f7f7f,color:#7f7f7f;
```
