Topics

#ai-solution #fintech #fintech-ai #fintech-solution #solution

Language breakdown

TypeScript 97.0%

CSS 1.4%

JavaScript 0.8%

Dockerfile 0.5%

Shell 0.3%

▸ Files click to expand

README

FinSight AI — AI Financial Assistant for SMEs

Production-grade SaaS financial intelligence platform powered by GPT-4o, Next.js 15, and PostgreSQL.

🚀 Features

Core Modules

| Module | Description | |--------|-------------| | Financial Dashboard | Real-time revenue, expenses, profit, invoice metrics | | Invoice Management | Create, send, track, record payments | | Expense Tracking | Manual entry, CSV import, categorization | | Transaction Ledger | Full double-entry transaction history | | Bank Statement Analyzer | Upload PDF/CSV, extract & categorize transactions | | AI Financial Assistant | RAG-based chatbot with real financial data context | | AI Insights Engine | Auto-detected anomalies, risks, opportunities | | Cash Flow Forecasting | Deterministic 3-month linear trend forecasts | | Financial Reports | P&L, Expense Summary, Revenue Trends (PDF/Excel) | | Settings & Security | RBAC, audit logs, MFA, organization management |

Critical Design Principle

AI NEVER calculates financial values. All calculations are deterministic and performed by the backend using Prisma queries. AI only generates explanations, insights, and narratives based on the pre-calculated data.

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    Next.js 15 App Router                 │
├──────────────────────┬──────────────────────────────────┤
│   Frontend (RSC)     │        API Routes                 │
│  - Dashboard         │  - /api/dashboard                 │
│  - Invoices          │  - /api/invoices                  │
│  - Expenses          │  - /api/expenses                  │
│  - AI Assistant      │  - /api/ai/chat (SSE streaming)   │
│  - Cash Flow         │  - /api/cash-flow                 │
│  - Reports           │  - /api/reports                   │
│  - Insights          │  - /api/insights                  │
└──────────────────────┴──────────────────────────────────┘
           │                          │
    Clerk Auth                  Prisma ORM
           │                          │
    PostgreSQL DB              OpenAI GPT-4o
           │                          │
    Qdrant Vector DB         RAG Pipeline

RAG Pipeline

User Question
→ Intent Classification (GPT-4o-mini)
→ Data Retrieval (Prisma queries = REAL numbers)
→ Context Assembly
→ OpenAI GPT-4o Response Generation
→ Streaming SSE to Frontend

📋 Tech Stack

Frontend

Next.js 15 (App Router, RSC, Streaming)
TypeScript 5
Tailwind CSS + ShadCN UI components
Recharts (interactive financial charts)
React Query (server state management)
Zustand (client state)

Backend

Next.js API Routes
Prisma ORM with PostgreSQL
Zod validation (all inputs)
Rate limiting via Redis when REDIS_URL is set (in-process fallback otherwise)
Redis-backed dashboard metrics cache with version invalidation on writes

AI

OpenAI GPT-4o (assistant responses)
OpenAI text-embedding-3-small (embeddings)
RAG architecture for financial context
Qdrant vector database

Auth & Security

Clerk Authentication (OAuth, MFA, RBAC)
OWASP Top 10 compliant
CSRF protection in middleware
SQL injection prevention (Prisma parameterized queries)
Complete audit logging

🗄️ Database Schema

Organizations ──┬── OrganizationMembers ── Users
                ├── Clients
                ├── Vendors
                ├── Categories
                ├── Transactions ── Categories
                ├── Invoices ─────┬── InvoiceItems
                │                 └── Payments
                ├── Expenses ── Categories
                ├── BankStatements ── Transactions
                ├── Reports
                ├── AIChats ── AIChatMessages
                ├── Insights
                ├── CashFlowForecasts
                ├── Notifications
                ├── AuditLogs
                └── Anomalies

🔒 Security Implementation

| Security Layer | Implementation | |----------------|---------------| | Authentication | Clerk JWT + MFA | | Authorization | RBAC (Admin/Accountant/Employee/Viewer) | | CSRF Protection | Origin/Host validation in middleware | | Rate Limiting | Per-IP sliding window (100 req/min default) | | Input Validation | Zod schemas on all API endpoints | | SQL Injection | Prisma ORM parameterized queries | | XSS Prevention | Next.js built-in + CSP headers | | Audit Logging | All CRUD operations logged with user/IP | | Sensitive Data | Prisma field-level encryption ready | | File Upload | Type validation, size limits, S3 signed URLs |

🚀 Quick Start

Prerequisites

Node.js 20+
PostgreSQL 16+
OpenAI API key
Clerk account

1. Clone & Install

git clone https://github.com/imchine/FinTech-Solution.git
cd finsight-ai
npm install

2. Environment Setup

cp .env.example .env.local
Fill in your API keys

3. Database Setup

# Apply schema
npx prisma migrate dev --name init
Generate client
npx prisma generate

4. Run Development

npm run dev
Open http://localhost:3000

5. Docker (Full Stack)

docker-compose up -d

Redis (optional)

Redis is optional but recommended for production and multi-instance deployments.

docker compose up -d redis
set in .env.local:
REDIS_URL=redis://localhost:6379

When REDIS_URL is set:

Rate limiting — shared across API routes (/api/transactions, /api/invoices, /api/ai/chat, etc.)
Dashboard cache — metrics cached for 2 minutes; invalidated when transactions, expenses, or invoices change
Health check — GET /api/health reports whether Redis is configured

Without Redis, rate limits and dashboard metrics use in-process behaviour only.

📁 Folder Structure

finsight-ai/
├── src/
│   ├── app/
│   │   ├── (auth)/          # Sign in/up pages (Clerk)
│   │   ├── (dashboard)/     # All protected dashboard pages
│   │   │   ├── dashboard/   # Main financial dashboard
│   │   │   ├── invoices/    # Invoice management
│   │   │   ├── expenses/    # Expense tracking
│   │   │   ├── transactions/# Transaction ledger
│   │   │   ├── ai-assistant/# AI chatbot interface
│   │   │   ├── cash-flow/   # Cash flow & forecasting
│   │   │   ├── insights/    # AI insights engine
│   │   │   ├── reports/     # Financial reports
│   │   │   ├── bank-statements/ # Bank statement analyzer
│   │   │   └── settings/    # Account & org settings
│   │   └── api/             # All API routes
│   ├── components/
│   │   ├── ui/              # ShadCN UI components
│   │   ├── charts/          # Recharts wrappers
│   │   ├── dashboard/       # Dashboard-specific components
│   │   ├── layout/          # Sidebar, Header
│   │   └── shared/          # Providers, theme
│   ├── lib/
│   │   ├── prisma.ts        # Database client
│   │   ├── auth.ts          # Auth helpers & audit logging
│   │   ├── openai.ts        # AI integration & RAG
│   │   ├── financial-calculations.ts  # ALL financial math
│   │   ├── validations.ts   # Zod schemas
│   │   ├── rate-limit.ts    # API rate limiting
│   │   └── utils.ts         # Utilities & formatters
│   ├── middleware.ts         # Auth & security middleware
│   └── types/               # TypeScript types
├── prisma/
│   └── schema.prisma        # Complete DB schema
├── docker-compose.yml       # Full stack Docker setup
├── Dockerfile               # Production container
└── .env.example             # Environment template

📊 API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/health | Health check | | GET | /api/dashboard | Dashboard metrics | | GET | /api/dashboard/trends | Monthly trends | | GET | /api/dashboard/categories | Expense categories | | GET/POST | /api/invoices | List/create invoices | | GET/PATCH/DELETE | /api/invoices/[id] | Invoice operations | | GET/POST | /api/expenses | List/create expenses | | GET/POST | /api/transactions | List/create transactions | | POST | /api/ai/chat | AI chat (SSE streaming) | | GET | /api/ai/chat | Chat history | | GET | /api/cash-flow | Historical + forecasts | | GET/POST | /api/reports | Report management | | GET | /api/insights | AI insights |