MindVault – Multi-User Personal Finance Ledger Platform

System Architecture & Domain Scope

MindVault is a multi-user personal finance platform I built solo as a self-directed learning project, to practice production-style backend and frontend architecture rather than to serve live users. The NestJS backend owns accounts, transactions, the ledger, summaries, tags and authentication; the Next.js client handles dashboards, reports and account management.

flowchart TD
    subgraph Client ["Next.js 15 App Router"]
        UI["32 pages · 92 components"]
        Stores["11 Zustand stores"]
        Services["10 API services"]
        UI --> Stores --> Services
    end

    subgraph Server ["NestJS 11 + TypeORM"]
        Controllers["22 controllers · 89 endpoints"]
        Guards["JWT & account RBAC guards"]
        Domain["28 domain services"]
        Ledger["Ledger & decimal engine"]
        Summary["Incremental summary engine"]
        Controllers --> Guards --> Domain
        Domain --> Ledger
        Domain --> Summary
    end

    DB[("PostgreSQL · 24 entities")]
    Services -->|"REST + cookies"| Controllers
    Domain --> DB

Persona Value Map

Core Engineering Innovations

1. Precision Ledger Engine

Balances are updated through safeAdd and safeSubtract helpers on decimal.js, with non-negative checks, while every change is written to an immutable AccountLedger table for audit.

2. Incremental Summary Pipeline

Transaction create, update and delete hooks update 6 summary entities (daily, weekly, monthly, yearly, category) in the same transaction, so analytics endpoints read rollups instead of raw history.

3. Contextual Account RBAC

An AccountUserRole junction entity maps users to accounts with Owner, Admin, Editor or Viewer roles, enforced by custom NestJS guards independent of global JWT auth.

4. Client State Architecture

Domain-specific Zustand stores and API services feed an ApiResponseToast listener, giving consistent success and error feedback across all mutations.

Database Design & Concurrency

• 24 TypeORM entities on PostgreSQL covering users, sessions, accounts, ledgers, transactions, summaries, categories, currencies, roles and tags.
• Summary updates run in the same transaction as the ledger mutation they derive from, keeping balances and rollups consistent.
• Six nestjs-command seeders bootstrap roles, categories, currencies, account types, tag groups and tags.
• Tags use soft delete with restore, plus dedicated repositories, validators and transformers.

Performance Benchmarks & Reliability

Lessons Learned & Architectural Retrospective

• What worked: isolating money math in one helper module and routing every balance change through it kept precision rules in a single place.
• Trade-offs: pre-aggregated summaries speed up reads but add write-path work; per-account roles add joins on scoped requests.
• Learning outcome: this project was my practice ground for modular NestJS design, transactional consistency, role-based access and a store-per-domain frontend.
• Next: statement export (PDF and CSV), then the personal growth suite.