Milestone Showcase & Scaffolding Architecture
A foundational project showcasing full-stack integration, behavioural finance engineering, and AI coaching architectures.
Traditional financial tracking apps only tell you where your money went; Financial Intelligence uses behavioural science and AI to explain why you spent it and how to reframe your financial habits.
-
Cognitive Bias Detection Engine
- Ingests raw bank statement CSVs and scans transaction patterns for classic behavioural biases:
- Present Bias: Heavy spending immediately following payday vs. late-month deficits.
- Mental Accounting: Treating bonuses, tax refunds, or unexpected credits differently than core salary.
- Loss Aversion: Retaining low-utility subscription services or high-cost recurring plans due to friction or perceived value loss.
- Anchoring: Spending benchmarked against initial high spending thresholds.
- Ingests raw bank statement CSVs and scans transaction patterns for classic behavioural biases:
-
Counterfactual Financial Simulations
- Allows users to model "what-if" scenarios (e.g., "What if I reduce weekend dining by 25% over 6 months?").
- Generates prospective cash flow projections and projected net wealth impacts.
-
Grounded AI Financial Coach (Powered by Gemini)
- Conversational assistant powered by Google Gemini, designed to provide hyper-personalised, non-judgmental guidance grounded directly in the user's detected spending evidence.
-
Prioritised 30-Day Action Plan
- Converts cognitive insights into time-bound, manageable steps with difficulty scoring and estimated monthly savings.
Financial-Intelligence-/
├── backend/ # Python 3.12 + FastAPI Async Backend
│ ├── app/
│ │ ├── ai/ # Gemini AI prompt builders & parser scaffolding
│ │ ├── api/ # FastAPI API router endpoints (V1)
│ │ ├── config/ # Pydantic Settings & SQLite database initialization
│ │ ├── models/ # SQLAlchemy ORM schemas (Sessions, Transactions, Plans)
│ │ ├── processing/ # Ingestion pipeline (CSV parsing, normalization, categorization)
│ │ ├── schemas/ # Pydantic validation models & responses
│ │ └── services/ # Business logic layer & pipeline orchestration
├── frontend/ # Next.js 14 (App Router) + TypeScript
│ ├── app/ # UI Routes (Upload, Snapshot, Behaviours, Savings, Coach, Plan)
│ ├── components/ # Modular React components & charts (Recharts)
│ ├── lib/ # Application constants & environment configurations
│ └── services/ # Axios/Fetch API client layer (`apiClient.ts`)
- Frontend: Next.js 14, React, TypeScript, Tailwind CSS, Recharts
- Backend: Python 3.12, FastAPI, SQLAlchemy, Pydantic v2, Pandas
- AI Integration: Google Gemini SDK (
google-generativeai) - Database: SQLite (Development) / PostgreSQL-ready ORM
- Communication: REST API over HTTP with CORS middleware
This repository stands as an end-to-end connected scaffold demonstrating full system design, API contracts, database modeling, and a polished frontend UI.
- Full End-to-End Connectivity: Frontend (
http://localhost:3000) and Backend (http://localhost:8000) communicate seamlessly via CORS without CORS blockages. - Frontend UI & Navigation: Complete high-fidelity UI built for all pages: Financial Snapshot dashboard, Behaviour list with evidence cards, Savings recommendations, Counterfactual simulator, AI Coach chat interface, and Action Plan.
- Backend API Specs & Validation: Comprehensive Pydantic models and FastAPI endpoint declarations for
/upload,/snapshot,/behaviours,/savings,/simulation,/coach/chat, and/plan. - Database Schemas & Ingestion Scaffolding: SQLAlchemy ORM models configured for
UploadSession,Transaction,DetectedBehaviour, andActionPlanItem. File upload pipeline handles CSV storage and session tracking.
To be implemented in future iterations as this project evolves:
-
Backend Service Logic & Hardcoded Endpoint Responses:
- Current State: Backend endpoints (e.g.
backend/app/api/snapshot.py,behaviours.py,savings.py,coach.py) currently return static dictionary stubs to ensure instant API responsiveness for UI testing. - Roadmap: Complete the implementation in
backend/app/services/(snapshot_service.py,behaviour_service.py) to query SQLite transactions and dynamically calculate income/expense breakdowns and detected bias rules via Pandas.
- Current State: Backend endpoints (e.g.
-
Live Gemini AI Integration:
- Current State:
GeminiClient(backend/app/ai/gemini_client.py) has prompt builders and structured JSON parsers set up, but calls are mocked. - Roadmap: Supply a live
GEMINI_API_KEY, uncomment thegoogle.generativeaiclient initialization, and pipe live transaction evidence into the prompt context for real-time generative coaching.
- Current State:
-
Advanced CSV Parsing:
- Current State: Basic CSV normalization logic is structured in
backend/app/processing/csv_parser.py. - Roadmap: Support flexible column mapping for various global bank statement formats (HDFC, Chase, Monzo, etc.).
- Current State: Basic CSV normalization logic is structured in
- Python: 3.11 or 3.12
- Node.js: v20 or v22 LTS
- npm: Package Manager
cd backend
python -m venv venv
# Windows PowerShell:
.\venv\Scripts\Activate.ps1
# Install dependencies:
pip install -r requirements.txt
# Start FastAPI server:
uvicorn app.main:app --reload --port 8000API Docs available at: http://localhost:8000/docs
cd frontend
npm install
# Ensure .env.local exists with:
# NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
# NEXT_PUBLIC_USE_MOCK=false
npm run devApplication available at: http://localhost:3000
"Every complex system starts as a well-architected scaffold. This repository records the initial vision, system design, and UI/API foundations of an AI-first financial platform — a benchmark to measure future growth and technical progress."