UrbanReflex

Highlights

• Real-time NGSI-LD context (RoadSegment, Streetlight, WeatherObserved, AirQualityObserved, POI, CitizenReport).
• Citizen reporting: create/list/update/delete + NLP classification and POI-based priority.
• AI chatbot: streaming/non-streaming; optional vector search (Pinecone) for RAG.
• Admin health/stats endpoints; Swagger/ReDoc/OpenAPI schema.
• One-command setup with Just + UV + Docker Compose (MongoDB, Orion-LD).

Quick Start

# 1) Clone
git clone https://github.com/minhe51805/UrbanReflex.git
cd UrbanReflex
 
# 2) Install all deps (UV + backend + frontend)
just install
 
# 3) Generate env files
just setup-env   # .env and src/frontend/.env.local
 
# 4) Run dev stack (MongoDB, Orion-LD, scheduler if configured, backend/frontend)
just dev

Services: Frontend http://localhost:3000 • Backend http://localhost:8000 (Swagger /docs) • Orion-LD http://localhost:1026 • MongoDB localhost:27017.
Run separately: just backend-dev, just frontend-dev, DB only: just db-start.

Minimal env (backend):

MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=urbanreflex
ORION_LD_URL=http://localhost:1026
GEMINI_API_KEY=        # optional for chatbot
PINECONE_API_KEY=      # optional for RAG
OPENAQ_API_KEY=        # optional, mock if absent
OPENWEATHER_API_KEY=   # optional, mock if absent
SECRET_KEY=change_me
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8000

Frontend .env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

Services & URLs

• Base (dev): http://localhost:8000
• Docs: /docs (Swagger), /redoc, schema /openapi.json
• API namespace: /api/v1/
• Orion-LD: http://localhost:1026/ngsi-ld/v1 (direct NGSI-LD operations)

Architecture

• Backend: FastAPI, async, Pydantic, OpenAPI, SSE chatbot.
• Data layer: MongoDB; Orion-LD for NGSI-LD; Pinecone optional; Redis (planned) for cache/rate-limit.
• AI: Gemini Pro; RAG optional with vector search.
• Docs/frontend: Next.js 15 static export (Fumadocs), Tailwind 4; GitHub Pages basePath supported (GITHUB_PAGES=true → /UrbanReflex).

See full diagrams in ARCHITECTURE.md.

Tech Stack

• Backend: FastAPI, Python 3.10+, httpx, Pydantic 2, Uvicorn, APScheduler (planned).
• Data/Context: MongoDB, Orion-LD (NGSI-LD), Pinecone (optional vectors).
• AI: Gemini Pro (google-generativeai).
• Docs/UI: Next.js 15, React 18, Tailwind 4, Fumadocs MDX; static export.

Documentation

• Setup: DEVELOPMENT_SETUP.md
• API: API_REFERENCE.md
• Data model: DATA_MODEL_AND_ENTITIES.md
• User guide: USER_GUIDE.md
• Architecture: ARCHITECTURE.md
• Code style: CODE_STYLE_GUIDE.md

Commands (Just)

just install       # Install UV + backend + frontend deps
just setup-env     # Create .env and .env.local
just dev           # Start DBs + show backend/frontend instructions
just backend-dev   # FastAPI dev server (8000)
just frontend-dev  # Frontend dev server (3000)
just db-start      # MongoDB + Orion-LD
just db-logs       # Tail DB logs
just test          # Backend tests
just format        # Black + Prettier
just lint          # Flake8 + ESLint

License

GPL-3.0. See LICENSE. Contributions welcome—PRs are appreciated.