A full-stack personal finance application built with a Turborepo monorepo, featuring an Express REST API, a Next.js 14 frontend, and shared Zod schemas for end-to-end type safety. Track accounts, transactions, categories, budgets, goals, recurring bills, and analytics with a responsive interface, CSV import, and polished dashboard workflows.

WealthWise also features an MCP Server exposing 43 financial tools and 6 resources, a Context Engineering service/package for graph-based financial context assembly, and an Agentic AI service with 4 specialized Claude-powered financial advisors. The project includes comprehensive testing with Vitest and an interactive Swagger UI for API exploration. It is containerized with Docker/Podman and ready for production deployment with Nginx, Kubernetes, and cloud platforms like AWS, Azure, and GCP.

Table of Contents

• High-Level Architecture
• Features
• User Interface
• Project Structure
• Getting Started
  • Prerequisites
  • 1. Clone and install
  • 2. Configure environment
  • 3. Start MongoDB
  • 4. Seed default data
  • 5. Start development
• Scripts
• Testing
• API Documentation
  • Endpoints
  • Request Lifecycle
• Database Schema
• Authentication Flow
• Docker Deployment
  • Development
  • Production
• MCP Server
• Context Engineering
• Agentic AI
• Technical Docs
• Cloud Deployment & Infrastructure
  • Hardened Production Docker
  • Kubernetes
  • Helm Chart
  • Terraform Modules
  • Cloud Providers
  • Production Nginx
  • Utility Scripts
  • GitHub Actions CI/CD
• Test Coverage
• Agentic Coding Flywheel
• Tech Stack
• License
• Creator

High-Level Architecture

graph TB
    subgraph Monorepo["Turborepo Monorepo"]
        direction TB

        subgraph Frontend["apps/web - Next.js 14"]
            UI["React UI<br/>Tailwind + shadcn/ui"]
            RQ["TanStack Query"]
            NA["NextAuth.js"]
            RHF["React Hook Form + Zod"]
            AdvisorUI["AI Advisor + Categories pages"]
        end

        subgraph Backend["apps/api - Express 4"]
            Routes["Routes + Swagger"]
            MW["Middleware<br/>Auth · Validate · Rate Limit"]
            Services["Services"]
            AdvisorService["Advisor Service<br/>context + action execution"]
            Models["Mongoose Models"]
        end

        subgraph Shared["packages/shared-types"]
            Schemas["Zod Schemas"]
            Types["Inferred TS Types"]
        end

        subgraph MCP["mcp/ - MCP Server"]
            MCPTools["43 Tools · 6 Resources"]
            MCPTransport["SSE + stdio Transport"]
        end

        subgraph ContextEngineering["context-engineering/"]
            CEGraph["KnowledgeGraph + Traversal + Query"]
            CEKb["KnowledgeBase (BM25)"]
            CEEngine["ContextEngine + PromptAssembler"]
            CEApi["Context API + D3 UI"]
        end

        subgraph AgenticAI["agentic-ai/ - Agentic AI"]
            Orchestrator["Orchestrator Agent"]
            Specialists["4 Specialist Agents"]
            ClaudeAPI["Claude API"]
        end
    end

    DB[(MongoDB 7)]
    Gemini["Gemini API"]

    UI --> RQ
    AdvisorUI --> RQ
    RQ -->|"HTTP REST"| Routes
    NA -->|"Bearer Token"| MW
    RHF -.->|"validates forms"| Schemas
    Routes --> MW --> Services --> Models --> DB
    MW --> AdvisorService
    AdvisorService --> Models
    AdvisorService --> Gemini
    MW -.->|"validates input"| Schemas
    Schemas --> Types
    DB --> CEGraph
    CEGraph --> CEEngine
    CEKb --> CEEngine
    CEEngine --> CEApi
    MCPTools --> CEGraph
    Orchestrator --> Specialists --> ClaudeAPI
    ClaudeAPI -->|"tool_use"| MCPTransport
    MCPTransport --> MCPTools --> DB
    Specialists --> CEEngine

    style Frontend fill:#0f172a,stroke:#6366f1,color:#e2e8f0
    style Backend fill:#0f172a,stroke:#10b981,color:#e2e8f0
    style Shared fill:#0f172a,stroke:#f59e0b,color:#e2e8f0
    style MCP fill:#0f172a,stroke:#4f46e5,color:#e2e8f0
    style ContextEngineering fill:#0f172a,stroke:#06b6d4,color:#e2e8f0
    style AgenticAI fill:#0f172a,stroke:#cc785c,color:#e2e8f0
    style DB fill:#0f172a,stroke:#47a248,color:#e2e8f0
    style Gemini fill:#0f172a,stroke:#4285f4,color:#e2e8f0

Features

• Multi-account tracking - checking, savings, credit cards, cash, investments
• Transaction management - CRUD, filtering, sorting, text search, CSV import with duplicate detection
• Categories workspace - dedicated category page with search, filters, usage insights, safe delete warnings, and reusable create/edit dialogs
• Budget alerts - per-category budgets with configurable thresholds and spending progress
• **Fina