Live: fin-os-self.vercel.app
AI-powered financial operating system. FinOS moves beyond passive expense tracking by combining a dashboard UI with Google Gemini 1.5 Flash Vision to scan receipts, parse unstructured financial data, automate budget alerts, and generate financial insights — all backed by Next.js Server Actions, Prisma, and a serverless event-worker pipeline.
- Features
- Architecture
- Database Schema
- Tech Stack
- Project Structure
- Quick Start
- Environment Variables
- Documentation
AI Receipt Parsing Receipts can be uploaded from mobile or desktop. Google Gemini 1.5 Flash Vision reads the raw image, extracts merchant name, line items, date, and amount, and returns schema-compliant JSON that's written straight into the transaction table — no manual entry or brittle OCR regex.
Multi-Account Aggregation A unified dashboard tracks current and savings balances, net worth trajectory, cash flow velocity, and spending habits across every linked account in one place.
Dynamic Budget Guardrails Monthly budgets can be set per category. Progress bars update in real time, and an automated alert fires once spend crosses 80% of the budget for that category.
Recurring Transaction Engine Upcoming bills and subscription renewals are forecast automatically. A daily background worker checks due dates and processes recurring transactions without any manual intervention.
Automated AI Email Summaries A monthly cron job aggregates spend by category, asks Gemini for financial advice based on that data, and dispatches an HTML summary email via Resend — entirely in the background, outside the request/response cycle.
Enterprise-Grade Security Every mutation passes through Arcjet WAF (bot defense, rate limiting capped at 1 request/minute per user for intensive operations) behind Clerk authentication, so abuse is blocked before it reaches business logic.
FinOS runs on a serverless architecture with clean boundaries between edge authentication, synchronous server actions, asynchronous event workers, and multi-modal AI inference.
graph TB
subgraph "Client Layer"
WEB[Web Browser]
MOB[Mobile Device]
end
subgraph "Edge & Security"
MID[Next.js Middleware<br/>Routing]
CLERK[Clerk Auth<br/>Session Validation]
WAF[Arcjet WAF<br/>Bot Protection]
WEB --> MID
MOB --> MID
MID <--> CLERK
MID <--> WAF
end
subgraph "Frontend: App Router"
FE[Frontend Pipeline]
subgraph "UI & State"
UI[React Components<br/>Tailwind + Shadcn]
PAGE[App Pages<br/>Dashboard & Budgets]
end
MID --> FE
FE --> UI
UI --> PAGE
end
subgraph "Backend: Server Actions"
SA[Server Actions Engine]
DEC{Is Async/AI<br/>Task?}
PAGE --> SA
SA --> DEC
end
subgraph "Tier 2: Async & AI Processing"
T2[Async Pipeline]
subgraph "Workers & Models"
AI[Google Gemini 1.5<br/>Vision & Insights]
JOB[Inngest Workers<br/>Crons & Webhooks]
end
DEC -->|Yes| T2
T2 --> AI
T2 --> JOB
end
subgraph "Data Layer"
PRISMA[Prisma ORM<br/>Type-safe Client]
DB[(Supabase PostgreSQL<br/>Relational Store)]
SA --> PRISMA
JOB --> PRISMA
PRISMA <--> DB
end
subgraph "Output Layer"
DASH[Live Dashboard<br/>Optimistic Updates]
EMAIL[Resend Email<br/>Alerts & Reports]
end
DEC -->|No| PRISMA
SA --> DASH
JOB --> EMAIL
AI --> PRISMA
style FE fill:#e3f2fd
style T2 fill:#fff3e0
style PRISMA fill:#f3e5f5
style MID fill:#e8f5e9
style DASH fill:#fce4ec
style EMAIL fill:#1428a0,color:#fff
Infrastructure layers:
- Next.js 16 App Router + React 19 renders the dashboard and handles concurrent UI state with optimistic updates.
- Clerk + Arcjet WAF authenticate every request and block bots, SQL injection, and abusive mutation rates at the edge.
- Next.js Server Actions run synchronous business logic directly on the backend with no separate REST controller layer.
- Google Gemini 1.5 Flash powers both receipt-image parsing and monthly insight generation.
- Prisma + Supabase PostgreSQL persist
User,Account,Transaction, andBudgetrecords with connection pooling. - Inngest runs scheduled crons and event workers outside Vercel's serverless timeout window.
- Resend + React Email deliver budget alerts and monthly summary emails.
FinOS implements a strict relational schema in PostgreSQL, managed through Prisma for type-safe queries and migrations.
erDiagram
User ||--o{ Account : "owns"
User ||--o{ Transaction : "makes"
User ||--o{ Budget : "has"
Account ||--o{ Transaction : "contains"
User {
String id PK
String clerkUserId UK
String email UK
String name
String imageUrl
DateTime createdAt
DateTime updatedAt
}
Account {
String id PK
String name
AccountType type
Decimal balance
Boolean isDefault
String userId FK
DateTime createdAt
DateTime updatedAt
}
Transaction {
String id PK
TransactionType type
Decimal amount
String description
DateTime date
String category
String receiptUrl
Boolean isRecurring
RecurringInterval recurringInterval
DateTime nextRecurringDate
DateTime lastProcessed
TransactionStatus status
String userId FK
String accountId FK
DateTime createdAt
DateTime updatedAt
}
Budget {
String id PK
Decimal amount
DateTime lastAlertSent
String userId FK
DateTime createdAt
DateTime updatedAt
}
| Component | Technology |
|---|---|
| Frontend | Next.js 16 (App Router), React 19, Tailwind CSS v4, shadcn/ui |
| Animation | Framer Motion, GSAP, Three.js |
| Data Visualization | Recharts |
| Backend Logic | Next.js Server Actions |
| Authentication | Clerk |
| Security / WAF | Arcjet |
| AI Vision & Insights | Google Gemini 1.5 Flash |
| Database | Supabase PostgreSQL 16, Prisma ORM v6 |
| Async Queues & Crons | Inngest v3 |
| Email Delivery | Resend, React Email |
| Deployment | Vercel |
FinOS/
├── Backend/
│ ├── actions/ # Server Actions (account.js, budget.js, dashboard.js, transaction.js)
│ ├── database/ # Prisma client singleton + schema
│ │ └── schema/ # schema.prisma models and enums
│ ├── security/ # Arcjet WAF defense + Clerk user sync
│ └── services/
│ ├── emails/ # React Email templates (Budget Alert, Monthly Report)
│ └── inngest/ # Inngest client + scheduled function handlers
├── app/
│ ├── (main)/ # Protected dashboard routes
│ └── api/ # Webhook endpoints (Inngest receiver, db seeding)
├── components/ # Reusable UI components and dashboard widgets
├── hooks/ # Client hooks for UI state and financial calculations
├── lib/ # Utility helpers and formatting constants
├── public/ # Favicons, static logos, illustrations
├── middleware.js # Clerk auth + Arcjet edge interception
└── package.json
- Node.js 18+
- A Supabase (or any PostgreSQL) instance
- API keys for Clerk, Gemini, Resend, Arcjet, and Inngest
git clone https://github.com/shreedharkb/FinOS.git
cd FinOS
npm installcp .env.example .env
# Edit .env — set DATABASE_URL, CLERK keys, GEMINI_API_KEY, RESEND_API_KEY, ARCJET_KEY, INNGEST_EVENT_KEYnpx prisma db push
npx prisma generatenpm run devOpen http://localhost:3000.
npx inngest-cli@latest dev| Variable | Description |
|---|---|
DATABASE_URL |
Supabase PostgreSQL pooled connection string |
DIRECT_URL |
Direct unpooled connection string, required for Prisma migrations |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY |
Clerk frontend publishable key |
CLERK_SECRET_KEY |
Clerk backend secret key |
GEMINI_API_KEY |
Google AI Studio key for Vision parsing and insights |
RESEND_API_KEY |
Resend key for transactional emails |
ARCJET_KEY |
Arcjet WAF security key |
INNGEST_EVENT_KEY |
Inngest event signing key |
Shreedhar K B — Design, development, and deployment.
This project is licensed under the GNU General Public License v3.0.| Clerk backend secret key | |GEMINI_API_KEY| Google AI Studio key for Vision parsing and insights | |RESEND_API_KEY| Resend key for transactional emails | |ARCJET_KEY| Arcjet WAF security key | |INNGEST_EVENT_KEY` | Inngest event signing key |
Shreedhar K B — Design, development, and deployment.
This project is licensed under the GNU General Public License v3.0.