CasaNova

CasaNova is a mobile-first web app that estimates buying price, rent, living area and related targets for a house from a photo and the user's location. The app helps users explore how they could afford a similar house over time.

This repository contains:

• frontend/ — React + Vite frontend (mobile-first UI).
• backend/ — Uvicorn/FastAPI backend that serves the API and the trained model.
• models/house_model/ — training code, dataset utilities, and model checkpoints.

This README summarizes the project, how to run it locally (dev & Docker), and how to train the model.

---

Project overview

CasaNova lets a user take a picture of a house and (using GPS -> ZIP lookup) predicts buying price, rent, rooms and area. The prediction pipeline:

• Input image (224×224) processed by a CNN (ResNet18 in our design).
• ZIP code is converted to a learned embedding and fused with image features.
• Fusion MLP produces separate heads for price, rent, rooms, and area.

See models/house_model/README.md for model-specific details and available checkpoints.

---

Inspiration & goal

• Help people evaluate a house they like by providing instant price/rent/size estimates from a phone photo and location.
• Provide tools to explore saving strategies and visualize when owning becomes financially feasible.

---

Quickstart (development)

Prerequisites

• Python 3.8+ (backend and model training)
• Node 16+ / npm or yarn (frontend dev)
• Docker & Docker Compose (optional but recommended for a complete local environment)
• (Optional) GPU + CUDA + matching PyTorch build for training speed

Backend (dev)

1. Create a virtual environment and install dependencies (from backend/requirements.txt):

cd backend
python -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

2. Run the backend API (Uvicorn):

# from repository root
cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000.

Frontend (dev)

1. Install node dependencies and start dev server:

cd frontend
npm install
npm run dev

2. Open the address shown by Vite (e.g. http://localhost:5173) on a mobile device or simulator. The frontend will communicate with the backend API (ensure backend is running and CORS is configured if needed).

Docker (compose)

• Development / quick local full-stack run (from repo root):

docker-compose up --build

• Production compose is available as docker-compose.prod.yml:

docker-compose -f docker-compose.prod.yml up -d --build

These will build the backend and frontend images and run them together.

---

Training the model

Training scripts and dataset utilities are in models/house_model/.

1. Prepare data

• The training script expects a metadata.json inside the dataset directory and images under images/<listing_id>/<image_id>.jpg.
• The project used the Interhyp/thinkimmo API to fetch listings (see models/house_model/fetch_data.py). If your data is missing, run the fetcher:

cd models\house_model
python fetch_data.py   # or use the provided fetch script/function (see file)

2. Train

• The training entrypoint is models/house_model/train.py.
• Example command (from repository root):

cd models\house_model
python train.py --data-dir data --epoch-from 1 --epoch-to 10 --batch-size 32

Available CLI flags (common):

• --data-dir : path to data (default: data inside models/house_model)
• --batch-size : batch size
• --epoch-from, --epoch-to : epoch range to run
• --checkpoint : path to checkpoint to resume from
• --save-dir : where to write checkpoints (default: checkpoints)
• --val-split : validation split ratio
• --fetch-data : attempt to fetch data if metadata is missing

Notes and suggestions

• If you have a GPU, ensure your installed PyTorch build matches the CUDA driver. See models/house_model/train.py for a CUDA diagnostics helper.

Checkpoints

• Trained model checkpoints and histories are saved under models/house_model/checkpoints by default.

---

How to use the app (user flow)

• Open the frontend app on a mobile device or a responsive browser.
• Allow the app to access your location (used to derive ZIP code via geoapify API).
• Take a picture of the house (the UI is mobile-first and guides camera usage).
• The app sends the photo and ZIP code to the backend; the backend returns estimated buying price, rent, rooms and area.
• You can then experiment with financial inputs (savings rate, age, graduation year) to visualize a realistic path toward owning a similar house.

---

Acknowledgements

• The idea and initial dataset gathering used the Interhyp/thinkimmo API.