UrbanReflex

UrbanReflex is an open-source smart city platform that transforms road segments into linked data nodes, integrating environmental monitoring, infrastructure status, and citizen reports. AI-powered classification and prioritization help city teams manage issues efficiently, while NGSI-LD open data ensures transparency and interoperability.

Generate Convert Improve

Install / Use

/learn @minhe51805/UrbanReflex

About this skill

Quality Score

0/100

README

<img loading="lazy" src="https://drive.google.com/uc?export=view&id=1GG28YjHys9I1DTv2HnXOtD6zD0zwUgrg" alt="UrbanReflex Logo" height="150"> <h1 align="center">UrbanReflex</h1> 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 <a href="https://urbanreflex.org" rel="dofollow" target="blank">Explore the platform »</a> <a href="https://github.com/minhe51805/UrbanReflex/issues/new?template=bug_report.yml">🐛 Report Bug</a> | <a href="https://github.com/minhe51805/UrbanReflex/issues/new?template=feature_request.yml">✨ Request Feature</a> | <a href="https://t.me/+o1X9iR9j7_czYmE1">💬 Join Discussion</a> | <a href="./docs/">📚 Documentation</a> <a href="https://github.com/minhe51805/UrbanReflex/releases" target="blank"> <img loading="lazy" src="https://img.shields.io/badge/version-0.2.0-blue.svg" alt="UrbanReflex version"/> </a> <a href="https://github.com/minhe51805/UrbanReflex/releases" target="blank"> <img loading="lazy" src="https://img.shields.io/badge/release-Stable-green.svg" alt="Release Status"/> </a> <a href="https://github.com/minhe51805/UrbanReflex/issues" target="blank"> <img loading="lazy" src="https://img.shields.io/github/issues/minhe51805/UrbanReflex?label=Issues" alt="UrbanReflex issues"/> </a> <a href="https://github.com/minhe51805/UrbanReflex/blob/main/LICENSE" target="blank"> <img loading="lazy" src="https://img.shields.io/github/license/minhe51805/UrbanReflex?label=License" alt="UrbanReflex license"/> </a> <a href="https://fastapi.tiangolo.com/" target="blank"> <img loading="lazy" src="https://img.shields.io/badge/FastAPI-0.121-009688?logo=fastapi&logoColor=white" alt="FastAPI"/> </a> <a href="https://nextjs.org/" target="blank"> <img loading="lazy" src="https://img.shields.io/badge/Next.js-16.0.7-black?logo=next.js&logoColor=white" alt="Next.js"/> </a> <a href="https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.08.01_60/gs_CIM009v010801p.pdf" target="blank"> <img loading="lazy" src="https://img.shields.io/badge/NGSI--LD-Compliant-00A3E0" alt="NGSI-LD"/> </a> <img loading="lazy" src="https://lh3.googleusercontent.com/d/13S8-5iyJ0gnvT_wIFRnAVPxeNz8_7E5Q" alt="UrbanReflex Banner" width="100%">

✨ 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

<details> <summary>Expand contents</summary>

What is UrbanReflex?
What's New in v0.2.0
Key Features
Quick Start
Demo Credentials
Technology Stack
System Architecture
Project Structure
Just Commands Reference
Documentation
Project Status
Contributing
Support and Organization
License

</details>

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. <blockquote> 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. </blockquote>

🆕 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

<details> <summary>❌ UV installation error on Windows</summary>

If just install fails with UV path errors:

# 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

</details> <details> <summary>❌ Database connection error</summary>

Make sure databases are running:

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

</details>

Environment Variables (Optional)

<details> <summary>Click to expand configuration</summary>

Edit .env for backend:

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

Edit src/frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

App works without API keys (uses mock data)

</details>

🛠️ Technology Stack

Backend

| Technology | Purpose | | ---------------- | --------------------------------------- | | FastAPI | High-performance async API framework | | Python 3.10+ | Backend runtime | | MongoDB | Document database for users and reports | | Orion-LD | NGSI-LD compliant context broker | | Redis | In-memory caching and sessions | | Gemini AI | Natural language understanding | | Pinecone | Vector search for semantic similarity |

Frontend

| Technology | Purpose | | ----------------- | ------------------------------- | | Next.js 16 | React framework with App Router | | TypeScript | Type-safe development | | Tailwind CSS | Utility-first styling | | MapLibre GL | Interactive WebGL mapping | | Chart.js | Data visualization | | Framer Motion | Smooth UI animations |

Infrastructure

| Technology | Purpose | | ------------------ | --------------------------- | | Docker Compose | Multi-service orchestration | | Just | Task automation | | UV | Fast Python package manager | | Husky | Git hooks for code quality |

📊 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
│