Full-stack real estate analytics: a React (Vite) dashboard (Figma-export UI) backed by the SubMarketIQ FastAPI service. Search metros, explore heatmap submarkets within each city, and view KPIs, trends, and fundamentals.

Upstream backend concepts and data pipeline live under SubmarketIQ/. The root app wires that API into the map, nav search, and filters.

• Node.js 18+ (for npm run dev / npm run build)
• Python 3.11+ with pip (for the FastAPI backend)

git clone https://github.com/aaravjj2/SubMarketIQ.git
cd SubMarketIQ
npm install

cp .env.example .env

Edit .env:

• VITE_GOOGLE_MAPS_API_KEY — Maps JavaScript API key (Google Cloud Console)
• VITE_SUBMARKETIQ_API_URL — default http://127.0.0.1:8000, or /submarketiq if you use the Vite dev proxy (see vite.config.ts)

cd SubmarketIQ/backend
cp .env.example .env

Set API keys as needed (e.g. FRED_API_KEY, CENSUS_API_KEY) for live connectors. The app runs with fixtures when keys are missing.

cd SubmarketIQ/backend
pip install -r requirements.txt

Terminal A — API

cd SubmarketIQ/backend
python -m uvicorn main:app --reload --host 127.0.0.1 --port 8000

From repo root you can use:

npm run backend

Terminal B — dashboard

npm run dev

Open the URL Vite prints (usually http://localhost:5173), go to Map, and use the top search bar or filters.

• Metro search — suggestions from /markets/top; deep link /map?q=Austin%2C%20TX
• Submarkets — per-metro heatmap_points as clickable zones + ranked list in the side panel
• KPIs & charts — metro-level time series; zone-level stats when a submarket is selected

Key routes (see SubmarketIQ/backend/main.py):

• GET /health — health + market count
• GET /markets/top — all fixture metros
• GET /market/{city} — resolve + snapshot
• GET /market/{city}/live — live pipeline (requires connector keys)
• GET /sources — connector status

npm run build
npm run preview   # optional local preview of dist/

Serve dist/ behind your static host; set VITE_SUBMARKETIQ_API_URL to your deployed API origin and configure CORS on the backend (SUBMARKETIQ_CORS_ORIGINS).

• Do not commit .env files. Keys belong in environment variables or secret managers.
• Restrict Google Maps keys by HTTP referrer; rotate any key that was exposed.

Add a LICENSE file if you want to open-source under a specific terms.

Issues and PRs welcome on GitHub.