FinMind System Architecture

Detailed structural specification, database schemas, predictive math models, and REST API references for the FinMind PFM Ecosystem.

1. Project Overview

FinMind is an AI-powered personal finance management application that automates receipt logging, extracts structured category items, calculates future spending projections, and processes natural language chatbot queries.

By combining vision-based document processing with vector search indexes and classic forecasting curves, the platform transforms manual, historical expense logging into an automated, predictive financial intelligence tool.

2. Technology Stack

The choice of technologies in FinMind was driven by the need to support unstructured document parsing, vector indexing, and unified serverless API operations.

Technology Role
Next.js 15.5.20Framework
MongoDB AtlasDatabase & Search
Firebase Client SDKAuthentication
NVIDIA NIM CloudAI Inference
Recharts 3.8.1Visualization

* Full justifications visible on larger screens.

3. System Architecture

The following diagram shows the request lifecycle from receipt upload to structured vector storage and RAG-based query answers. 

[Receipt Capture]
   │
   ▼
👤 User Client ---> ⚛ React UI (Canvas Compressor < 200KB)
                     │
                     ▼ (Base64 Form Post)
                  ▲ Next.js Serverless Route
                     │
                     ├─(Vision Image Payload)──> ⚡ NVIDIA NIM (Llama 3.2 Vision OCR)
                     │                                 │
                     │<─(Parsed Structured JSON)───────┘
                     │
                     ├─(Compile Vector Summary)─> ⚡ NVIDIA NIM (nv-embedqa-e5-v5)
                     │                                 │
                     │<─(1024-Dimension Float Array)───┘
                     │
                     ▼
                  🍃 MongoDB Atlas (Saves receipt & indexing vector array)
                        │
                        ▼
                  🔍 Atlas Vector Search (Performs user-scoped RAG searches)
                        │
                        ▼
                  💬 FinAI Chatbot (Runs user queries via Llama 3.1 Instruct)
                        │
                        ▼
                  👤 User Response

4. Workspace Folder Structure

src/
app/
add/ (receipt inputs)
admin/ (user management)
api/ (REST handlers)
components/ (widgets)
lib/
db.js (pool)
financialAnalytics.js
vectorStore.js
models/ (Mongoose schemas)

app/: Next.js App Router folders that define the layout pages and backend REST endpoint API controllers.

components/: Modular React components like the image compressor, budget trackers, and analytics charts.

lib/: Core helper libraries containing statistical math algorithms and the database connection pools.

models/: Database collection schemas and access validation constraints managed through Mongoose.

5. Database Schema & ER Design

MongoDB collections are linked using the user's Firebase UID as the primary lookup reference. 

User Collection
  ├── uid (Primary Key, String matched from Firebase)
  ├── email (String)
  ├── limitType ("restricted" | "unlimited")
  └── customLimit (Number, limits upload operations)
         │
         ├── (1:N Relationship)
         ▼
Receipt Collection
  ├── _id (Object ID)
  ├── user_id (Index Key, references User.uid)
  ├── store { store_name, address }
  ├── transaction { merchant, total, date, time }
  ├── items [ { name, total_price, category: { main, sub } } ]
  ├── summary { tax, discount, grand_total }
  └── vector_embedding (1024-Dimension Float Array)
         │
         ├── (1:N Relationship)
         ▼
Budget Collection
  ├── _id (Object ID)
  ├── userId (Index Key, references User.uid)
  ├── month (String, Format: YYYY-MM)
  ├── category { main }
  └── budget (Number)

6. API Endpoint Directory

Method Endpoint
POST/api/users/sync
POST/api/receipts/analyze
POST/api/receipts
GET/api/receipts/stats
GET/api/ai/signals
POST/api/ai/query

* Usage details visible on larger screens.

POST /api/receipts/analyze

Uploads a receipt image, compresses it, and calls Llama-3.2-Vision to extract structured expense items.

// Request: multipart/form-data
                            image: [File Binary]

                            // Response: 200 OK
                            {
                                "store": { "store_name": "Target" },
                                "transaction": { "date": "2026-07-08", "total": 24.99 },
                                "items": [
                                { "name": "Notebook", "total_price": 4.99, "category": { "main": "Office" } }
                                ]
                            }

POST /api/ai/query

Vectorizes the user's natural language question and performs a pre-filtered similarity query on MongoDB.

// Request: application/json
                            {
                                "query": "How much did I spend on office supplies?",
                                "userId": "firebase_uid_123"
                            }

                            // Response: 200 OK
                            {
                                "response": "You spent a total of $4.99 on office supplies for a Notebook on July 8th."
                            }

7. AI Processing & ML Pipelines

Linear Month-End Forecasts (OLS)

Fits an Ordinary Least Squares (OLS) linear regression model to cumulative daily spending data. Let \(x_i\) = day of month, \(y_i\) = cumulative spend.

\[ \hat{y} = mx + c \]
\[ m = \frac{n \sum (x_i y_i) - \sum x_i \sum y_i}{n \sum (x_i^2) - (\sum x_i)^2} \]

3-Month Trend (Holt-Winters)

Double exponential smoothing with level (\(L_t\)) and trend (\(T_t\)):

\[ L_t = \alpha Y_t + (1 - \alpha)(L_{t-1} + T_{t-1}) \]
\[ T_t = \beta (L_t - L_{t-1}) + (1 - \beta)T_{t-1} \]

\(\alpha = 0.40\), \(\beta = 0.30\). Forecast: \(\hat{Y}_{t+k} = L_t + (k \times T_t)\).

Double-Layer Outlier Guards

Z-Score (n ≥ 5)

\[ Z = \frac{X - \mu}{\sigma} \]   Flag if \(Z > 2.0\).

Tukey's IQR (n < 5)

\[ \text{Upper Fence} = Q_3 + (1.5 \times IQR) \]

8. Authentication & Security

  • ✓
    Google OAuth

    Firebase Client SDK handles OAuth login and returns verified session tokens.

  • ✓
    User-Scoped Isolation

    All queries filter by Firebase UID, preventing cross-tenant access.

  • ✓
    Protected API Handlers

    Admin routes check against authorized admin email in MongoDB.

  • ✓
    Upload Size Validation

    Server rejects payloads > 4.5MB; clients compress locally.

9. Benchmarks & Latency

Latency times recorded under standard deployment network conditions:

3.20s
Vision OCR
180ms
API Processing
450ms
Embeddings
40ms
Vector Query

Total /api/receipts/analyze response ~3.4s (NIM inference ~3.2s + overhead ~180ms).

10. Technical Challenges

DNS SRV Resolution Failures

  • Problem: querySrv ECONNREFUSED errors.
  • Cause: Local DNS dropped SRV records.
  • Resolution: Replaced SRV with explicit replica set connection string.

Next.js ES6 Import Hoisting

  • Problem: DNS overrides evaluated too late.
  • Cause: Mongoose loaded before custom DNS servers were registered.
  • Resolution: Used CommonJS require() inside connection file: 
    dns.setServers(['8.8.8.8', '1.1.1.1']);
                                        const mongoose = require('mongoose');

11. Environment & Roadmap

.env.example

# MongoDB (bypass SRV)
                        MONGO_URI=mongodb://<user>:<pass>@ac-shard-00.mongodb.net:27017/finmind?ssl=true&replicaSet=atlas-shard-0

                        # NVIDIA NIM
                        NVIDIA_API_KEY=nvapi-xxxxxxxxxxxxxxxxxxxxxxxx

                        # Firebase
                        NEXT_PUBLIC_FIREBASE_API_KEY=AIzaSyA...
                        NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=finmind-auth.firebaseapp.com
                        NEXT_PUBLIC_FIREBASE_PROJECT_ID=finmind-auth

Roadmap

v1.0 ✓

Core Features

Firebase Auth, DB collections, receipt upload forms.

v2.0 ✓

AI Integration

Vision OCR, vector search, Holt-Winters forecasting.

v3.0 🔜

Voice & Multi‑Currency

Speech‑to‑text logging & automated currency conversion.