Finchat

FinChat — Detailed Project Description

FinChat is an open-source, full-stack AI financial operating system for individuals and small businesses. It replaces scattered spreadsheets, chat notes, and disconnected apps with one workspace for the full money lifecycle: income, expenses, budgets, savings goals, loans, bills, procurement orders, reminders, notifications, AI/voice entry, and reports.

It is MIT-licensed. Anyone can use, fork, and contribute.

Problem

Personal and small-business money is messy. People track spend in notes, bills in calendars, loans in bank PDFs, and shopping lists in chats. Totals drift because of floating-point errors and copy-paste. Recurring items get missed. Receipts and backups live on one device. Existing expense apps usually stop at “add a transaction and draw a pie chart.” They do not handle partial purchase orders, amortization, shared errand lists, or correct money math end to end.

Solution

FinChat is a typed, modular product:

Server-side money helpers (toCents, sumMoney, rounding) so 0.1 + 0.2 cannot corrupt ledgers.
Separate frontend/ (React 19, Vite, Tailwind CSS v4, PWA) and backend/ (Express, TypeScript, LibSQL/SQLite, Prisma).
Gemini for natural-language and spoken transaction entry; optional ElevenLabs and Google Maps agents.
Local-first storage (IndexedDB, OPFS) plus optional Firebase Auth and Firestore snapshot backup/restore.
JWT + bcrypt, PIN app lock, audit logs, CORS/security headers, rate limits, and Firestore zero-trust rules.

Who it is for

Individuals: daily spend, budgets, bills, goals, voice entry.
Small businesses: orders with partial fulfillment, credits, shared shopping lists, reporting.

What to demo in 3 minutes

Register or sign in (email/password or Google).
Add an expense by form, text, or voice (Ctrl+Shift+V / ⌘+Shift+V).
Set a category budget and show 80% warning / 100% critical alerts.
Create a shopping/procurement order, mark a line as partially available, split the remainder.
Open Reports (overview, cash flow, category, trends) and export PDF or ZIP.

Core modules

Module	What it does
Ledger	Expenses and income with categories, payment methods, notes, receipt images
Budgets	Category caps, live burn-down, 80% / 100% alerts
Goals	Savings milestones, contribution history, progress
Loans	Borrowed/lent, interest, remaining balance, payoff planner, what-if
Bills	Recurring due dates, reminders, one-click mark paid
Orders	Lists, partial quantity, remainder split, time-limited share links (`VIEW_ONLY`, `UPDATE_STATUS`, `ADD_ITEM`)
Reports	Overview, cash flow, category, trends, income/expense; PDF and ZIP export
AI & voice	Gemini parsing; Web Speech dictation; ElevenLabs voice API
Auth & backup	Email/password, Google, JWT sessions, Firestore backup/restore
Security	PIN lock, audit trail, per-user isolation, rate limits, security headers
PWA	Installable, offline-aware caching (API routes are not treated as SPA pages)

Currencies: PKR, USD, EUR, GBP, AED, SAR, INR, plus custom codes.

Architecture (short)

Browser UI → REST /api → validators + services → LibSQL/SQLite.
Optional: Gemini / Maps / ElevenLabs on the server; Firebase Auth + Firestore backups; IndexedDB/OPFS on the client.

Main APIs: /api/auth, /api/expenses, /api/income, /api/budgets, /api/goals, /api/loans, /api/bills, /api/orders, /api/reports, /api/notifications, /api/ai, /api/subscription, plus /health and /ready.

Repo: frontend/ (React SPA), backend/ (Express API, Prisma, tests, uploads). Docs and MIT license at the root.

Stack: React 19, TypeScript, Vite, Tailwind v4, Recharts, Express, Prisma, LibSQL/SQLite, bcryptjs, JWT, Firebase, Google GenAI, Web Speech, ElevenLabs, Google Maps, JSZip, jsPDF.

Why this is more than a CRUD expense app

Correct money — integer-cent style arithmetic on the server; tests for precision, validation, financial smoke, and subscription security.
Full lifecycle — not only expenses: recurring income/expense, budgets, goals, loans, bills, credits, reminders, notifications, subscriptions.
Orders that match real shopping — partial stock, actual vs estimated price, remainder split, tokenized share links for errand runners.
AI that writes structured data — spoken or typed “Paid 1,500 for fuel at Shell” becomes a ledger row, not a chat bubble.
Trust — hashed passwords, JWT, PIN lock, audit logs, ABAC Firestore rules (request.auth.uid == userId), health/readiness probes.

Further improvements (roadmap)

Near term

Finish the frontend/backend split: independent package.json scripts, CORS/API base URL, and a one-command demo.
Automated CI (lint, typecheck, money/validation/smoke tests) on every pull request.
Seeded demo account so reviewers can skip registration.
Stronger accessibility (keyboard, focus, screen readers) and a dedicated mobile layout pass.

Product

Bank/CSV import and smarter category suggestions from history.
Recurring budget rollover and “pay from goal / loan extra payment” flows.
Multi-user households and business roles (owner, accountant, staff) beyond share-link orders.
Real-time notifications (email/push) instead of in-app + scheduler only.
Native-quality PWA: background sync of the offline queue, conflict resolution UI.

Receipt OCR → expense draft with confidence scores.
Monthly “financial briefing” generated from real ledger invariants, not generic tips.
Safer tool-use: AI can propose writes, user confirms before commit.

Platform & security

PostgreSQL/Turso in production; encrypted backups; object storage (S3/GCS) for receipts.
2FA, WebAuthn, and shorter-lived tokens with refresh rotation.
Independent security review of share links, file uploads, and subscription access.
Internationalization (Urdu + English first) and right-to-left layout.

Open source

CONTRIBUTING.md, issue templates, and “good first issue” labels.
Public changelog and tagged releases.
Optional Docker Compose for one-file local demo.

How to run (local)

Requirements: Node.js 18+, npm or bun.

git clone https://github.com/hanzlaonline-cyber/Finchat
cd Finchat
cp .env.example backend/.env
npm install
cd backend && npm install && cd ../frontend && npm install

Minimum .env: PORT=3000, JWT_SECRET (32+ characters), DATABASE_URL=file:./data/expense_tracker.db.
Optional: GEMINI_API_KEY, GOOGLE_CLIENT_ID, GOOGLE_MAPS_API_KEY, ELEVENLABS_API_KEY.

cd backend && npm run dev
cd frontend && npx vite

Health check: http://localhost:3000/health

Do not commit real .env files, uploads/ backups, or local data/ databases.

License and contributing

Contributions are welcome: bugs, features, tests under backend/test/, docs, and security reports (sensitive issues privately). Keep frontend work in frontend/ and backend work in backend/. Small PRs with a clear “why” are preferred.

Extra reading in the repo: README.md, SKILLS.md, backend/.env.example, frontend/firestore.rules.

Hacktoberfest Hack Day Lahore x Fluxxion

Built with

AI tools

Prize Categories Entered