Roommates and Housing Matching for Virginia Tech

Bed-A-Thon helps VT students find compatible roommates and discover apartments that fit their preferences (budget, bedrooms, distance, amenities). It combines a modern Next.js frontend with a FastAPI backend, Supabase integration, and a local SQLite fallback for development.

• 🔗 Roommate matching based on lifestyle preferences, budget, year, and major
• 🏘 Apartment matching by distance to VT, bedrooms, budget fit, and amenity overlap
• 🎨 Clean, responsive UI built with Shadcn UI + Tailwind CSS
• 🔑 OAuth sign-in with Google (via Supabase Auth)
• 🗄 Supabase profiles with optional local SQLite for development
• 📞 Voice call integration (optional) to “get the latest info” from an apartment

Frontend (frontend/)

• Framework: Next.js (App Router), React, TypeScript
• Styling: Tailwind CSS + Shadcn UI
• Auth: Supabase Auth

Backend (backend/)

• Framework: FastAPI (Uvicorn)
• Data: Supabase (production) or SQLite (development fallback)
• Matching: Python algorithms for roommates and apartments

Data Sources

• Apartment data: imported from VT JSON sources or Supabase DB
• Profiles: stored in Supabase profiles table via backend APIs

Roommate Matching (default weights)

• Lifestyle vector (cleanliness, noise, study, social, sleep): 50%
• Budget proximity: 25%
• Year match: 10%
• Major similarity: 15%

Formula:
score = 0.50*lifestyle + 0.25*budget + 0.10*year + 0.15*major

Apartment Matching (default weights)

• Price fit: 35% (best within ±10% of budget)
• Distance to VT: 30% (best near 0.5 miles)
• Amenity overlap: 20% (Laundry, Parking, WiFi bonuses)
• Study-friendliness: 10% (WiFi + no pool if study-focused)
• Parking: 5%

• Node.js 18+
• Python 3.10+
• Supabase project (optional for local dev; required for full profiles)
• macOS/Linux recommended

Create:

• frontend/.env.local
• backend/.env

💡 For local dev, omit DATABASE_URL to use sqlite:///./bedathon.db.

Backend

cd backend
pip install -r requirements.txt
uvicorn main:app --reload

Frontend

cd frontend
npm install
npm run dev

cd backend
python import_apartments_to_db.py

1. Click "Sign in with Google" on the landing page
2. Complete onboarding form (budget, bedrooms, preferences)
3. Backend creates/updates Supabase profile
4. Access Roommate Matches and Apartment Matches tabs

Base URL: http://localhost:8000

• GET /health → Health check
• POST /profiles → Create/update profile
• GET /profiles/me → Fetch current profile
• PUT /profiles/me → Update profile

• POST /matching/roommate-preferences → Save preferences
• POST /matching/roommate-matches → Get roommate matches
• POST /matching/apartment-matches-for-preferences → Get apartment matches
• GET /matching/apartment-matches/{profile_id}?limit=100 → Matches for profile
• GET /matching/apartments → All apartments

Note: Voice call endpoint exists in codebase but may be disabled.

HokieNest includes an intelligent AI agent that streamlines the apartment hunting process:

• Automated Calling → Agent calls apartments that roommates have selected
• Information Gathering → Collects current pricing, bedroom availability, amenities, and lease terms
• Summary Generation → Creates comprehensive email summaries with all collected details
• Real-time Updates → Ensures apartment information is current and accurate

The AI agent eliminates the need for students to make multiple phone calls, saving time and providing standardized information across all potential housing options.

• Onboarding → Form for budget, bedrooms, lifestyle preferences
• Roommate Matches → Grid with compatibility badges
• Apartment Matches → Price, distance, amenity badges + "why it matches" reasons

• Next.js auto-increments ports (3000 → 3001…)
• Ensure NEXT_PUBLIC_BACKEND_URL matches backend (default: 8000)

• SQLite: Omit DATABASE_URL for local SQLite
• Reset: Delete/recreate bedathon.db if errors occur
• Supabase Postgres: Use actual DB credentials, not service role key

• If /profiles returns 401, re-login and check Bearer token is sent

• Save/Like apartments and roommate profiles
• Group-based housing recommendations
• Map view with filters by distance/amenities
• Availability and contact integration per apartment

Add screenshots to frontend/public/ and embed them here:

![Landing Page](frontend/public/screenshots/landing.png)
![Onboarding](frontend/public/screenshots/onboarding.png)
![Roommate Matches](frontend/public/screenshots/roommate-matches.png)
![Apartment Matches](frontend/public/screenshots/apartment-matches.png)

1. Fork this repo
2. Create a feature branch (git checkout -b feature/my-feature)
3. Run linters/tests before pushing
4. Open a PR with description + screenshots if UI changes

MIT (or your preferred license)

• Next.js
• Tailwind CSS
• Shadcn UI
• FastAPI
• SQLModel / SQLAlchemy
• Supabase
• VT community datasets and housing resources