UrbanLenz - Housing Market Intelligence Platform

Version: 2.0
Status: ✅ Production Ready
Last Updated: December 2024

UrbanLenz is a comprehensive Canadian housing market intelligence platform providing 10-year historical analytics, AI-powered insights, and real-time data collection across 6 major cities and 99 neighborhoods.

🌐 Live Application: https://urbanlenz-prod.web.app
📄 Landing Page: https://urbanlenz-prod.web.app/landing
🔌 API Endpoint: https://urbanlenz-api-lizy7jaiza-uc.a.run.app

---

🚀 Quick Start

Prerequisites

• Node.js 20.x or later
• npm or yarn
• gcloud CLI + Firebase CLI

Start Local Development

# Clone and install
cd d:\dev\urbanLenz
npm install

# Terminal 1: Backend
cd backend
npm run dev  # http://localhost:3001

# Terminal 2: Frontend
cd frontend
npm run dev  # http://localhost:3000

Deploy to Production

# Deploy backend
.\deploy-backend-prod.ps1

# Deploy frontend
.\deploy-frontend-prod.ps1

# Deploy agents
cd backend
firebase deploy --only functions --project=urbanlenz-prod

See QUICKSTART.md for detailed instructions

---

📚 Documentation

Core Guides

Guide	Purpose
MASTER_DOCUMENTATION.md	Complete platform documentation
DEPLOYMENT_GUIDE.md	Deployment instructions (all environments)
QUICKSTART.md	Quick start guide

Feature-Specific Guides

Guide	Purpose
AI_AGENTS_GUIDE.md	20 AI agents - deployment & monitoring
UI_UX_GUIDE.md	Professional UI/UX enhancements
DATA_COLLECTION_GUIDE.md	Data sources & collection

Reference

Document	Purpose
ARCHITECTURE.md	Technical architecture
CHANGELOG.md	Version history
DESIGN_SYSTEM.md	UI design system
VALUE_STRATEGY.md	Product strategy

---

🎯 Key Features

10-Year Historical Analytics

• 40 Quarters of Data: Q1 2015 - Q4 2024
• Market Cycle Analysis: 5 complete phases
• 10-Year CAGR: Compound annual growth rates
• Interactive Charts: Timeline, cycles, comparisons

Professional AI Assistant

• Floating Interface: Always accessible
• Modal Design: Full-featured chat window
• Context-Aware: Knows city/neighborhood
• Smart Responses: GPT-4 powered

Automated Data Collection

• 20 AI Agents: Operating 24/7
• 10+ Data Sources: 100% FREE
• Self-Healing: Multi-source fallback
• Cost: $7/month (vs $2,000 premium)

Comprehensive Coverage

• 6 Cities: Toronto, Vancouver, Montreal, Calgary, Ottawa, Edmonton
• 99 Neighborhoods: Complete coverage
• 9,405 Data Points: Historical metrics
• 5 Market Cycles: Complete analysis

---

🏗️ Architecture

Stack

Frontend: Next.js 14 + React 18 + TypeScript + Tailwind CSS
Backend: Express + TypeScript + Firebase Functions
Database: Cloud Firestore + JSON files
Infrastructure: GCP + Firebase + Cloud Run
AI: OpenAI GPT-4 + 20 automated agents

Environments

Environment	Backend URL	Frontend URL	Purpose
Local	localhost:3001	localhost:3000	Development
Dev	urbanlenz-api-dev-*.run.app	urbanlenz-dev.web.app	Testing
Staging	staging-url	urbanlenz-staging.web.app	Pre-production
Production	urbanlenz-api-lizy7jaiza-uc.a.run.app	urbanlenz-prod.web.app	Live

---

📊 Project Status

Metric	Status
Version	2.0
Cities	6 (Toronto, Vancouver, Montreal, Calgary, Ottawa, Edmonton)
Neighborhoods	99 with complete data
Historical Data	40 quarters (10 years)
Data Points	9,405 across all metrics
AI Agents	20 deployed
Production	✅ Live
Monthly Cost	~$70-100

---

🛣️ Roadmap

Completed ✅

• 10-year historical data (40 quarters)
• 6 cities, 99 neighborhoods
• 20 AI data collection agents
• Professional UI/UX redesign
• Floating AI assistant
• Production deployment
• Firebase Authentication
• Cloud Firestore integration

In Progress 🔄

• Environment testing (local, staging, production)
• Custom domain configuration
• Additional data source integration
• Performance optimization

Planned 📋

• Neighborhood comparison tools
• Investment portfolio tracking
• Email alerts for market changes
• PDF report generation
• Mobile app (React Native)

---

🎨 UI/UX Highlights

Floating AI Assistant

• Always Accessible: Fixed position button
• Professional Modal: Gradient design, smooth animations
• Full-Featured: Chat history, suggestions, PDF export

Enhanced Landing Page

• Modern Hero: Dark gradient background, animated orbs
• Feature Grid: 6 cards with elegant hover effects
• Professional Typography: 60px headings, gradient text

Design System

• Colors: Sky blue gradients, dark slate backgrounds
• Typography: Inter font, 5 weight scales
• Spacing: 4px-64px scale
• Shadows: 4 levels with color glows

See UI_UX_GUIDE.md for details

---

🤖 AI Agent System

Categories

Housing Data (8 agents):

• CMHC, StatCan, Municipal (3 cities), Census, Open Data, Smart Fetcher

Economic Data (2 agents):

• Bank of Canada, Economic Indicators

Sentiment Analysis (2 agents):

• News & Sentiment, Community Sentiment

AI Enhancement (4 agents):

• Data Validator, Smart Fetcher, Health Monitor, Quality Checker

Main API (1 agent):

• Express Server

Scheduled Versions (8 agents):

• Automated cron jobs for all core agents

Deployment

# Deploy all 20 agents
cd backend
firebase deploy --only functions --project=urbanlenz-staging

# Test agent
Invoke-RestMethod -Uri "https://us-central1-urbanlenz-staging.cloudfunctions.net/cmhcAgent" -Method POST

See AI_AGENTS_GUIDE.md for complete guide

---

📡 API Endpoints

Core Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/api/cities	List all cities
GET	/api/cities/:id	City details
GET	/api/cities/:id/neighborhoods	Neighborhoods list
GET	/api/cities/:id/neighborhoods/:nid/metrics	10-year metrics
GET	/api/cities/:id/neighborhoods/:nid/opportunity-score	Opportunity score
POST	/api/chat	AI chat interface
POST	/api/insights	Generate insights

Example

# Get cities
Invoke-RestMethod -Uri "https://urbanlenz-api-lizy7jaiza-uc.a.run.app/api/cities"

# Get Toronto neighborhoods
Invoke-RestMethod -Uri "https://urbanlenz-api-lizy7jaiza-uc.a.run.app/api/cities/toronto/neighborhoods"

# Get Yorkville 10-year data
Invoke-RestMethod -Uri "https://urbanlenz-api-lizy7jaiza-uc.a.run.app/api/cities/toronto/neighborhoods/yorkville/metrics"

---

🔐 Security & Authentication

Authentication: Firebase Authentication (Email/Password)
Authorization: Firebase ID token verification
Network: HTTPS only, CORS configured
Data Protection: Firestore security rules
Input Validation: Zod schemas
Secrets: Firebase Functions config

---

💰 Cost Breakdown

Monthly Costs

Service	Cost
Cloud Functions	$0-10 (free tier covers most)
Cloud Run	$20-30
Firestore	$5-10
Firebase Hosting	$0 (free tier)
Firebase Auth	$0 (free tier)
AI Agents	$7-15
OpenAI API	$5-10 (optional)
Total	$70-100/month

Savings

Premium Data Alternatives: $2,000/month
UrbanLenz FREE Strategy: $7/month
Savings: $1,993/month (99.6% reduction!)

---

🧪 Testing

Manual Testing

# Backend health
Invoke-RestMethod -Uri "http://localhost:3001/health"

# Frontend
# Open http://localhost:3000
# Test: City selection, AI assistant, authentication

Automated Tests

# Backend tests
cd backend
npm test

# Frontend build test
cd frontend
npm run build

---

🐛 Troubleshooting

Backend won't start

cd backend
npm install
npm run build
npm run dev

Frontend won't start

cd frontend
npm install
rm -rf .next
npm run dev

CORS errors

• Check NEXT_PUBLIC_API_URL in .env.local
• Ensure backend allows frontend domain

Agent not responding

# Check function exists
firebase functions:list --project=urbanlenz-staging

# Redeploy
firebase deploy --only functions:cmhcAgent --project=urbanlenz-staging

See DEPLOYMENT_GUIDE.md for comprehensive troubleshooting

---

📝 Version History

v2.0 (December 2024):

• 10-year historical data (40 quarters)
• 20 AI data collection agents
• Professional UI/UX redesign
• 6 cities, 99 neighborhoods

v1.4.0 (November 2024):

• Firebase deployment
• Analytics integration
• Feedback system

v1.0.0 (Initial Release):

• 3 cities MVP
• Basic metrics
• Rule-based insights

See CHANGELOG.md for complete history

---

🤝 Contributing

Areas where contributions are welcome:

1. Data Integration: Connect additional data sources
2. AI Enhancement: Improve LLM prompts and agents
3. UI/UX: Mobile optimization, accessibility
4. Testing: Unit tests, integration tests
5. Documentation: Tutorials, API examples

---

📧 Support

• Documentation: See guides above
• Issues: Create GitHub issue
• Questions: Check inline code comments

---

📜 License

This project is for demonstration and educational purposes. Modify as needed for your use case.

---

Built with ❤️ for urban developers, investors, and municipalities seeking data-driven market intelligence.