How madhuryapasan/personal-finance-advisor works
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