IV Housing Platform — Proof of Concept

A centralized housing intelligence platform for UCSB students that aggregates listings, extracts structured attributes using NLP, and provides a map-first search experience.

Features

• Automated Data Ingestion: Scrapes and normalizes listings from multiple sources
• NLP Extraction: Extracts structured attributes (rent, parking, utilities, laundry, etc.) with evidence
• Net Cost Modeling: Calculates true monthly cost including parking and utilities
• Map-First UI: Interactive map with filterable listings
• Admin Tools: Review and correction interface for maintaining data quality

Project Structure

ucsbHousing/
├── backend/           # FastAPI backend
│   ├── app/
│   │   ├── models/    # Database models
│   │   ├── api/       # API endpoints
│   │   ├── services/  # Business logic
│   │   └── nlp/       # NLP extraction engine
│   └── requirements.txt
├── frontend/          # React frontend
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   └── services/
│   └── package.json
└── README.md

Setup

Backend

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend

cd frontend
npm install
npm start

Quick Start

See QUICKSTART.md for a 5-minute setup guide.

Development Status

This is a proof of concept focusing on correctness, transparency, and extensibility.

Key Features

✅ NLP Extraction: Automatically extracts structured attributes (rent, parking, utilities, laundry, etc.) from unstructured text
✅ Net Cost Modeling: Calculates true monthly cost including parking and estimated utilities
✅ Map-First UI: Interactive map with filterable listings
✅ Admin Tools: Review and correct low-confidence extractions
✅ Evidence Tracking: Every extracted field includes confidence score and source evidence
✅ Deduplication: Detects duplicate listings based on address and price similarity

Architecture Highlights

• Backend: FastAPI with SQLAlchemy ORM
• Frontend: React with Leaflet maps
• NLP: Regex-based pattern matching (extensible to transformer models)
• Database: SQLite for POC (easily upgradeable to PostgreSQL)
• Geocoding: Nominatim/OpenStreetMap (can use Google Maps API)

Documentation

• SETUP.md - Detailed setup and configuration guide
• QUICKSTART.md - Quick start guide
• INFO.md - File structure and component documentation
• NEXT_STEPS.md - Development roadmap
• TROUBLESHOOTING.md - Common issues and solutions
• API Documentation: http://localhost:8000/docs (when backend is running)