UrbanReflex

A smart city intelligence platform that bridges fragmented urban data sources into a unified NGSI-LD ecosystem, empowering communities and city managers with real-time infrastructure insights and open data access

Explore the platform »

🐛 Report Bug | ✨ Request Feature | 💬 Join Discussion | 📚 Documentation

✨ Highlights

• 🌍 Real-time air quality and environmental monitoring (NGSI-LD aligned)
• 📝 Citizen-Powered Infrastructure Reporting with photo uploads & geolocation
• 🤖 Automated classification and prioritization for city operations & RAG system
• 🏛️ NGSI-LD Compliant Smart City Data Models (ETSI standard)
• 📂 Open Data Access via public API & standard exports: GeoJSON, NDJSON, CSV
• ⚡ One-Command Setup with Just task runner & UV package manager
• 🔐 Access control for citizens, city staff, and admins

📋 Table of Contents

What is UrbanReflex?

UrbanReflex is an open-source smart city platform designed to address critical urban challenges through integrated data-driven solutions, combining real-time environmental monitoring with citizen engagement tools for transparent, efficient urban governance.

Built on NGSI-LD standards, the platform unifies infrastructure data, air quality monitoring, and citizen reports into actionable intelligence. Through open data access, AI-powered analytics, and real-time insights, it enables communities and city managers to make informed decisions that drive sustainable urban development and transparent governance.

🆕 What's New in v0.2.0

This release focuses on developer experience improvements, automation, and production readiness.

⚡ One-Command Setup

• Just Task Runner: 16+ pre-configured recipes for all development tasks
• UV Auto-Installation: just install automatically installs UV + all dependencies
• Dual Environment Setup: Separate configuration for backend (.env) and frontend (.env.local)
• Zero Configuration: No manual dependency installation required

🌐 Multi-Language Support

• 12 Languages: English, Vietnamese, Spanish, French, German, Chinese, Japanese, Korean, Arabic, Russian, Portuguese, Hindi
• Google Translate Integration: Real-time UI translation without page reload
• Language Persistence: Selected preference stored in browser

🔧 Developer Experience

• Updated Dependencies: Next.js 16.0.7, Prettier 3.2.5
• Code Quality Tools: Black, Flake8, isort, ESLint, Prettier pre-configured
• Pre-commit Hooks: Automatic code quality checks with Husky
• Comprehensive Documentation: Complete setup guide with troubleshooting

🐛 Bug Fixes

• Fixed ModuleNotFoundError for backend models package
• Fixed Just command PowerShell syntax errors on Windows
• Fixed frontend environment file location

See CHANGELOG.md for full release notes.

🚀 Quick Start

Prerequisites

✅ Just task runner    # https://just.systems/
✅ Docker Desktop      # https://www.docker.com/
✅ 8GB RAM minimum

Installation

# 1. Clone repository
git clone https://github.com/minhe51805/UrbanReflex.git
cd UrbanReflex

# 2. Install Just (if not already installed)
winget install Casey.Just  # Windows
brew install just          # macOS
cargo install just         # Linux

# 3. Install all dependencies (one command!)
just install
# ✅ Auto-installs UV, Python packages, npm packages

# 4. Setup environment files
just setup-env
# ✅ Creates .env and src/frontend/.env.local from examples

# 5. Start all services (one command!)
just dev
# ✅ Starts MongoDB, Orion-LD, and Scheduler with Docker Compose

Done! 🎉

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000/docs
• Orion-LD: http://localhost:1026

Note: To run backend/frontend locally (without Docker), use separate terminals:

just backend-dev    # Terminal 2: Backend dev server
just frontend-dev   # Terminal 3: Frontend dev server

Troubleshooting

# Option 1: Restart terminal and try again
just install

# Option 2: Install backend separately
just backend-install

# Option 3: Manual UV installation
irm https://astral.sh/uv/install.ps1 | iex
# Restart terminal, then: uv sync --all-extras

just db-start
just db-logs  # Check for errors

Environment Variables (Optional)

GEMINI_API_KEY=your-key        # For AI chatbot
PINECONE_API_KEY=your-key      # For vector search
OPENAQ_API_KEY=your-key        # For real air quality data

NEXT_PUBLIC_API_URL=http://localhost:8000

🛠️ Technology Stack

Backend

Frontend

Infrastructure

📊 System Architecture

📦 Project Structure

UrbanReflex/
├── src/
│   ├── backend/              # FastAPI Backend
│   │   ├── app.py            # Main application entry
│   │   ├── routers/          # API endpoint definitions
│   │   ├── models/           # Database models
│   │   ├── schemas/          # Pydantic validation schemas
│   │   ├── ai_service/       # Gemini AI & Pinecone integration
│   │   └── utils/            # Utility functions
│   └── frontend/             # Next.js 16 Frontend
│       ├── app/              # App Router pages
│       ├── components/       # React components
│       ├── contexts/         # State management
│       ├── lib/              # API clients & utilities
│       └── types/            # TypeScript definitions
├── scripts/                  # Data fetching & processing scripts
├── docs/                     # Project documentation
├── open_data/                # Open datasets (GeoJSON, NDJSON)
├── schemas/                  # JSON schemas for data validation
├── .justfile                 # Just task automation recipes
├── pyproject.toml            # Python dependencies (PEP 518)
├── docker-compose.yml        # Container orchestration
└── LICENSE                   # GPL-3.0 license

📜 Just Commands Reference

Installation & Setup

just install          # Install UV + backend deps + frontend deps (one command!)
just setup-env        # Create .env and src/frontend/.env.local from examples

Development

just dev              # Start databases + show instructions for backend/frontend
just backend-install  # Install backend dependencies only
just backend-dev      # Start backend API (port 8000)
just frontend-install # Install frontend dependencies only
just frontend-dev     # Start frontend app (port 3000)

Database Management

just db-start         # Start MongoDB + Orion-LD
just db-stop          # Stop databases
just db-restart       # Restart databases
just db-logs          # View database logs
just db-clean         # Remove all database data (with confirmation)

Code Quality

just format           # Format all code (Black + Prettier)
just lint             # Run linters (Flake8 + ESLint)
just test             # Run backend tests

Utilities

just info             # Show project info, ports, and quick start guide
just health           # Check backend health endpoint
just clean            # Clean build artifacts and cache
just stop-all         # Stop all running services
just code             # Open project in VS Code

📖 Documentation

🌟 Use Cases

For Citizens

• Click any road segment on the map to view complete infrastructure information: weather conditions, air quality, streetlights, and nearby public facilities
• Report infrastructure issues (broken streetlights, potholes, waste dumping, flooding) with automatic GPS location and photo documentation
• Track real-time resolution status of submitted reports with automatic updates and notifications
• Explore open data to gain deeper insights about your neighborhood and make informed decisions

For City Officials

• Real-time dashboard displaying all citizen reports on an interactive map with powerful filtering capabilities
• AI-powered automatic issue classification and priority adjustment based on proximity to schools, hospitals, and sensitive areas
• Data-driven task management and maintenance assignment, optimizing resource allocation and response times
• Export open data in multiple formats (NDJSON, CSV, GeoJSON) for deep analysis and urban planning

For Developers

• Access complete NGSI-LD entities (RoadSegment, WeatherObserved, AirQualityObserved, Streetlight, PointOfInterest, CitizenReport) via standard REST API
• Build custom applications leveraging Linked Open Data (LOD) relationships between entities
• Integrate with other smart city systems through FiWARE Smart Data Models and SOSA/SSN ontology compliance
• Contribute to open-source smart city platform with comprehensive, ready-to-use open datasets

Contributing

📖 Contributing Guidelines

We are excited that you are interested in contributing to this project! Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

Read through our contributing guidelines to learn about our submission process, coding rules, and more.

💁 Want to Help?

Want to report a bug, contribute some code, or improve the documentation? Excellent! Read up on our guidelines for contributing and then check out one of our issues labeled as help wanted or good first issue.

Support and Organization

📈 Project Stats

Metric	Badge
🌟 Stars
🍴 Forks
👁️ Watchers
👥 Contributors
📝 Commits
🐛 Issues
🎯 Pull Requests
📅 Last Commit
📦 Code Size
📜 License

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Key Points:

• ✅ Free to use, modify, and distribute
• ✅ Source code must be made available
• ✅ Modifications must use same GPL-3.0 license
• 📖 Full license: https://www.gnu.org/licenses/gpl-3.0.html