House-price prediction as a small full-stack app. Upload a CSV (or fetch one by URL), store it in Postgres, explore it, train a scikit-learn regression model on it and ask the model for a price.
- Backend - FastAPI + SQLAlchemy, in backend/app/
- Frontend - Streamlit, in frontend/. Talks to the backend over HTTP only.
- Database - Postgres 17 (Docker locally, Neon when deployed)
Design notes and the course report: TECHNICAL_REPORT.md. Original plan: PLAN.md. Open problems: KNOWN_ISSUES.md.
- uv - installs Python 3.13 and all dependencies
- Docker - for the local Postgres
docker compose up -d # Postgres 17 on :5432, database "propertea"
cp .env.example .env
uv sync # runtime + dev deps (Streamlit is in the dev group)Then start the backend and the frontend in two terminals. Both must be running.
Terminal 1 - backend:
cd backend && uv run uvicorn app.main:app --reloadAPI docs at http://127.0.0.1:8000/docs.
Terminal 2 - frontend (from the repo root):
uv run streamlit run frontend/app.pyApp at http://localhost:8501.
Tables are created on backend startup by create_all in the FastAPI lifespan,
followed by a few idempotent ALTER TABLE statements (MIGRATIONS in
backend/app/main.py). There is no separate migration step.
- Create an account on the sign-in screen (username 3+ chars, password 8+ chars).
- Datasets -> Upload dataset. Upload
exploratory-data-analysis/data/train.csv
(Kaggle Ames House Prices) with target column
SalePrice. - Explore shows the target distribution, missingness and correlations.
- Train - pick an algorithm and train. Each run is saved; train several to compare.
- Predict - describe a house and get an estimated price.
Explore, Train and Predict need an Ames-shaped dataset (all Ames feature columns
plus SalePrice). Any other CSV opens in Prepare, where you can trim, rename,
reorder, cast, impute and filter columns, then save the result as a new dataset.
| Variable | Used by | Default |
|---|---|---|
DATABASE_URL |
backend | required; .env.example points at the Docker DB |
BACKEND_URL |
frontend | http://localhost:8000 |
.env is gitignored and per-machine. Never copy someone else's - the
credentials refer to their database, not yours.
A native Postgres (Homebrew, Postgres.app) will hold the port. Either stop it:
brew services stop postgresql@17 # match your installed versionor move the container and update DATABASE_URL in your .env to match:
ports: ["5433:5432"]Use Postgres 17 locally. CI and Neon both run 17; other versions are untested.
uv run pytest # in-memory SQLite, no Docker needed
uv run pytest --cov # same, with coverageCI (.github/workflows/ci.yml) runs the same suite
against a Postgres 17 service container on every push and PR to main. To do
that locally, point DATABASE_URL at a separate database - the fixtures
drop every table after each test:
docker compose exec db createdb -U postgres propertea_test
DATABASE_URL=postgresql://postgres:dev@localhost:5432/propertea_test uv run pytestAll routes except /health, /algorithms and /auth/* need the
X-Session-Id header with the token returned by register/login.
| Method | Path | Does |
|---|---|---|
| GET | /health |
liveness check |
| POST | /auth/register |
create account, returns token |
| POST | /auth/login |
returns a fresh token |
| POST | /auth/logout |
invalidates the token |
| POST | /datasets/upload |
multipart CSV upload (max 10 MB) |
| POST | /datasets/from-url |
backend downloads a CSV by URL |
| GET | /datasets |
your datasets |
| GET | /datasets/{id} |
metadata + paginated rows |
| GET | /algorithms |
trainable algorithm names |
| POST | /datasets/{id}/train |
train, store model + metrics |
| GET | /datasets/{id}/models |
models trained on a dataset |
| POST | /models/{id}/predict |
price for one house |
backend/app/
main.py FastAPI app, startup schema setup
db.py models.py engine/session, ORM tables
auth.py bcrypt hashing, token lookup
routers/ auth, datasets, models (train/predict)
services/ preprocessing.py (Ames), modeling.py (pipeline + training)
frontend/
app.py entry point, sidebar navigation
api_client.py every HTTP call to the backend
views/ one module per page
prep_ops.py pure pandas operations behind the Prepare page
eda_service.py plotting and EDA helpers
tests/ pytest suite (API, services, frontend helpers)
exploratory-data-analysis/
EDA notebooks (Ames, King County, Realtor) and raw CSVs
- Frontend - Streamlit Community Cloud, entry point
frontend/app.py. It installs frontend/requirements.txt, so a new frontend import must be added there as well as topyproject.toml. SetBACKEND_URLin the app's secrets. - Backend - any host that runs
uvicorn app.main:app --host 0.0.0.0 --port $PORTfrombackend/, withDATABASE_URLset to the Neon connection string.
Branch off main and open a PR back into main. CI must pass before merging.
| Prefix | Use |
|---|---|
feat/ |
new features |
fix/ |
bug fixes |
chore/ |
cleanup, config, docs |
Name the rest after the change: feat/dataset-upload, fix/cascade-delete.