Skip to content

codinggita/neighborhoodIQ

BranchesTags

Repository files navigation

🏠 NeighborhoodIQ – Neighborhood Intelligence Platform

License: MIT Node.js React MongoDB Docker Code Style: Prettier

Data-driven neighborhood analysis for smarter real estate decisions

🚀 Quick Start • 📚 Documentation • 🐛 Report Bug • 💡 Request Feature

📋 Table of Contents

🎯 Overview

NeighborhoodIQ transforms fragmented neighborhood data into actionable insights. Homebuyers, real estate investors, and urban planners can now make data-driven decisions by evaluating neighborhoods through a standardized, transparent scoring system.

Unlike price-focused platforms, NeighborhoodIQ emphasizes the factors that truly impact quality of life: safety, air quality, healthcare access, education, infrastructure, and water quality.

Why NeighborhoodIQ?

Real estate is the largest purchase most people make, yet neighborhood evaluation relies heavily on subjective opinions and incomplete data. NeighborhoodIQ solves this by:

  • ✅ Aggregating 6+ data sources into one unified platform
  • ✅ Standardizing neighborhood metrics with a transparent 0–10 scoring system
  • ✅ Eliminating information asymmetry in real estate transactions
  • ✅ Empowering buyers, sellers, and planners with institutional-grade insights
  • ✅ Open-source & transparent algorithms you can audit and understand

❗ Problem & Solution

The Problem

When homebuyers evaluate properties, they focus on price, size, and amenities. Critical neighborhood factors remain scattered:

  • 🛡️ Safety data fragmented across police departments and FBI databases
  • 🌫️ Air quality only accessible through specialized environmental tools
  • 🏥 Healthcare & schools buried in Google searches
  • 🚧 Infrastructure not easily quantifiable
  • 💧 Water quality rarely considered

This information asymmetry leads to suboptimal decisions and hidden risks discovered only after purchase.

The Solution

NeighborhoodIQ provides a standardized Neighborhood Intelligence System combining 7 key metrics into a single score:

Metric Weight Data Source Impact
🛡️ Safety 30% FBI Crime Data Highest impact on daily life
🌫️ Air Quality 20% OpenAQ API Health implications
🏥 Healthcare 15% Google Places Critical for families
🎓 Education 15% School APIs Long-term value
🚧 Infrastructure 10% OpenStreetMap Enables mobility
💧 Water Quality 5% EPA SDWIS Health baseline
🚶 Walkability 5% Walk Score Lifestyle quality

Score Result: 0–10 rating with color-coded grade (🟢 Excellent → 🔴 Poor)

✨ Key Features

🔍 Smart Search

  • Auto-complete with geolocation detection
  • Full-text search across 50,000+ neighborhoods
  • Recent search history & saved favorites
  • Map-based discovery with zoom levels

📊 Comprehensive Scores

  • Color-coded 0–10 rating system
  • Interactive radar chart showing all 6 dimensions
  • Factor-by-factor breakdown with trend indicators
  • Historical score progression over 12 months
  • Peer comparison (how your area ranks)

🗺️ Interactive Map

  • Real-time facility layer toggles (hospitals, schools, transit, police)
  • Heat map overlays for crime and air quality
  • Facility search radius slider
  • Street-level view integration
  • Custom markers for neighborhoods

⚖️ Comparison Tool

  • Compare up to 3 neighborhoods side-by-side
  • Metric-by-metric comparison table
  • Winner badges highlighting best area in each category
  • Export comparison as PDF
  • Saved comparisons to account

💬 Community Reviews

  • Star-rated resident reviews
  • Verified purchase badges
  • Photo uploads in reviews
  • Helpful/Not helpful voting
  • Moderated content

🔐 User Dashboard

  • Saved areas & favorites
  • My reviews section
  • Bookmarked comparisons
  • Activity log
  • Personalized recommendations

🛠️ Admin Panel

  • Data management & refresh
  • User analytics
  • Content moderation
  • System health monitoring
  • Audit logs

🛠️ Tech Stack

Frontend

  • React 18 – UI library
  • Vite – Lightning-fast bundler
  • Tailwind CSS 3.0 – Utility-first styling
  • Redux Toolkit – State management
  • React Query – Server state management
  • Leaflet.js + Mapbox – Interactive mapping
  • Recharts – Data visualization
  • React Hook Form – Form handling
  • Zod – Schema validation

Backend

  • Node.js 18+ – Runtime
  • Express.js 4.x – HTTP server
  • MongoDB 7.0 – Document database
  • Mongoose 8.x – ODM layer
  • Redis 7.x – Caching layer
  • JWT – Authentication
  • node-cron – Job scheduling
  • Winston – Structured logging

External APIs

  • OpenAQ – Air Quality Index (AQI)
  • FBI Crime Data – Crime statistics
  • Google Places – Hospitals, schools, transit
  • Mapbox – Maps & geocoding
  • Walk Score – Walkability metrics
  • OpenWeather – Environmental data

DevOps & Infrastructure

  • Docker & Docker Compose – Containerization
  • GitHub Actions – CI/CD pipeline
  • Jest & Supertest – Testing framework
  • ESLint & Prettier – Code quality

🚀 Quick Start

Prerequisites

Installation (5 minutes)

1️⃣ Clone Repository

git clone https://github.com/yourname/NeighborhoodIQ.git
cd NeighborhoodIQ

2️⃣ Install Dependencies

npm install                          # Root dependencies
cd client && npm install && cd ..    # Frontend
cd server && npm install && cd ..    # Backend

3️⃣ Setup Environment Variables

cp server/.env.example server/.env
cp client/.env.example client/.env

Edit files with your API keys:

nano server/.env
nano client/.env

4️⃣ Start Database Services

docker-compose up -d mongodb redis

5️⃣ Run Development Servers

npm run dev

This starts:

Environment Variables Required

server/.env

PORT=5000
NODE_ENV=development
MONGO_URI=mongodb://localhost:27017/NeighborhoodIQ
REDIS_URL=redis://localhost:6379
JWT_SECRET=your_secret_key_min_32_chars
JWT_EXPIRES_IN=7d
OPENAQ_API_KEY=your_key
GOOGLE_PLACES_API_KEY=your_key
MAPBOX_TOKEN=your_token
WALKSCORE_API_KEY=your_key
OPENWEATHER_API_KEY=your_key

client/.env

VITE_API_BASE_URL=http://localhost:5000/api/v1
VITE_MAPBOX_TOKEN=your_token
VITE_GOOGLE_MAPS_KEY=your_key

📁 Project Structure

NeighborhoodIQ/
│
├── 📁 client/                          # React Frontend (Vite)
│   ├── 📁 public/
│   │   ├── favicon.ico
│   │   ├── logo.png
│   │   └── robots.txt
│   │
│   ├── 📁 src/
│   │   │
│   │   ├── 📁 assets/                  # Static assets
│   │   │   ├── 📁 images/
│   │   │   ├── 📁 icons/
│   │   │   └── 📁 fonts/
│   │   │
│   │   ├── 📁 components/              # Reusable UI Components
│   │   │   ├── 📁 common/
│   │   │   │   ├── Button.jsx
│   │   │   │   ├── Input.jsx
│   │   │   │   ├── Modal.jsx
│   │   │   │   ├── Loader.jsx
│   │   │   │   ├── Badge.jsx
│   │   │   │   ├── Card.jsx
│   │   │   │   ├── Tooltip.jsx
│   │   │   │   └── index.js
│   │   │   │
│   │   │   ├── 📁 layout/
│   │   │   │   ├── Navbar.jsx
│   │   │   │   ├── Footer.jsx
│   │   │   │   ├── Sidebar.jsx
│   │   │   │   ├── PageWrapper.jsx
│   │   │   │   └── index.js
│   │   │   │
│   │   │   ├── 📁 map/
│   │   │   │   ├── MapView.jsx          # Leaflet map container
│   │   │   │   ├── MapMarker.jsx        # Custom markers
│   │   │   │   ├── MapPopup.jsx         # Info popups
│   │   │   │   ├── MapLegend.jsx        # Map legend
│   │   │   │   ├── FacilityLayer.jsx    # Hospitals, Schools on map
│   │   │   │   └── index.js
│   │   │   │
│   │   │   ├── 📁 charts/
│   │   │   │   ├── AQIChart.jsx         # Air quality trend chart
│   │   │   │   ├── CrimeChart.jsx       # Crime rate bar chart
│   │   │   │   ├── ScoreRadarChart.jsx  # Radar chart for scores
│   │   │   │   ├── TrendLineChart.jsx   # Area growth trend
│   │   │   │   ├── CompareBarChart.jsx  # Area comparison chart
│   │   │   │   └── index.js
│   │   │   │
│   │   │   ├── 📁 score/
│   │   │   │   ├── ScoreCard.jsx        # Main score display card
│   │   │   │   ├── ScoreGauge.jsx       # Circular gauge widget
│   │   │   │   ├── ScoreBreakdown.jsx   # Factor-wise breakdown
│   │   │   │   ├── ScoreBadge.jsx       # Color-coded badge
│   │   │   │   └── index.js
│   │   │   │
│   │   │   ├── 📁 search/
│   │   │   │   ├── SearchBar.jsx        # Main search input
│   │   │   │   ├── SearchSuggestions.jsx
│   │   │   │   ├── SearchFilters.jsx    # Filter panel
│   │   │   │   ├── RecentSearches.jsx
│   │   │   │   └── index.js
│   │   │   │
│   │   │   ├── 📁 compare/
│   │   │   │   ├── ComparePanel.jsx     # Side-by-side compare
│   │   │   │   ├── CompareSelector.jsx  # Area selector
│   │   │   │   ├── CompareTable.jsx     # Metric table
│   │   │   │   └── index.js
│   │   │   │
│   │   │   └── 📁 reviews/
│   │   │       ├── ReviewCard.jsx
│   │   │       ├── ReviewForm.jsx
│   │   │       ├── ReviewList.jsx
│   │   │       ├── StarRating.jsx
│   │   │       └── index.js
│   │   │
│   │   ├── 📁 pages/                   # Route-level Pages
│   │   │   ├── 📁 Home/
│   │   │   │   ├── index.jsx            # Landing page
│   │   │   │   ├── HeroSection.jsx
│   │   │   │   ├── FeaturesSection.jsx
│   │   │   │   ├── HowItWorks.jsx
│   │   │   │   └── TopAreas.jsx         # Featured top areas
│   │   │   │
│   │   │   ├── 📁 AreaDetail/
│   │   │   │   ├── index.jsx            # Main area detail page
│   │   │   │   ├── AreaHeader.jsx       # Area name + score hero
│   │   │   │   ├── OverviewTab.jsx
│   │   │   │   ├── SafetyTab.jsx
│   │   │   │   ├── EnvironmentTab.jsx
│   │   │   │   ├── InfrastructureTab.jsx
│   │   │   │   └── ReviewsTab.jsx
│   │   │   │
│   │   │   ├── 📁 Search/
│   │   │   │   ├── index.jsx            # Search results page
│   │   │   │   ├── ResultsGrid.jsx
│   │   │   │   └── FilterSidebar.jsx
│   │   │   │
│   │   │   ├── 📁 Compare/
│   │   │   │   └── index.jsx            # Area comparison page
│   │   │   │
│   │   │   ├── 📁 Dashboard/
│   │   │   │   ├── index.jsx            # User dashboard
│   │   │   │   ├── SavedAreas.jsx
│   │   │   │   ├── MyReviews.jsx
│   │   │   │   └── ActivityLog.jsx
│   │   │   │
│   │   │   ├── 📁 Auth/
│   │   │   │   ├── Login.jsx
│   │   │   │   ├── Register.jsx
│   │   │   │   └── ForgotPassword.jsx
│   │   │   │
│   │   │   ├── 📁 Admin/
│   │   │   │   ├── index.jsx            # Admin panel
│   │   │   │   ├── ManageAreas.jsx
│   │   │   │   ├── ManageUsers.jsx
│   │   │   │   ├── DataRefresh.jsx      # Trigger data sync
│   │   │   │   └── Analytics.jsx
│   │   │   │
│   │   │   ├── NotFound.jsx
│   │   │   └── ServerError.jsx
│   │   │
│   │   ├── 📁 hooks/                   # Custom React Hooks
│   │   │   ├── useAreaSearch.js
│   │   │   ├── useNeighborhoodScore.js
│   │   │   ├── useGeolocation.js
│   │   │   ├── useAQIData.js
│   │   │   ├── useCrimeData.js
│   │   │   ├── useCompare.js
│   │   │   ├── useAuth.js
│   │   │   ├── useDebounce.js
│   │   │   └── useLocalStorage.js
│   │   │
│   │   ├── 📁 store/                   # Redux Toolkit State Management
│   │   │   ├── index.js                 # Store configuration
│   │   │   ├── 📁 slices/
│   │   │   │   ├── authSlice.js
│   │   │   │   ├── areaSlice.js
│   │   │   │   ├── searchSlice.js
│   │   │   │   ├── compareSlice.js
│   │   │   │   ├── reviewSlice.js
│   │   │   │   └── uiSlice.js
│   │   │   └── 📁 api/                 # RTK Query API slices
│   │   │       ├── areaApi.js
│   │   │       ├── authApi.js
│   │   │       ├── reviewApi.js
│   │   │       └── scoreApi.js
│   │   │
│   │   ├── 📁 services/                # API call functions
│   │   │   ├── api.js                   # Axios base instance
│   │   │   ├── areaService.js
│   │   │   ├── authService.js
│   │   │   ├── scoreService.js
│   │   │   ├── reviewService.js
│   │   │   └── mapService.js
│   │   │
│   │   ├── 📁 utils/                   # Helper functions
│   │   │   ├── scoreCalculator.js       # Client-side score logic
│   │   │   ├── formatters.js            # Date, number formatters
│   │   │   ├── validators.js            # Form validators
│   │   │   ├── constants.js             # App-wide constants
│   │   │   ├── colorHelpers.js          # Score → color mapping
│   │   │   └── geoHelpers.js            # Lat/lng utilities
│   │   │
│   │   ├── 📁 context/                 # React Context (lightweight)
│   │   │   ├── ThemeContext.jsx
│   │   │   ├── MapContext.jsx
│   │   │   └── AuthContext.jsx
│   │   │
│   │   ├── 📁 routes/                  # Route definitions
│   │   │   ├── AppRouter.jsx
│   │   │   ├── PrivateRoute.jsx
│   │   │   ├── AdminRoute.jsx
│   │   │   └── routes.js               # Route path constants
│   │   │
│   │   ├── 📁 styles/                  # Global styles
│   │   │   ├── index.css               # Tailwind base imports
│   │   │   ├── variables.css           # CSS custom properties
│   │   │   └── animations.css
│   │   │
│   │   ├── 📁 config/
│   │   │   └── appConfig.js            # App-level config (env vars)
│   │   │
│   │   ├── App.jsx
│   │   └── main.jsx
│   │
│   ├── .env
│   ├── .env.example
│   ├── index.html
│   ├── vite.config.js
│   ├── tailwind.config.js
│   ├── postcss.config.js
│   └── package.json
│
│
├── 📁 server/                          # Node.js + Express Backend
│   │
│   ├── 📁 src/
│   │   │
│   │   ├── 📁 config/                  # Configuration files
│   │   │   ├── db.js                    # MongoDB connection
│   │   │   ├── redis.js                 # Redis connection
│   │   │   ├── env.js                   # Env variable loader
│   │   │   ├── cors.js                  # CORS config
│   │   │   └── logger.js               # Winston logger setup
│   │   │
│   │   ├── 📁 models/                  # Mongoose Models
│   │   │   ├── User.model.js
│   │   │   ├── Area.model.js
│   │   │   ├── NeighborhoodScore.model.js
│   │   │   ├── CrimeData.model.js
│   │   │   ├── AQIData.model.js
│   │   │   ├── Review.model.js
│   │   │   ├── SavedArea.model.js
│   │   │   └── AuditLog.model.js
│   │   │
│   │   ├── 📁 controllers/             # Request handlers
│   │   │   ├── auth.controller.js
│   │   │   ├── area.controller.js
│   │   │   ├── score.controller.js
│   │   │   ├── crime.controller.js
│   │   │   ├── aqi.controller.js
│   │   │   ├── review.controller.js
│   │   │   ├── compare.controller.js
│   │   │   ├── user.controller.js
│   │   │   └── admin.controller.js
│   │   │
│   │   ├── 📁 routes/                  # Express Routes
│   │   │   ├── index.js                 # Route aggregator
│   │   │   ├── auth.routes.js
│   │   │   ├── area.routes.js
│   │   │   ├── score.routes.js
│   │   │   ├── crime.routes.js
│   │   │   ├── aqi.routes.js
│   │   │   ├── review.routes.js
│   │   │   ├── compare.routes.js
│   │   │   ├── user.routes.js
│   │   │   └── admin.routes.js
│   │   │
│   │   ├── 📁 services/                # Business Logic Layer
│   │   │   ├── auth.service.js
│   │   │   ├── area.service.js
│   │   │   ├── score.service.js         # Core scoring algorithm
│   │   │   ├── crime.service.js
│   │   │   ├── aqi.service.js
│   │   │   ├── water.service.js
│   │   │   ├── healthcare.service.js
│   │   │   ├── education.service.js
│   │   │   ├── infrastructure.service.js
│   │   │   ├── review.service.js
│   │   │   ├── compare.service.js
│   │   │   └── notification.service.js
│   │   │
│   │   ├── 📁 integrations/            # Third-party API integrations
│   │   │   ├── 📁 openaq/
│   │   │   │   ├── openaq.client.js     # OpenAQ API client
│   │   │   │   └── openaq.mapper.js     # Response normalizer
│   │   │   │
│   │   │   ├── 📁 fbi/
│   │   │   │   ├── fbi.client.js        # FBI Crime Data API
│   │   │   │   └── fbi.mapper.js
│   │   │   │
│   │   │   ├── 📁 google/
│   │   │   │   ├── places.client.js     # Google Places API
│   │   │   │   └── places.mapper.js
│   │   │   │
│   │   │   ├── 📁 mapbox/
│   │   │   │   ├── mapbox.client.js
│   │   │   │   └── mapbox.mapper.js
│   │   │   │
│   │   │   ├── 📁 walkscore/
│   │   │   │   ├── walkscore.client.js
│   │   │   │   └── walkscore.mapper.js
│   │   │   │
│   │   │   └── 📁 openweather/
│   │   │       ├── weather.client.js
│   │   │       └── weather.mapper.js
│   │   │
│   │   ├── 📁 middleware/              # Express Middleware
│   │   │   ├── auth.middleware.js       # JWT verification
│   │   │   ├── admin.middleware.js      # Admin role check
│   │   │   ├── rateLimiter.middleware.js
│   │   │   ├── cache.middleware.js      # Redis caching
│   │   │   ├── validate.middleware.js   # Request validation
│   │   │   ├── errorHandler.middleware.js
│   │   │   └── requestLogger.middleware.js
│   │   │
│   │   ├── 📁 validators/              # Joi/Zod validation schemas
│   │   │   ├── auth.validator.js
│   │   │   ├── area.validator.js
│   │   │   ├── review.validator.js
│   │   │   └── search.validator.js
│   │   │
│   │   ├── 📁 jobs/                    # Scheduled / Background Jobs
│   │   │   ├── scheduler.js             # node-cron job runner
│   │   │   ├── syncAQI.job.js           # Daily AQI data sync
│   │   │   ├── syncCrime.job.js         # Weekly crime data sync
│   │   │   ├── recalculateScores.job.js # Nightly score recalc
│   │   │   └── cleanupLogs.job.js       # Log cleanup
│   │   │
│   │   ├── 📁 utils/
│   │   │   ├── ApiError.js              # Custom error class
│   │   │   ├── ApiResponse.js           # Standard response wrapper
│   │   │   ├── asyncHandler.js          # Try-catch wrapper
│   │   │   ├── scoreWeights.js          # Scoring weight constants
│   │   │   ├── geoUtils.js              # Haversine & geo helpers
│   │   │   ├── tokenUtils.js            # JWT helpers
│   │   │   └── emailUtils.js            # Email templates
│   │   │
│   │   ├── 📁 constants/
│   │   │   ├── httpStatus.js
│   │   │   ├── scoreFactors.js
│   │   │   └── messages.js
│   │   │
│   │   └── app.js                       # Express app setup
│   │
│   ├── 📁 tests/                       # Backend Tests
│   │   ├── 📁 unit/
│   │   │   ├── score.service.test.js
│   │   │   ├── aqi.service.test.js
│   │   │   └── auth.service.test.js
│   │   ├── 📁 integration/
│   │   │   ├── area.routes.test.js
│   │   │   └── auth.routes.test.js
│   │   └── setup.js
│   │
│   ├── server.js                        # Entry point
│   ├── .env
│   ├── .env.example
│   ├── .eslintrc.js
│   └── package.json
│
│
├── 📁 shared/                          # Shared between client & server
│   ├── constants.js                     # Shared constants
│   ├── scoreFormulas.js                 # Score math (reused both sides)
│   └── types.js                         # JSDoc type definitions
│
├── 📁 docs/                            # Documentation
│   ├── API.md                           # REST API documentation
│   ├── SCORING_ALGORITHM.md             # How scoring works
│   ├── SETUP.md                         # Local dev setup guide
│   └── ARCHITECTURE.md
│
├── 📁 scripts/                         # Dev/Ops utility scripts
│   ├── seed.js                          # Database seeder
│   ├── migrate.js                       # DB migration runner
│   └── generateMockData.js
│
├── .gitignore
├── .prettierrc
├── .eslintrc.js
├── docker-compose.yml                   # Docker setup (MongoDB + Redis)
├── README.md
└── package.json                         # Root (monorepo scripts)

🧮 Scoring Algorithm

The Neighborhood Score (0–10) combines 7 normalized metrics with semantic weighting.

Calculation Formula

NeighborhoodIQ = (S × 0.30) + (AQ × 0.20) + (H × 0.15) + (E × 0.15) + (I × 0.10) + (W × 0.05) + (WK × 0.05)

Where:

  • S = Safety score (crime rate, normalized to 0–10)
  • AQ = Air Quality (AQI value, normalized to 0–10)
  • H = Healthcare access (hospital proximity, count)
  • E = Education (school ratings, normalized)
  • I = Infrastructure (transit, roads, utilities)
  • W = Water quality (contamination levels)
  • WK = Walkability (Walk Score API)

Grade Scale

Score Grade Color Meaning
8.5–10.0 Excellent 🟢 Green Premier neighborhood
7.0–8.4 Good 🟡 Lime Desirable area
5.5–6.9 Average 🟡 Yellow Mixed characteristics
4.0–5.4 Fair 🟠 Orange Needs improvement
0.0–3.9 Poor 🔴 Red High-risk factors

Data Freshness

  • Air Quality: Real-time (hourly updates)
  • Crime Data: 3 months old (FBI quarterly updates)
  • Healthcare: 6 months old
  • Education: Annual
  • Infrastructure: 6 months old
  • Water Quality: Annual

Full scoring details: See docs/SCORING.md

📡 API Endpoints

Authentication

POST   /api/v1/auth/register           # Register new user
POST   /api/v1/auth/login              # Login
POST   /api/v1/auth/logout             # Logout
POST   /api/v1/auth/refresh-token      # Get new token

Areas

GET    /api/v1/areas/search?q=query           # Search areas
GET    /api/v1/areas/:areaId                  # Get area details
GET    /api/v1/areas/nearby?lat=X&lng=Y       # Nearby areas
GET    /api/v1/areas/top?limit=10             # Top rated areas

Scores

GET    /api/v1/scores/:areaId                 # Get score
GET    /api/v1/scores/:areaId/history?days=30 # Score history
GET    /api/v1/scores/compare                 # Compare areas

Data

GET    /api/v1/crime/:areaId                  # Crime data
GET    /api/v1/aqi/:areaId                    # Air quality
GET    /api/v1/healthcare/:areaId             # Healthcare access

Reviews

GET    /api/v1/reviews/:areaId                # Get reviews
POST   /api/v1/reviews/:areaId                # Submit review
PUT    /api/v1/reviews/:reviewId              # Edit review
DELETE /api/v1/reviews/:reviewId              # Delete review

User

GET    /api/v1/users/me                       # Get profile
PUT    /api/v1/users/me                       # Update profile
GET    /api/v1/users/saved-areas              # Get saved areas
POST   /api/v1/users/saved-areas/:areaId      # Save area

Complete API docs: See docs/API.md

🎨 Design

View the complete NeighborhoodIQ design on Figma:

🔗 NeighborhoodIQ Design - Figma

Color System

  • Excellent: #22c55e (Green) | Good: #84cc16 (Lime) | Average: #eab308 (Yellow)
  • Fair: #f97316 (Orange) | Poor: #ef4444 (Red)
  • Neutral: #1f2937 (Dark), #6b7280 (Gray), #f3f4f6 (Light)

Typography

  • Font: Inter (sans-serif) for UI, Fira Code for code
  • Sizes: Display (48px), H1 (36px), H2 (28px), Body (16px), Caption (12px)
  • Weights: 400 (Regular), 600 (SemiBold), 700 (Bold)

Spacing & Components

  • Grid: 8px base unit (4px, 8px, 16px, 24px, 32px...)
  • Radius: 8px (cards), 12px (containers)
  • Shadows: Soft elevation system for depth
  • Components: Score gauge, interactive map, radar chart, comparison tables

Accessibility

  • WCAG 2.1 AA compliant with 4.5:1 contrast ratio
  • Keyboard navigation fully supported
  • Responsive: Mobile (320px), Tablet (641px), Desktop (1025px+)

🔧 Development

Running Tests

# Backend unit tests
cd server && npm run test

# Backend integration tests
npm run test:integration

# All tests with coverage
npm run test:coverage

Code Quality

# Lint code
npm run lint

# Format code (Prettier)
npm run format

# Check formatting without changes
npm run format:check

Building for Production

# Build frontend
cd client && npm run build

# Build & run with Docker
docker-compose up --build

Database Operations

cd server

# Create migration
npm run migrate:create -- --name migration_name

# Run migrations
npm run migrate:up

# Rollback
npm run migrate:down

# Seed test data
node scripts/seed.js

📊 Monitoring & Performance

  • Response Times: Avg <200ms for most endpoints (cached)
  • Database Queries: Indexed for optimal performance
  • API Rate Limiting: 100 requests/hour per IP
  • Caching: Redis caching for scores, areas, and facility data
  • Logging: Structured JSON logs with Winston

🤝 Contributing

We welcome contributions! Follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/your-feature)
  3. Make your changes with clear commit messages
  4. Test your code (npm run test)
  5. Format your code (npm run format)
  6. Push to your branch
  7. Open a Pull Request

Code Style

  • ESLint enforces consistency
  • Prettier formats code automatically
  • Write meaningful commit messages
  • Add tests for new features
  • Update docs for API changes

Commit Message Format

feat: add neighborhood comparison feature
fix: resolve score calculation bug
docs: update API documentation
style: format code with prettier
test: add unit tests for score service
refactor: simplify area search logic

📚 Documentation

🐛 Known Issues & Limitations

  • Crime data has 3-month lag (FBI update cycle)
  • Walk Score API has geographic limitations
  • Water quality data not available in all regions
  • Real-time traffic/events not factored into score
  • School ratings methodology varies by state

🚀 Roadmap

  • ✅ Mobile app (React Native)
  • ✅ AI-powered neighborhood recommendations
  • ✅ Demographic diversity metrics
  • ✅ Economic mobility data integration
  • ✅ Climate & extreme weather risk assessment
  • ✅ Commute time calculator to major employers
  • ✅ Rental market insights
  • ✅ Noise pollution data
  • ✅ Multilingual support

📞 Support & Contact

📄 License

This project is licensed under the MIT License – see the LICENSE file for details.

You are free to use, modify, and distribute this software for any purpose, including commercial use.

🙏 Acknowledgments

  • Data Partners: OpenAQ, FBI, Google, Mapbox, Walk Score, OpenWeather
  • Libraries: React, Express, MongoDB, Tailwind CSS, Recharts, Leaflet
  • Community: All contributors, users, and testers
  • Inspiration: Zillow, Redfin, CityLab, Urban Institute

📈 Project Stats

  • Lines of Code: 15,000+
  • API Endpoints: 25+
  • React Components: 40+
  • Database Collections: 8
  • Test Coverage: 85%+
  • Supported Regions: 50,000+ neighborhoods

Made with ❤️ by the NeighborhoodIQ Team

⭐ Star us on GitHub to show your support!

⬆ Back to top

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages