Where The Heart Is

Overview

"Where The Heart Is" is a web tool designed to aid prospective homebuyers in visualizing and calculating various mortgage scenarios. This tool helps you understand the true financial impact of homebuying decisions by revealing what typical calculators hide: the lifetime cost of interest, the impact of rate changes, and how PMI affects your bottom line.

Answer "what does this house actually cost me over 30 years?" instead of just "can I afford the monthly payment?"

Quick Start with Docker

Get up and running in 4 commands:

git clone https://github.com/Mike-Bros/WhereTheHeartIs
cd WhereTheHeartIs
cp .env.example .env       # Copy environment configuration
docker compose up -d       # Build and start all services

Access the application at http://localhost:8911 (or https://wthi.bros.ninja in production)

Configuration: All ports and settings are in .env - edit to customize.

Features

✅ Implemented

• Transparent Cost Breakdown: See total interest, PMI costs, and hidden fees
• Real-time Calculations: Results update as you type with intelligent debouncing
• Extra Payment Modeling: See the true impact of paying extra principal monthly or yearly
• Pin & Compare: Save multiple scenarios for side-by-side comparison
• Rate Range Visualization: Interactive chart showing monthly payment across interest rates
• Dark Mode Support: Seamless dark mode UI for better user experience
• Responsive Design: Works flawlessly on desktop, tablet, and mobile
• Input Validation: Robust validation with clear, helpful error messages
• RESTful API: Clean JSON API for calculations and saved results
• Production Ready: Docker-based deployment with reverse proxy support

🔄 Planned Features

• User Authentication: Save calculations to user accounts for future reference
• Enhanced Visualizations: More detailed charts and graphs for payment breakdown over time
• PDF Export: Generate professional mortgage scenario reports
• Amortization Schedule View: Interactive table showing principal/interest breakdown by month
• Comparative Market Analysis: Compare with typical loan scenarios in your area

Technology Stack

Backend: Go + PostgreSQL

• Language: Go 1.21+ with Gin framework
• Database: PostgreSQL 16
• Architecture: Clean architecture with repository pattern
• API: RESTful JSON endpoints

Frontend: Next.js + React

• Framework: Next.js 15 (App Router) with TypeScript
• UI: Shadcn/ui components with Tailwind CSS
• State: TanStack Query for data fetching and caching
• Charts: Recharts for interactive visualizations
• Forms: React Hook Form with Zod validation

Infrastructure

• Containers: Docker with docker-compose orchestration
• Configuration: Environment-based (.env file) for easy customization
• Ports: Configurable via .env (defaults: Frontend 8911, Backend 8910)
• Proxy: Nginx reverse proxy ready for production deployment

Production (with Nginx reverse proxy)

The application is designed to work behind a reverse proxy. Example Nginx configuration for wthi.bros.ninja:

server {
    listen 443 ssl http2;
    server_name wthi.bros.ninja;

    location /api/ {
        proxy_pass http://sao:8910/api/;
    }

    location /health {
        proxy_pass http://sao:8910/health;
    }

    location / {
        proxy_pass http://sao:8911;
    }
}

See the nginx configuration above for deployment details.

API Endpoints

POST /api/v1/calculate

Calculate mortgage payment and costs

Request:

{
  "home_price": 300000,
  "down_payment_percent": 20,
  "loan_term_years": 30,
  "interest_rate": 6.5,
  "cash_savings": 100000,
  "moving_costs": 2000,
  "closing_cost_percent": 3,
  "extra_monthly_payment": 0,
  "extra_yearly_payment": 0
}

Response: Complete calculation results including monthly payment, total interest, PMI costs, amortization schedule, and more.

GET /health

Health check endpoint for monitoring

Key Features Explained

The Hidden Truth

Prominently displays what typical calculators hide:

• Total Interest Paid: The actual lifetime cost of borrowing
• Savings with 1% Lower Rate: Impact of rate shopping (encourages negotiation)
• Total PMI Cost: Hidden cost when down payment < 20%

Extra Payment Impact

Shows true benefits of paying extra:

• Interest Saved: Dollar amount saved over loan lifetime
• Years Saved: How much faster you'll pay off the loan
• Equivalent Rate: The rate you'd need without extra payments for the same total cost

Pin & Compare

• Save up to 5 scenarios simultaneously
• Compare different down payments, terms, and extra payment strategies
• Make informed decisions by seeing all options side-by-side

Project History: Technology Evolution

This project has been reimplemented across multiple technology stacks, demonstrating adaptability and continuous improvement:

1. Jupyter Notebook (Python) - Original Prototype

Initial proof-of-concept focused on mortgage calculation algorithms and data visualization.

2. Dash Framework (Python) - First Web Version

Migrated to Dash for interactive web-based calculations with Python's data science ecosystem.

3. Laravel + Vue 3 (PHP + JavaScript) - Full-Featured App

Complete rewrite with user authentication, Inertia.js SPA architecture, and Laravel Breeze.

• ✅ Added user accounts and authentication
• ✅ Implemented responsive UI with dark mode
• ❌ Calculator logic remained incomplete (placeholder implementations)

4. Go + Next.js (Current) - Production-Ready Refactor

Modern, performant implementation with correct calculations and production deployment.

• ✅ Accurate mortgage calculations with proper amortization formulas
• ✅ Better architecture: Separate concerns, RESTful API, clean architecture patterns
• ✅ Production ready: Docker containers, reverse proxy support, health checks
• ✅ Modern stack: Go for performance, Next.js for SEO, TypeScript for safety
• ✅ Developer experience: Hot reload, comprehensive logging, clear error messages

Each iteration improved performance, accuracy, and deployment strategy while exploring different ecosystems and architectural patterns.

Local Development (Outside Docker)

Backend

cd backend
go mod download
cp .env.example .env
go run cmd/api/main.go

Frontend

cd frontend
npm install
cp .env.local.example .env.local
npm run dev

Contributing

This is a portfolio/demonstration project showcasing full-stack development, system architecture, and DevOps practices.

Original Laravel/PHP version: Laravel-PHP-Version branch

Repository: mike/WhereTheHeartIs

License

MIT