Mortgage Repayment Explorer

A full-stack Python web application to calculate mortgage payments, generate amortization schedules, and explore extra-payment scenarios. It combines FastAPI as the backend API and Streamlit as the interactive frontend.

Table of Contents

1. Overview
2. Features
3. Architecture
4. Tech Stack
5. Installation
6. Running the Application
7. Usage
8. API Endpoints
9. Testing
10. Project Structure
11. Contributing
12. License

Overview

Mortgage Repayment Explorer is designed for homeowners, financial planners, and students to:

• Compute monthly payments for a mortgage.
• Generate a detailed amortization schedule.
• Explore the effect of extra payments (monthly or one-time) on interest and loan term.
• Visualize the mortgage repayment journey with interactive charts.

Features

• Monthly Payment Calculator: Computes fixed monthly payments for any principal, interest rate, and term.
• Amortization Schedule: Detailed breakdown showing each payment, principal, interest, extra payments, and remaining balance.
• Extra Payments Simulation: Add recurring or one-time extra payments to see the impact on total interest and loan duration.
• Interactive Charts: Visualize balance over time and interest vs principal per payment.
• Responsive Web UI: Built with Streamlit for easy exploration.

Architecture

+----------------+      +-----------------+      

|  Streamlit UI  | ---> |   FastAPI API   | --->  Mortgage Logic    

+----------------+      +-----------------+     

• Frontend (Streamlit): Collects user input, sends requests to backend, and displays results.
• Backend (FastAPI): Handles calculation requests, runs mortgage logic, and returns JSON responses.
• Mortgage Logic (mortgage.py): Contains reusable functions for monthly payment and amortization schedule calculations.

Tech Stack

• Python 3.13
• FastAPI – Backend API
• Streamlit – Frontend web interface
• Pandas & Matplotlib – Data manipulation and visualization
• Pydantic – Request/response validation
• Pytest – Unit and integration testing

Installation

1. Clone the repository:

       git clone https://github.com/yourusername/mortgage-repayment-explorer.git
       cd mortgage-repayment-explorer

2. Create a virtual environment (optional but recommended):

   For macOS/Linux

   python -m venv venv
   source venv/bin/activate   

   For Windows

   python -m venv venv
   venv\Scripts\activate      

3. Install dependencies:

   pip install -r requirements.txt

Running the Application

Start FastAPI backend:

uvicorn fastapi_app:app --reload --port 5000

• Runs on http://localhost:5000 by default.
• --reload allows automatic reload on code changes.

Start Streamlit frontend:

streamlit run streamlit_app.py

• Runs on http://localhost:8501 by default.
• Use the sidebar to configure FastAPI base URL if your backend runs on a different port.

Usage

1. Input mortgage parameters: Principal, annual interest rate (%), term in years.
2. Add extra payments: Optional monthly or one-time payments.
3. Click "Compute" to view:
   • Monthly payment summary
   • Full amortization schedule
   • Charts: remaining balance over time, interest vs principal per payment

API Endpoints

1. /calculate – Monthly Payment

   • Method: POST
   • Request JSON:

     {
         "principal": 300000,
         "annual_rate_pct": 3.5,
         "years": 30
     }

   • Response JSON:

     {
         "monthly_payment": 1347.13,
         "total_paid": 484966.8,
         "total_interest": 184966.8
     }

2. /amortization – Full Schedule

   • Method: POST
   • Request JSON:

     {
         "principal": 300000,
         "annual_rate_pct": 3.5,
         "years": 30,
         "extra_monthly": 100,
         "extra_payments": {"12": 5000}
     }

   • Response JSON:

     {
         "monthly_payment": 1347.13,
         "schedule": [
             {"payment_number": 1, "payment": 1347.13, "principal": 347.13, "interest": 1000, "extra_payment": 0, "balance": 299652.87},
             ...
         ],
         "total_interest": 180000,
         "total_paid": 480000,
         "num_payments": 350
     }

Testing

Run all tests (unit + integration):

   pytest -v

• Unit tests: Check mortgage.py logic.
• Integration tests: Verify API endpoints using FastAPI TestClient.
• Streamlit tests: Mock API calls to ensure frontend code doesn’t crash.

Project Structure

├── fastapi_app.py        # FastAPI backend
├── mortgage.py           # Mortgage calculation logic
├── streamlit_app.py      # Streamlit frontend
├── tests/                # Unit & integration tests
├── requirements.txt      # Dependencies
└── README.md             # Project documentation

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes & add tests
4. Run pytest to ensure tests pass
5. Submit a pull request

License

MIT License. See LICENSE file for details.