SPDX-License-Identifier: Apache-2.0

Copyright (c) 2026 Stephen Hellings and contributors

Financier

Node.js backend with Bun runtime

Financier is the OpenFinance service for viewing, planning, and managing finances. It's a self-hosted finance dashboard with email integration, market data, and transaction tracking.

---

Quick Start

# 1. Install dependencies
bun install

# 2. Copy environment config
cp .env.example .env  # or create .env manually

# 3. Start development server
bun --watch src/main.ts

App runs at http://localhost:3000 (or $PORT). Register a new account and start connecting email inboxes, market watches, and customizing your dashboard.

---

Prerequisites

• Bun v1.0+ (the runtime used throughout)
• Podman (optional — required only if using actor email parsing)
• A code editor (VS Code recommended)

---

Development

Available Scripts

Script	Description
bun --watch src/main.ts	Start dev server with hot-reload (nods to start:dev in package.json)
nest build	Build NestJS production backend
bun build src/client/chart.ts --outdir dist/public --target browser	Build Chart.js bundle for frontend
prettier --write "src/**/*.ts" "src/**/*.tsx"	Format code with Prettier
just keygen	Generate SSH keys (see justfile)

Folder Structure

src/
├─ modules/      # NestJS modules (app, dashboard, oauth, registry, db)
├─ entities/     # TypeORM entity definitions (User, Transaction, EmailInbox, etc.)
├─ views/        # React + JSX templates (SSR via nestjs-tsx-views)
├─ actors/       # Containerized actor manifests for email parsing
├─ client/       # Frontend-only scripts (chart.ts)
├─ data-source.ts # SQL.js SQLite config
└─ main.ts       # Entry point

---

Documentation

See the docs/ folder for in-depth guides:

Doc	What you’ll find
ARCHITECTURE.md	Tech stack, data flow, entity breakdown, actor development guide
GETTING_STARTED.md	Local dev setup, script usage, actor testing, deployment checklist
API.md	Full REST API reference (auth, dashboard, market, transactions, OAuth, errors)
ROADMAP.md	Planned features, technical debt, version tracking
SECURITY.md	Authentication details, data protection, actor sandboxing, hardening checklist

---

Features

• Authentication: Password-based register/login with scrypt hashing; OAuth2/OIDC via nest-oidc-provider; Google OAuth for email connections
• Dashboard: Rearrangeable layout cards (accounts, activity, connections, transactions, market)
• Email Integration: IMAP inbox connections (via imapflow), Google OAuth linking, historical sync, actor-based email parsing for Zelle/chase transactions
• Market Data: Real-time stock quotes from Yahoo Finance, financial news from Google News; add watches per user
• Transactions: Manual entry + actor-extracted transactions from email; amount, merchant, account last-four tracking
• Encryption: AES-256-GCM for inbox credentials; scrypt for password hashing
• Actors: Isolated containerized processors via podman (--network none, --read-only, --cap-drop ALL); discoverable at GET /registry/actors

---

Configuration

Copy .env.example (or create .env) with at minimum:

Variable	Default	Description
PORT	3000	Server port
DATABASE_PATH	database.sqlite	SQLite file location
SESSION_SECRET	development-session-secret	HMAC signing key for sessions
INBOX_ENCRYPTION_KEY	derived from SESSION_SECRET	AES-256-GCM key for email credentials
PUBLIC_URL	http://localhost:3000	Public base URL for OIDC redirects
OIDC_CLIENT_ID	financier-web	OIDC client ID
OIDC_CLIENT_SECRET	development-only-secret	OIDC client secret
OIDC_JWKS	(none)	JWKS JSON for token validation
GOOGLE_OAUTH_CLIENT_ID	(none)	Google OAuth client ID
GOOGLE_OAUTH_CLIENT_SECRET	(none)	Google OAuth client secret

---

License

SPDX-License-Identifier: Apache-2.0

Copyright (c) 2026 Stephen Hellings and contributors

Apache-2.0 License

---

Built with ❤️ using NestJS v12, React 19, sql.js, and containerized actors.