Loan Logic: A Mortgage scenario modelling application

Background

I have always been interested in financial modelling and how different financial decisions can impact long term outcomes. Given I am a web developer, a while back I decided to make myself a mortgage managing app, and at the time I wrote the backend in PHP.

With the introduction of AI coding assistants, I thought it would be a great opportunity to:

1. refactor an old PHP application I had written into a Python/Cloud based application.
2. test the process of using Google’s Antigravity and VSCode Copilot to do a large refactor

Architecture

1. Frontend (Client & Serving)

• Technology: Vanilla JavaScript, TailwindCSS, DaisyUI.
• Serving: Nginx container acts as a web server, delivering static assets (HTML, JS, CSS) to the browser.
• Auth Handling:
  • after user logs in client receives a JWT (Access Token) that is stored in localStorage.
  • the ApiClient intercepts all requests and injects the Authorization: Bearer header.

2. Backend (Application API)

• Technology: Python FastAPI, running on Uvicorn.
• Authentication (Internal):
  • Uses python-jose for JWT encoding/decoding.
  • Uses passlib[argon2] for secure password hashing.

3. Database Layer

• Technology: Remote MySQL Database (managed externally, e.g., AWS RDS, Azure MySQL, or a VPS).
• ORM: SQLAlchemy handles object-relational mapping, translating Python objects to SQL queries.
• Migrations: Alembic manages database schema versioning (creating tables, altering columns) directly against the MySQL database.

A (fictitious) journey of home ownership and financial uncertainty

Now, to demonstrate a use case for the application with screen shots, I thought it would be good to step through how it might be used with an example.

Meet Sarah Thompson, a fictitious (and AI generated) Australian professional who is about to buy her first property in the Canberra suburb of Franklin.

Her financial situation was stable for a long period of time, and she was on track to pay off her mortgage in the standard 30 years. But as with everyone, financial circumstances changed over time. A few years into her home ownership and she gets a decent tax refund from the ATO. Then a few years later, her uncle Peter passes away and leaves her a small inheritance.

She also had some unexpected expenses over the course of her mortgage.

This became a roller coaster of financial ups and downs for Sarah and she needed a way to model different scenarios to see how these events impacted her mortgage.

Loan Logic

Sarah looked around for something that could give her an idea of how these large financial events would impact her mortgage. She couldn’t find anything that she liked (well she is a fictitious person, but you get the idea).

Since she actually worked in the tech industry and was comfortable spinning up applications with Docker and setting up backend databases, her friend suggested she try Loan Logic.

After setting up her MySQL database, and migrating the schema using Alembic she confirmed the tables were deployed.

She creates her .env file for the DB connection and then spins up the application with docker-compose up --build and opens up the service https://localhost:3000.

# .env
# Database Configuration
# Replace with your actual remote MySQL database connection details
DATABASE_URL=mysql+pymysql://your_username:your_password@your_mysql_host:3306/mortgage_app

# Authentication Configuration
SECRET_KEY=your-super-secret-jwt-key
ACCESS_TOKEN_EXPIRE_MINUTES=30

# docker-compose.yaml
version: '3.8'

services:
  # Backend API
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: loanlogic_backend
    env_file:
      - .env
    ports:
      - "8000:8000"
    volumes:
      - ./backend:/app
    networks:
      - loanlogic_network
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

  # Frontend
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    container_name: loanlogic_frontend
    ports:
      - "3000:80"
    depends_on:
      - backend
    networks:
      - loanlogic_network
    volumes:
      - ./frontend/src:/usr/share/nginx/html

networks:
  loanlogic_network:
    driver: bridge

After she registers, she confirms that new user in the users tables.

First she inputs the baseline mortgage parameters as was the case when she bought the property.

After doing all this she setups up a baseline scenario.

She clicks on the baseline scenario to see the mortgage payments over time.

She can see the mortgage payments over time decreasing the loan balance. She also now can track the cumulative interest paid. She is amazed that over the course of the 30 year mortgage she will pay more in interest than the original loan amount.

She then sets up a new scenario with the extra expenses and windfalls and clicks on the scenario tile to compare with the baseline scenario.

The way Loan Logic works is by tracking all events in a scenario as changes to an off-set account balance. In the chart below, the light blue line shows the offset account balance over time for the baseline scenario (flat on $0), and the dark blue line shows the offset account balance for the events scenario.

Sarah can now easily see that even with the extra expenses, the windfalls will allow her to pay off her mortgage in 28 years which will save her more than $82,000 in interest.