InsightLedger

AI-assisted personal finance and budgeting

Local-first personal finance workspace that tracks spending, manages budgets, and surfaces Gemini-powered insights over your live data.

Repository Issue Tracker

Overview

What it solves

Gives individuals a single place to plan budgets, review transactions, and ask natural-language questions about their spending.

Ships with demo data so reviewers can try features instantly without setup.

Guardrails

Input validation, rate limiting, strict CORS, and hardened error handling on the Express API.

JWT auth with per-user data isolation and bcrypt password hashing.

Features

Secure auth and RBAC with JWT, bcrypt hashing, and role-based access.

Full CRUD for income/expense transactions with filters, search, pagination, and CSV export.

Category-level budgets with progress indicators, periods, and overspend highlights.

Custom categories with icons/colors per user and uniqueness enforcement.

Analytics dashboards for income vs expenses, spending by category, and trends.

Gemini-powered insights and chat with suggested questions from live data.

Responsive React SPA with consistent design system and offline-friendly demo data.

Security-first Express backend with validation, rate limits, CORS, and hardened errors.

Tech Stack

Frontend

React 18

TypeScript

react-router-dom

axios

Recharts

React Context

CSS modules

CRA tooling

Backend

Node.js

Express

TypeScript

MongoDB + Mongoose

jsonwebtoken

bcryptjs

express-validator

helmet

express-rate-limit

cors

@google/generative-ai

Tooling

ts-node

nodemon

TypeScript types

React Testing Library

Jest

Architecture

React SPA (frontend/src) renders Home, Transactions, Budgets, Categories, Analytics, and AI Chat. Context handles auth and shared state; API modules talk to Express.

Express API (/api) with Helmet, CORS, JSON parsing, rate limiting, auth middleware, and centralized error handling. Routes grouped by auth, transactions, categories, budgets, analytics.

MongoDB models for users, transactions, categories, budgets with indexes on user/date/category. Aggregation pipelines power analytics endpoints. Gemini integration encapsulated in config/services and used by analytics Q&A and suggested questions.

Flow: React SPA ⇄ Express API ⇄ MongoDB · React SPA ⇄ Express /analytics → Gemini API

Getting Started

Prerequisites & Install

Node.js 14+, MongoDB 4.4+, npm/yarn; optional Gemini API key.

git clone https://github.com/rasikasrimal/InsightLedger.git

cd InsightLedger

cd backend && npm install

cd ../frontend && npm install

Run

# Terminal 1

cd backend

npm run dev

# Terminal 2

cd frontend

npm start

# Frontend: http://localhost:3000 · API: http://localhost:5000

# Production build

cd backend && npm run build && npm start

cd ../frontend && npm run build

# serve frontend/build via static host/CDN

Configuration

Backend (.env)

PORT=5000

NODE_ENV=development

MONGODB_URI=mongodb://localhost:27017/insightledger

JWT_SECRET=your-very-secure-random-string-change-this

FRONTEND_URL=http://localhost:3000

GEMINI_API_KEY=your-gemini-api-key-here

GEMINI_MODEL=gemini-flash-latest

# Optional demo user

# DEMO_EMAIL=demo@example.com

# DEMO_PASSWORD=password123

# DEMO_NAME=Demo User

Frontend (.env)

REACT_APP_API_URL=http://localhost:5000/api

Key config: backend/src/config/database.ts, backend/src/config/gemini.ts, backend/src/middleware/auth.ts, backend/src/middleware/errorHandler.ts.

API / Modules

Auth: POST /api/auth/register, POST /api/auth/login (returns JWT + user).
Transactions: GET/POST/PUT/DELETE /api/transactions with filters and pagination.
Categories: GET/POST/PUT/DELETE /api/categories.
Budgets: GET/POST/PUT/DELETE /api/budgets.
Analytics & AI: GET /api/analytics/dashboard, /spending-by-category, /monthly-trends; POST /api/analytics/ask, /suggestions.
Health: GET /api/health.

Data & Migrations

MongoDB collections for users, transactions, categories, budgets with indexes on user/date/category.

Aggregation pipelines for analytics; schema evolution handled in Mongoose code (no external migration framework).

Demo user auto-created via config; other seed data created via UI/API.

Testing

Frontend: CRA Jest + React Testing Library (tests in frontend/src). Run: npm test inside frontend.

Backend: npm test placeholder today; planned unit + integration coverage for controllers/services.

Manual flows: auth, CRUD for transactions/categories/budgets, analytics screens, AI chat, rate limits, validation messaging.

CI/CD

No workflows committed yet; recommended CI runs backend/frontend builds plus frontend tests on PRs, with lint/type-check jobs.

Deployment options: Render/Heroku/VPS for backend; Netlify/Vercel/static hosting for frontend (serve frontend/build).

Suggested: staging auto-deploy from main, manual approval to production.

Performance & Security

Performance: Aggregation pipelines; indexed queries; focused analytics responses; production build for SPA.

Security: JWT + RBAC; bcrypt password hashing; validation/sanitization; rate limiting; helmet headers; trusted CORS; centralized error handling.

Recommendations: HTTPS, strong secrets, DB auth, logging/monitoring, future caching layer.

Roadmap

Short term

• Backend test suite for critical routes/services.

• UI polish for transaction/budget editing flows.

• PDF or richer export formats for reports.

• More chart types and filters for analytics.

Medium term

• Multiple wallets/accounts.

• Recurring transactions.

• Transaction attachments (receipts).

• Budget templates and goal tracking.

• Proactive AI insights and alerts.

Long term

• React Native companion app.

• Bank integrations for automatic imports.

• Shared/collaborative budgets.

• Comprehensive audit logging and security analytics.

Contributing

Use feature branches; keep controllers thin and push logic into helpers/services.

TypeScript everywhere; explicit interfaces for API payloads/models; mirror validation and error-handling patterns.

Commit style: conventional, descriptive (e.g., feat: add recurring transaction model).

Update docs when behavior or setup changes (API docs, deployment notes).

License & Credits

License: ISC declared in backend package.json; add a root LICENSE for public release if needed.

Credits: React, React Router, CRA, Recharts, Axios, Express, Mongoose, JWT, bcryptjs, Helmet, express-validator, express-rate-limit, Gemini API.