MODRACXKENNETH D'SILVA

← Documentation Hub

Orqa Personal Finance: Reference Manual

A self-hosted, privacy-first personal finance platform built with Next.js App Router, Prisma ORM, and PostgreSQL. Features strict double-entry ledger math, multi-currency Forex tracking, cash flow analytics, and envelope budgeting.

GitHub Repository ↗ Read Architectural Case Study

1. System Architecture & Tech Stack

Orqa is architected to eliminate third-party data tracking, banking API subscriptions, and single-entry balance calculation drift. Built on React Server Components (RSC) and PostgreSQL ACID transactions, it provides sub-50ms query speeds across multi-year ledgers.

Subsystem Technology Function
Application Runtime Next.js 15 (Node.js 20+ standalone) Server Component streaming and Server Actions
Data Layer PostgreSQL 16 + Prisma ORM Double-entry ledger records with BigInt precision
Math & Currencies Decimal.js + ECB Forex feed Zero-floating-point calculations and daily FX snapshots
Authentication NextAuth.js + Argon2id Self-contained credential hashing and session security

2. Docker Compose Deployment Guide

Deploy Orqa on any Linux server in under 2 minutes using the production Docker Compose stack:

# docker-compose.yml
version: '3.8'

services:
  orqa-app:
    image: modracx/orqa:latest
    container_name: orqa_web
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      - DATABASE_URL=postgresql://orqa:secure_password_here@orqa-db:5432/orqa_prod
      - NEXTAUTH_SECRET=generate_64_character_hex_string_here
      - NEXTAUTH_URL=https://finance.yourdomain.com
      - NODE_ENV=production
    depends_on:
      orqa-db:
        condition: service_healthy

  orqa-db:
    image: postgres:16-alpine
    container_name: orqa_postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=orqa
      - POSTGRES_PASSWORD=secure_password_here
      - POSTGRES_DB=orqa_prod
    volumes:
      - orqa_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U orqa -d orqa_prod"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  orqa_pgdata:
    driver: local
# Start containers in detached mode
docker compose up -d

# Run initial database schema migrations
docker compose exec orqa-app npx prisma migrate deploy

3. Environment Variables Reference

Variable Required Example Value Description
DATABASE_URL Yes postgresql://user:pass@host:5432/db PostgreSQL connection string
NEXTAUTH_SECRET Yes openssl rand -hex 32 Key used to sign and encrypt session cookies
NEXTAUTH_URL Yes https://finance.example.com Public canonical URL of your instance
DEFAULT_CURRENCY No USD (or EUR, GBP, CAD) Default currency for newly created user accounts

4. Core Ledger Operations & Posting Rules

Every transaction must satisfy the double-entry identity:

∑ Debits === ∑ Credits (in base currency minor units)

Supported root account hierarchies:

  • Assets:Current:* (Checking, Savings, Cash in Wallet)
  • Assets:Investments:* (Brokerage, Roth IRA, Crypto)
  • Liabilities:CreditCard:* (Visa, Amex Revolving)
  • Liabilities:Loans:* (Mortgage, Auto Note)
  • Revenue:* (Salary, Consulting, Dividends)
  • Expenses:* (Housing, Groceries, Utilities, Subscriptions)

5. Bank CSV Import & Categorization Pipeline

Drag and drop standard CSV statements from your online banking portal into Ledger > Import. Orqa provides automated column mapping for Date, Payee/Description, and Amount, running regular expression rules to automatically match recurring payees to their corresponding expense categories.

Related Tools & Documentation