MindVault – Full-Stack Personal Finance & Productivity Engine

Executive Summary

MindVault is a comprehensive, multi-user personal finance management and productivity platform engineered with enterprise-grade architecture principles. Built across two decoupled repositories—a Next.js 15 App Router frontend and a NestJS + TypeORM + PostgreSQL backend—MindVault combines strict type safety, modular micro-domain boundaries, granular role-based access control (RBAC), and high-performance financial ledger rollups.

Architecture

High-level system design

flowchart TB
    subgraph Client ["Frontend — Next.js 15 (App Router)"]
        APP["Next.js App Router<br/>(protected)/*"]
        ZUSTAND["Zustand Stores<br/>(Accounts, Transactions, Auth)"]
        UI_COMP["ShadCN UI + Radix UI<br/>Lucide Icons"]
        CHARTS["Data Visualization<br/>Chart.js, Recharts, Ant Design Plots"]
        FORMS["React Hook Form + Zod"]
        TOAST["Sonner Notifications<br/>ApiResponseToast"]
    end

    subgraph API_GATEWAY ["NestJS Modular Backend (/api/v1)"]
        JWT_GUARD["JWT Auth Guard<br/>+ Passport.js"]
        RBAC_GUARD["Role-Based Access Guard<br/>(Owner / Admin / Editor / Viewer)"]
        SWAGGER["OpenAPI 3.0 / Swagger UI<br/>/api/v1/docs#/"]
    end

    subgraph DOMAINS ["Domain Modules (6-Layer Standard)"]
        AUTH_MOD["Auth & Users Module"]
        ROLE_MOD["Roles & Permissions Module"]
        FINANCE_MOD["Finance & Ledger Module"]
        TAGS_MOD["Polymorphic Tags Module"]
    end

    subgraph STORAGE ["Persistence Layer"]
        TYPEORM["TypeORM DataSource<br/>Repository Layer + Migrations"]
        POSTGRES[("PostgreSQL 15+<br/>Indexed Ledger Schemas")]
        SEEDER["Automated Seeders<br/>(Roles, Currencies, Categories)"]
    end

    APP --> FORMS & UI_COMP & CHARTS
    APP --> ZUSTAND
    ZUSTAND -->|"HTTP Requests (/api/v1)"| JWT_GUARD
    JWT_GUARD --> RBAC_GUARD
    RBAC_GUARD --> AUTH_MOD & ROLE_MOD & FINANCE_MOD & TAGS_MOD
    AUTH_MOD & ROLE_MOD & FINANCE_MOD & TAGS_MOD --> TYPEORM
    TYPEORM --> POSTGRES
    SEEDER --> POSTGRES

The 6-Layer Module Standard

MindVault enforces a strict, predictable 6-layer architecture across all backend domain modules (auth, roles, finance, tags). Every module follows this exact structure:

/src/<module-name>/
├── controller/       # Routes HTTP requests and maps DTOs (No business logic)
├── validators/       # Input validation & cross-field business constraints
├── services/         # Business logic orchestration (No raw SQL or QueryBuilder)
├── repository/       # Data access, QueryBuilder queries, soft-deletes, pagination
├── transformers/     # Converts TypeORM entities into API-friendly DTO contracts
├── entity/           # TypeORM entity definitions with snake_case table mappings
├── dto/              # Create, Update, Query, and Shared validation DTOs
├── data/             # Default data sets for system seeding
├── seeder/           # Automated database seeders
└── <module>.module.ts # NestJS dependency injection wiring

Request/Response Lifecycle Pipeline

sequenceDiagram
    autonumber
    actor User as Client (Next.js / Zustand)
    participant Ctrl as Controller
    participant Val as Validator
    participant Svc as Service Layer
    participant Repo as Repository Layer
    participant DB as PostgreSQL 15+
    participant Trans as Transformer Layer

    User->>Ctrl: POST /api/v1/finance/transactions (DTO Payload)
    Ctrl->>Val: validateCreateTransaction(dto)
    alt Validation Failure
        Val-->>Ctrl: Throw BadRequestException (Zod/class-validator errors)
        Ctrl-->>User: Standardized Error Envelope
    else Validation Passed
        Val-->>Ctrl: DTO Sanitized
        Ctrl->>Svc: createTransaction(userId, sanitizedDto)
        Svc->>Svc: Execute business logic & balance recalculation
        Svc->>Repo: saveTransaction(entity)
        Repo->>DB: TypeORM QueryBuilder / INSERT query
        DB-->>Repo: Raw DB Entity Record
        Repo-->>Svc: Transaction Entity
        Svc->>Trans: transformToResponseDto(entity)
        Trans-->>Svc: Sanitized Clean DTO
        Svc-->>Ctrl: Result DTO
        Ctrl-->>User: HTTP 201 { success: true, message: "Transaction created", data: {...} }
    end

Core Technical Decisions

Decision 1 — Strict 6-Layer architectural boundary enforcement

Decision 2 — Multi-Account Ledger & Time-Series Financial Rollups

flowchart LR
    subgraph RawData ["Raw Transaction Ledgers"]
        T1["Transaction Records<br/>(Amount, Category, Date, Account)"]
    end

    subgraph QueryEngine ["TypeORM QueryBuilder Engine"]
        FILTER["User & Account Scope Filter"]
        TRUNC["DATE_TRUNC('month', transaction_date)"]
        AGG["SUM(amount), COUNT(id) Grouped by Category"]
        FILTER --> TRUNC --> AGG
    end

    subgraph Summaries ["Aggregated Outputs"]
        S1["Daily Summary"]
        S2["Weekly Summary"]
        S3["Monthly Breakdown"]
        S4["Yearly P&L Trend"]
    end

    T1 --> FILTER
    AGG --> S1 & S2 & S3 & S4

Decision 3 — Multi-Tier Role-Based Access Control (RBAC)

flowchart TD
    REQ["User Request on Account Resource"] --> JWT{"Valid JWT Token?"}
    JWT -- No --> UNAUTH["401 Unauthorized"]
    JWT -- Yes --> ROLE_CHECK{"User Role on Account?"}
    
    ROLE_CHECK -- Owner --> ALLOW_ALL["Full Access (CRUD, Delete, Share)"]
    ROLE_CHECK -- Admin --> ALLOW_ADMIN["Manage Transactions, Categories, Members"]
    ROLE_CHECK -- Editor --> ALLOW_EDIT["Record & Edit Transactions"]
    ROLE_CHECK -- Viewer --> ALLOW_READ["Read-Only Ledgers & Charts"]
    ROLE_CHECK -- None --> FORBID["403 Forbidden"]

Visual Workflows & Architecture Wireframes

1. Financial Command Center & Analytics Dashboard Wireframe

+----------------------------------------------------------------------------------------------------+
|  [Logo] MindVault   |  [Account: Main Checking v]  |  [Date: This Month v]  |  [+ Add Tx]  | (Avatar) |
+---------------------+------------------------------------------------------------------------------+
| NAVIGATION          | FINANCIAL SUMMARY & LEDGER ROLLUP                                            |
|                     +------------------------------------------------------------------------------+
| [=] Dashboard       | +-- KPI SUMMARY CARDS -----------------------------------------------------+ |
| [$] Accounts (4)    | | Net Balance: $42,580.00  | Total Income: +$8,450.00 | Total Expense: -$3,210.00| |
| [#] Transactions    | | Savings Rate: 62.0%      | Active Budgets: 4/5 Met  | Monthly Delta: +$5,240.00| |
| [*] Budgets & Goals | +--------------------------------------------------------------------------+ |
| [^] Analytics       |                                                                              |
| [@] Shared Members  | +-- CASH FLOW & SPENDING TREND (Chart.js / Recharts) ----------------------+ |
| [!] Settings        | |  $8k |               /---\                                               | |
|                     | |  $6k |    /---\     /     \     /---\        Income (Green)              | |
|                     | |  $4k |   /     \---/       \---/     \       Expense (Crimson)           | |
|                     | |  $2k |===================================                                | |
|                     | |      | Week 1    Week 2    Week 3    Week 4                               | |
|                     | +--------------------------------------------------------------------------+ |
|                     |                                                                              |
|                     | +-- RECENT TRANSACTIONS TABLE ---------------------------------------------+ |
|                     | | Date       | Description          | Category       | Account     | Amount   | |
|                     | |------------|----------------------|----------------|-------------|----------| |
|                     | | 2026-08-28 | Client Invoice #104  | Consulting     | Business Checking | +$4,200 | |
|                     | | 2026-08-27 | AWS Cloud Services   | Infrastructure | Corporate Visa    | -$340.00| |
|                     | | 2026-08-26 | Ergonomic Desk Chair | Office Setup   | Savings           | -$650.00| |
| [<-] Sign Out       | +--------------------------------------------------------------------------+ |
|                     | PAGE 1 OF 24 (238 RECORDS)                     [<<] [<] [1] [2] [3] [>] [>>] |
+---------------------+------------------------------------------------------------------------------+

2. Frontend State Management & API Toast Synchronization

flowchart TD
    subgraph UI_Layer ["Next.js App Router (Client Components)"]
        ACTION["User Action (e.g., Create Account / Edit Category)"]
        FORM["React Hook Form + Zod Validation"]
        ACTION --> FORM
    end

    subgraph State_Layer ["Zustand Store Layer"]
        STORE["Zustand Domain Store (useFinanceStore)"]
        FETCHER["Custom Axios/Fetch Wrapper with Bearer JWT"]
        FORM -->|"Dispatch Action"| STORE
        STORE -->|"Trigger Request"| FETCHER
    end

    subgraph Network_Layer ["Backend Communication"]
        API["NestJS REST API (/api/v1)"]
        FETCHER -->|"HTTP POST / PATCH"| API
        API -->|"Standard Envelope { success, message, data }"| FETCHER
    end

    subgraph Feedback_Layer ["Notification & UI Reconciliation"]
        TOAST["Sonner ApiResponseToast<br/>(Auto displays success / error message)"]
        REACTIVE["Update Zustand Reactive State<br/>(Optimistic UI Update)"]
        FETCHER --> TOAST
        FETCHER --> REACTIVE
    end

What I Built (Personal Contributions)

• Engineered the Entire Next.js 15 Frontend: Implemented the App Router architecture, Zustand state slices, ShadCN UI component integration, Chart.js visualizations, and form validations.
• Architected the NestJS 6-Layer Backend: Designed the Controller-Validator-Service-Repository-Transformer-Seeder pattern for high scalability, loose coupling, and clean testing.
• Designed PostgreSQL Relational Schemas: Created normalized database tables for multi-currency accounts, double-entry ledgers, category hierarchies, and savings goals with TypeORM migrations.
• Built Multi-User RBAC & Authentication: Implemented JWT authentication, Passkey support, security question recovery, and account-level RBAC (Owner, Admin, Editor, Viewer).
• Engineered Financial Aggregation Pipeline: Built TypeORM QueryBuilder aggregate services calculating daily, weekly, monthly, and yearly income/expense metrics with sub-65ms response times.
• Developed Comprehensive Developer Documentation: Built an interactive OpenAPI 3.0 Swagger UI alongside a dedicated Docusaurus static documentation portal.

Future Roadmap

timeline
    title MindVault Evolution Roadmap
    section In Progress
        Multi-Currency FX Engine : Real-time exchange rate normalization for international ledgers
        E2E Test Suite Expansion : Automated Jest and Playwright coverage across all financial workflows
    section Planned
        Plaid Banking Sync : Direct transaction ingestion from 10,000+ financial institutions
        AI Financial Advisor : Smart categorization and predictive cash flow runway modeling
        Encrypted Tax Exporter : Automated IRS/HMRC expense classification and exportable PDF/Excel reports