FinSight 💸

AI-powered Personal Finance Platform — membantu nasabah memahami pola pengeluaran mereka lewat AI Financial Coach.

FinSight adalah capstone project DBS Coding Camp 2026. Platform ini menganalisis transaksi nasabah menggunakan beberapa model Machine Learning (deteksi anomali, clustering persona, klasifikasi NLP) lalu menghasilkan laporan keuangan mingguan & bulanan yang dirangkai oleh LLM melalui pipeline RAG.

---

📑 Daftar Isi

• Arsitektur
• Struktur Monorepo
• Tech Stack
• Pipeline Machine Learning
• Alur Scheduler
• Prasyarat
• Setup & Menjalankan
  • 1. NestJS Backend
  • 2. FastAPI Backend
  • 3. React Native Frontend
  • 4. Streamlit Dashboard
  • 5. Notebook Model
• Ringkasan API
• Environment Variables
• Tim

---

🏗 Arsitektur

FinSight memakai arsitektur dua backend dengan pembagian tanggung jawab yang jelas:

                         ┌──────────────────────────┐
                         │   React Native (Expo)     │
                         │   Mobile / Web Frontend   │
                         └────────────┬─────────────┘
                                      │ REST (JWT)
                                      ▼
                         ┌──────────────────────────┐
                         │      NestJS Backend       │   ◄── Backend utama
                         │  Auth · Transactions ·    │       (source of truth)
                         │  Reports · Scheduler/Cron │
                         └──────┬────────────┬───────┘
                  internal key  │            │  TypeORM
                                ▼            ▼
                  ┌──────────────────┐  ┌──────────────────┐
                  │  FastAPI Backend │  │   PostgreSQL DB   │
                  │  ML Orchestration│◄─┤  (shared, async)  │
                  │  (internal only) │  └──────────────────┘
                  └──────────────────┘
                     │  load models
                     ▼
        Autoencoder · K-Means · NLP (TF-IDF) · RAG + LLM

• NestJS = backend utama / source of truth. Memegang autentikasi (JWT), transaksi, laporan, dan menjadwalkan cron job. Hanya NestJS yang menghadap publik.
• FastAPI = ML orchestration layer internal. Tidak menghadap publik — hanya dipanggil NestJS dengan internal key. Memuat seluruh model ML & menjalankan pipeline laporan.
• PostgreSQL = database tunggal yang dibagi keduanya (NestJS via TypeORM, FastAPI via asyncpg read-only).

---

📂 Struktur Monorepo

CAPSTONE/
├── nestjs-backend/        # Backend utama: Auth, Transactions, Reports, Scheduler (NestJS 11 + TypeORM)
├── fastapi-backend/       # ML orchestration layer (FastAPI, VSA + DDD)
├── reactnative-frontend/  # Aplikasi mobile/web (Expo Router + React Native 0.81)
├── notebook-model/        # Notebook training & artefak model (.keras, .pkl)
├── streamlit/             # Dashboard admin untuk eksplorasi clustering
└── .gitignore

---

🛠 Tech Stack

Layer	Teknologi
Frontend	React Native 0.81, Expo 54, Expo Router 6, TypeScript, Axios, expo-secure-store
Backend Utama	NestJS 11, TypeORM 0.3, PostgreSQL, JWT (passport-jwt), bcrypt, Swagger, @nestjs/schedule (cron)
ML Backend	FastAPI, SQLAlchemy + asyncpg, Pydantic v2, Uvicorn
Machine Learning	TensorFlow/Keras (Autoencoder), scikit-learn + UMAP (K-Means), TF-IDF (NLP), OpenRouter/OpenAI-compatible LLM
Dashboard	Streamlit, Plotly, scikit-learn, UMAP
Database	PostgreSQL

---

🤖 Pipeline Machine Learning

Empat komponen ML diorkestrasi oleh FastAPI (semua model di-preload saat startup via preload_all_models()):

1. NLP (TF-IDF + classifier) — mengklasifikasikan transaksi Transfer P2P ke kategori (Needs/Wants) berdasarkan deskripsi. Output: (vectorizer, model).
2. Autoencoder (Keras) — deteksi anomali transaksi. Threshold MAE adaptif per kombinasi (customer_id, sub_category). Preprocessing: One-Hot Encoding sub-kategori, log1p nominal, Z-score per user-kategori, lalu MinMaxScaler.
3. K-Means Clustering — pipeline StandardScaler → UMAP → K-Means untuk menentukan persona nasabah dari 10 fitur behavioral (wants_ratio, fixed_costs_ratio, savings_rate, wants_frequency, small_leaks_ratio, night_owl_spending, weekend_surge, early_month_depletion, balance_volatility, survival_mode_days).
4. RAG + LLM — konteks dirangkai manual dari knowledge base keuangan (ml/knowledge/financial_kb.json) + ringkasan transaksi, lalu dikirim ke LLM (OpenRouter, API OpenAI-compatible) untuk menulis narasi laporan.

Artefak model tersimpan di notebook-model/model/ (autoencoder.keras, kmeans_all_umap.pkl, umap_all.pkl, scaler_all.pkl, nlp_model.pkl, tfidf_vectorizer.pkl, dll). Path-nya dikonfigurasi via env FastAPI.

---

⏰ Alur Scheduler

NestJS menjadwalkan cron, lalu memanggil endpoint internal FastAPI:

• Weekly — POST /scheduler/weekly setiap Senin 06:00 WIB Query 7 hari transaksi → NLP (klasifikasi P2P) → Autoencoder (anomali) → hitung rasio Wants/Needs → RAG + LLM → laporan mingguan.
• Monthly — POST /scheduler/monthly setiap tanggal 1, 00:05 WIB Query 30 hari transaksi → NLP → K-Means (update persona) → hitung savings rate & rasio Wants/Needs → RAG + LLM → laporan bulanan.
• Reset Ratio — NestJS mereset currentNeedsRatio/currentWantsRatio = 0 tepat 00:00 tanggal 1 (sebelum monthly scheduler jalan).

Endpoint scheduler dilindungi internal key (verify_internal_key) dan mendukung dry_run (diblokir di environment production).

---

✅ Prasyarat

• Node.js ≥ 20 dan pnpm (frontend) / npm (nestjs)
• Python ≥ 3.13 — direkomendasikan uv (FastAPI memakai pyproject.toml + uv.lock)
• PostgreSQL ≥ 14 (database bersama)
• Expo CLI (otomatis via npx expo)
• API key LLM (OpenRouter) untuk pipeline RAG

---

🚀 Setup & Menjalankan

Clone repo:

git clone https://github.com/FinSight-DBS/Finsight.git
cd Finsight

Tiap komponen punya .env sendiri. Salin dari .env.example lalu sesuaikan. Jangan commit .env — sudah di-ignore.

1. NestJS Backend (backend utama)

cd nestjs-backend
cp .env.example .env          # isi DB, JWT_SECRET, FASTAPI_URL, FASTAPI_INTERNAL_KEY
npm install
npm run migration:run         # apply skema database
npm run seed                  # (opsional) isi data awal
npm run start:dev             # http://localhost:3000  ·  Swagger: /api/docs

Script berguna: npm run migrate:fresh:seed (drop → migrate → seed), npm run test, npm run lint.

2. FastAPI Backend (ML orchestration)

cd fastapi-backend
cp .env.example .env          # isi DB, path model, LLM_API_KEY, INTERNAL_API_KEY

# dengan uv (disarankan)
uv sync
uv run python main.py         # http://localhost:8000  ·  docs: /docs

# atau dengan pip
pip install -r requirements.txt
python main.py

Pastikan path model di .env menunjuk ke artefak yang ada (mis. dari notebook-model/model/). Model di-preload saat startup.

3. React Native Frontend

cd reactnative-frontend
cp .env.example .env 2>/dev/null || true   # set EXPO_PUBLIC_API_URL ke URL NestJS
pnpm install
pnpm start                    # tekan: a (Android) · i (iOS) · w (web)

Script lain: pnpm android, pnpm ios, pnpm start:clear, pnpm typecheck, pnpm lint.

4. Streamlit Dashboard (admin)

cd streamlit
pip install streamlit pandas numpy plotly scikit-learn umap-learn scipy
streamlit run dashboard.py    # http://localhost:8501

5. Notebook Model (training)

Notebook training ada di notebook-model/code/ (auto-encoder/, clustering/, nlp/, data-generator/). Jalankan dengan Jupyter/VS Code untuk melatih ulang model; output disimpan ke notebook-model/model/.

---

🔌 Ringkasan API

Base URL NestJS: http://localhost:3000 · Dokumentasi interaktif: GET /api/docs (Swagger).

Auth

Method	Endpoint	Keterangan
POST	/auth/register	Registrasi → { token }
POST	/auth/login	Login → { token }
GET	/auth/profile	Profil user (income, savingsGoal, persona, rasio)
POST	/auth/logout	Logout (invalidasi active token)

Transactions

Method	Endpoint	Keterangan
POST	/transactions	Buat transaksi
GET	/transactions/customer/:customerId?limit	Daftar transaksi nasabah
GET	/transactions/:id	Detail transaksi

Users

Method	Endpoint	Keterangan
PATCH	/users/:id	Update profil user

Reports

Method	Endpoint	Keterangan
GET	/reports/weekly/:customerId	List laporan mingguan
GET	/reports/weekly/:customerId/:reportId	Detail mingguan ({ report, anomalies })
GET	/reports/monthly/:customerId	List laporan bulanan
GET	/reports/monthly/:customerId/:reportId	Detail bulanan
POST	/reports/trigger-weekly/:customerId	Trigger manual laporan mingguan
POST	/reports/trigger-monthly/:customerId	Trigger manual laporan bulanan

FastAPI (internal — butuh internal key)

Method	Endpoint	Keterangan
POST	/scheduler/weekly	Jalankan pipeline mingguan
POST	/scheduler/monthly	Jalankan pipeline bulanan

Frontend menurunkan balance, analitik kategori, dan notifikasi dari data transaksi + laporan (tidak ada endpoint khusus untuk itu). Lihat reactnative-frontend/services/analytics.ts.

---

🔐 Environment Variables

nestjs-backend/.env

NODE_ENV=development
PORT=3000
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=finsight_db
DB_SSL=false
JWT_SECRET=ganti-dengan-secret-yang-kuat
JWT_EXPIRES_IN=7d
FASTAPI_URL=http://localhost:8000
FASTAPI_INTERNAL_KEY=dev-internal-key

fastapi-backend/.env

APP_ENV=production
PORT=8000
DB_HOST=localhost
DB_PORT=5432
DB_NAME=finsight_db
DB_USER=finsight_user
DB_PASSWORD=<password_rahasia>
AUTOENCODER_MODEL_PATH=/app/model/autoencoder/autoencoder.keras
KMEANS_MODEL_PATH=/app/model/clustering/kmeans_all_umap.pkl
KMEANS_LABEL_MAP_PATH=/app/model/clustering/label_map.json
NLP_MODEL_PATH=/app/model/nlp/nlp_model.pkl
NLP_TOKENIZER_PATH=/app/model/nlp/tfidf_vectorizer.pkl
LLM_API_URL=https://openrouter.ai/api/v1
LLM_API_KEY=<your-openrouter-key>
LLM_MODEL=minimax/minimax-m2.5:free
INTERNAL_API_KEY=<secret_internal_key>

reactnative-frontend/.env

EXPO_PUBLIC_API_URL=http://localhost:3000

---

👥 Tim

Capstone Project — DBS Coding Camp 2026 · Tim FinSight-DBS.

---

Built with ❤️ for DBS Coding Camp 2026