Self-Hosted Personal Finance for Global Citizens
AI-powered transaction classification, real-time portfolio tracking, and event-driven analytics. Secured by AES-256 encryption. Built for self-hosting. Designed for global finances.
Production-Grade Infrastructure
Three services. Eight workers. Sixty endpoints. One configuration file.
A monorepo architecture designed for privacy-first self-hosting.
[ ENTRYPOINT: Nginx :8080 (Docker) ]
│
├──► / [ FRONTEND SPA ]
│ ├── React 18, Vite 6, shadcn/ui
│ └── Communicates via REST (JWT in HttpOnly Cookie)
│
├──► /api/ [ API LAYER ]
│ ├── Next.js 15 (Pages Router), NextAuth
│ ├── >60 Endpoints (Transactions, Reports, Users)
│ └── Communicates via Internal REST (API Key Auth)
│
└──► /svc/ [ EXPRESS BACKEND :3001 ]
├── Event-Driven Architecture
├── 10 Asynchronous BullMQ Workers
│
├─► Redis 7 (Cache + Job Queues)
│
├─► Database: PostgreSQL 16 + pgvector
│ ├── Secure Store: AES-256-GCM Encryption
│ └── AI Embeddings: 768-dim Vectors
│
└─► 3rd Party Integrations:
├─► AI: Gemini LLM (Classification)
├─► Banks: Plaid (Sync + Tokens)
├─► Prices: TwelveData (Real-time Stocks)
├─► FX: CurrencyLayer (Historical Rates)
└─► Ops: Sentry (Observability)Multi-Currency Wealth, Unified.
Built from the ground up for cross-border portfolios. Backend asynchronous workers calculate historical exchange rates, ensuring your frontend dashboard never has to perform currency math on the fly.
The Unified Financial Engine
Automatically normalizes income and expenses across borders using historical FX rates to give you a single base-currency view of your entire financial life.
Real-Time Portfolio Tracking
Asynchronous workers track FIFO lots and integrate directly with the Twelve Data API for live stock/ETF prices. Historical cost-basis calculations happen in the background, never blocking your dashboard.
Equity Analysis
Break down your stock portfolio by sector, industry, and country. Weighted fundamental metrics — P/E ratio, dividend yield, EPS — surface concentration risk and income opportunities at a glance.
Expense Reporting
Category breakdowns, monthly totals, and tag-based budgets across currencies and countries. Every transaction triggers an incremental analytics update — never a full table scan.
Quiet Intelligence, Built In.
AI that works in the background so you don't have to. Transactions classify themselves, bank data syncs overnight, imports map automatically, and financial insights surface without you asking.
4-Tier Classification Engine
A deterministic AI waterfall eradicates manual entry. Transactions cascade through an exact-match Redis cache, a pgvector similarity search, and a Gemini LLM fallback. User corrections automatically generate new vector embeddings, creating a reinforcement learning loop.
Read the classification guide
Secure Institution Sync
Robust Plaid webhook ingestion handles encrypted payload staging, optimistic account linking, and automated token rotation.
Plaid setup guide
Extensible File Ingestion
A streaming engine detects CSV/XLSX schemas and executes SHA-256 row deduplication. Easily write custom TypeScript adapters to ingest data from unsupported regional banks or legacy systems.
Import guide
AI Financial Insights
Actionable reports on four cadences — monthly, quarterly, annual, and weekly portfolio intelligence.
Insights guide
AI Financial Insights
Actionable reports on four cadences — monthly, quarterly, annual, and weekly portfolio intelligence.
Insights guideBuilt for the Homelab. Enterprise-Grade Architecture.
A decoupled architecture ensuring absolute privacy, rock-solid stability, and the ability to host multiple users from a single deployment.
Multi-Tenant, Multi-User
Host completely isolated financial environments for family, friends, or a partner from a single deployment. Strict query-level tenant isolation with view-only access for shared visibility.
AES-256-GCM Encryption
Your sensitive data — including Plaid access tokens and raw bank payloads — is encrypted at rest, ensuring your financial footprint remains strictly yours.
Bulletproof Reliability
Orchestrated by 8 independent BullMQ workers and protected by over 1,000 automated CI pipeline tests.
Developer Experience
Engineered for AI Coding Agents.
Bliss is built with strict Spec-Driven Development. Every repository includes embedded context files, allowing tools like Claude Code or GitHub Copilot to onboard instantly and start shipping features safely.
CLAUDE.md Primed
Five layered context files detailing architecture, module systems, testing rules, and state management conventions. AI agents load the right context automatically based on working directory.
Spec-Driven Architecture
Every system — from the Plaid webhook engine to the pgvector classification pipeline — was documented in isolated markdown specs before a line of code was written. 43 specification files across 3 layers.
Type-Safe Boundaries
Strict Prisma schemas and validated API contracts ensure AI-generated code won't break the data model. 50+ migrations maintain schema integrity across every change.
OpenAPI-Documented Endpoints
Every API surface is documented in OpenAPI 3.0 YAML specs — 19 files covering authentication, transactions, portfolios, imports, and more. Browse them interactively in the API Reference.
$ claude > Loading project context... ✓ CLAUDE.md (root) — architecture, critical rules ✓ apps/api/CLAUDE.md — route patterns, auth flow ✓ apps/backend/CLAUDE.md — worker patterns, services ✓ apps/web/CLAUDE.md — design tokens, components ✓ apps/docs/CLAUDE.md — sync script, Nextra > Context loaded. 5 files, 43 specs, 1,178 tests $ How can I help with Bliss?