FinSmart — AI-Powered Financial Assistant

ระบบผู้ช่วยการเงินอัจฉริยะสำหรับการจัดการรายจ่ายและการวางแผนเป้าหมายทางการเงินส่วนบุคคล

An AI-powered financial management system designed to help Thai users (Gen Z & young families) tackle financial fragility and household debt through automated expense tracking, intelligent analysis, and personalized financial advice.

Live demo: finsmart.kittipoom.dev

---

Features

Feature	Description
OCR Slip Scanning	Upload K-Bank transfer slips (JPEG/PNG) — Gemini Vision extracts amount, date, sender, receiver, memo, and auto-suggests a category
AI Chatbot	Gemini-powered financial advisor with real-time context (spending, goals, budgets)
Auto-Categorization	OCR suggestions use the user's actual categories (system + custom)
Transactions	Full CRUD with filters, pagination, type toggle (income/expense), and source badge (Manual / From Scan)
Budgets	Monthly per-category budgets with progress bars and over-budget alerts
Goals	Savings goals with deadline tracking, priority, contributions history, and daily saving calculator
Analytics	Monthly income/expense trends and category breakdown charts
Bilingual UI	English and Thai (next-intl)
Demo Mode	Shared demo account with sample data — auto-resets daily

---

Tech Stack

Frontend — Next.js 16, TypeScript (strict), Tailwind CSS, next-intl, Lucide icons

Backend — FastAPI (Python 3.12), SQLAlchemy 2 (async), Alembic, Pydantic v2, slowapi

Database — PostgreSQL (Neon serverless)

AI — Google Gemini API (gemini-2.5-flash-lite) for OCR extraction, auto-categorization, and chatbot

Deployment — Vercel (frontend), Railway (backend), Neon (database)

---

Project Structure

.
├── frontend/               # Next.js application
│   ├── app/(auth)/         # Login & register pages
│   ├── app/(main)/         # Page routes (dashboard, transactions, scan, goals, budgets, analytics, chat)
│   ├── components/         # Shared UI components
│   ├── lib/                # API client, types, format utilities, category helpers
│   └── messages/           # i18n strings (en.json, th.json)
├── backend/
│   ├── app/
│   │   ├── api/v1/         # Route handlers (auth, users, transactions, categories, budgets, goals, ocr, chat, analytics)
│   │   ├── models/         # SQLAlchemy models
│   │   ├── schemas/        # Pydantic schemas
│   │   ├── services/       # Business logic
│   │   └── utils/seed.py   # System category + demo data seeding
│   ├── alembic/            # Database migrations
│   └── tests/              # pytest test suite
└── docs/                   # Database schema and other docs

---

Local Development

Prerequisites

• Node.js 18+
• Python 3.12+
• PostgreSQL 15+
• A Google Gemini API key

Backend

cd backend

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL, SECRET_KEY, GEMINI_API_KEY at minimum

# Run migrations
alembic upgrade head

# Start the dev server
uvicorn app.main:app --reload --port 8000

API docs available at http://localhost:8000/docs

Frontend

cd frontend

# Install dependencies
npm install

# Configure environment — create frontend/.env.local
# NEXT_PUBLIC_API_URL=http://localhost:8000

# Start the dev server
npm run dev

App available at http://localhost:3000

---

Environment Variables

Backend (backend/.env)

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string (Neon: include ?sslmode=require)
SECRET_KEY	Yes	JWT signing key — openssl rand -hex 32
GEMINI_API_KEY	Yes	Google Gemini API key (OCR + chatbot)
DEMO_MODE	No	true to enable demo account and auto-seed (default: false)
GEMINI_MODEL	No	Default: gemini-2.5-flash-lite
OCR_RATE_LIMIT	No	Default: 20/day
CHAT_RATE_LIMIT	No	Default: 100/day

Frontend (frontend/.env.local)

Variable	Required	Description
NEXT_PUBLIC_API_URL	Yes	Backend base URL — http://localhost:8000 locally
NEXT_PUBLIC_DEMO_MODE	No	true to show demo banner and demo login button

---

Running Tests

cd backend
pytest

---

Deployment

The project deploys automatically on every push to master:

• Vercel builds and deploys the frontend
• Railway builds the Docker image and deploys the backend (backend/ root directory)
• On deploy, alembic upgrade head runs automatically before the server starts

Required environment variables

Railway (backend): DATABASE_URL, SECRET_KEY, GEMINI_API_KEY, DEMO_MODE

Vercel (frontend): NEXT_PUBLIC_API_URL, NEXT_PUBLIC_DEMO_MODE

---

Out of Scope

• Direct bank API integration
• Investment advice (stocks, funds, crypto)
• Real financial transactions
• Multi-currency (THB only)

---

Security

• All inputs validated via Pydantic (backend) and TypeScript types (frontend)
• JWT access tokens (short-lived, in-memory) + httpOnly refresh token cookies
• No sensitive financial data in logs
• OWASP guidelines followed