🏙️ CityCare

🏙️ CityCare

Intelligent Urban Infrastructure Management Platform

Data-driven visibility into city systems. Predictive maintenance powered by AI. Community engagement that makes a difference.

🎯 The Challenge

Cities face an infrastructure crisis that's invisible until something breaks.

The Current Reality:

📉 No visibility into system health across the city
🔧 Maintenance teams react to crises instead of preventing them
📱 Community reports scattered across multiple channels, easily lost
📊 Data siloed—no way to identify patterns or recurring problems
⚠️ Budget decisions made without data backing
🌆 Millions spent on avoidable emergencies

The Cost of Reactive Management: When water pipes burst, electrical systems fail, and roads deteriorate without warning, the city pays in emergency repairs, business disruptions, and reduced quality of life.

What if you could see problems forming before they became catastrophic? What if every citizen report became actionable intelligence? What if your maintenance budget was guided by data, not crisis?

💡 The CityCare Solution

CityCare transforms city infrastructure from reactive chaos into intelligent, data-driven management.

We combine real-time geospatial visualization, predictive AI analysis, and community-powered reporting to give cities complete visibility into infrastructure health and predictive insights for maintenance planning.

How It Works

📱 Citizens Report Issues → 🗺️ Live Heatmap Visualization →
📊 Pattern Detection & Analysis → 🤖 AI Risk Assessment →
🎯 Smart Prioritization → ✅ Accelerated Resolution

✨ Core Capabilities

🗺️ Spatial Intelligence

Real-time geospatial heatmaps showing issue density and severity
Zone-based clustering and risk zones identification
Historical pattern visualization overlays
Custom city boundary mapping

🤖 AI-Powered Insights

Gemini AI analyzes trends across all infrastructure data
Automatic root cause detection and pattern recognition
Predictive alerts for high-risk zones
Natural language reports: "Downtown has 5x more pothole reports than average"

📊 Comprehensive Analytics

Mean Time To Resolution (MTTR) tracking
Issue category trends and seasonal patterns
Recurring issue detection
Multi-zone comparative analysis

🏆 Community Engagement

Points and rewards system for active reporters
Public leaderboards and achievement badges
Community voting on critical issues
Recognition for city improvement advocates

👥 Admin Command Center

Complete user and issue management dashboard
System-wide analytics and health overview
Bulk operations and workflow management
Export reports in multiple formats (CSV, JSON, PDF)

📧 Smart Notifications

Beautiful HTML email templates
Instant alerts on issue reports
Resolution confirmations
Stakeholder updates
OAuth welcome communications

�️ Technology Stack

💻 Frontend

⚡ Next.js 14 with App Router
🎨 Tailwind CSS + Shadcn UI
🗺️ Leaflet + OpenStreetMap
📊 Recharts for analytics
🔔 React Hot Toast notifications

⚙️ Backend

🔒 Express + TypeScript APIs
🗄️ MongoDB with geospatial indexes
📧 Nodemailer for emails
🐳 Docker containerization
🚂 Railway deployment

💾 Database & Storage

📄 MongoDB NoSQL database
🗺️ Geospatial indexes for location queries
🖼️ Cloudinary for image storage
⚡ Real-time data sync via WebSocket/SSE
🔍 Compound indexes for analytics

🤖 AI & Intelligence

🧠 Gemini 1.5 Flash API
🔐 Firebase Authentication
📊 AI-powered insights
🎯 Risk scoring algorithms
📝 Natural language reports

🏗️ System Architecture

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#1976d2','primaryTextColor':'#fff','primaryBorderColor':'#0d47a1','lineColor':'#424242','secondaryColor':'#388e3c','tertiaryColor':'#f57c00','noteBkgColor':'#fff9c4','noteTextColor':'#000'}}}%%
graph TB
    subgraph Frontend["🖥️ Frontend - Vercel"]
        NextJS["Next.js 14<br/>App Router + RSC"]
        Leaflet["Leaflet Maps<br/>Real-time Heatmaps"]
        AdminUI["Admin Dashboard<br/>Charts & Analytics"]
    end

    subgraph Backend["⚙️ Backend - Railway"]
        Express["Express + TypeScript<br/>REST API"]
        AdminModule["Admin Module<br/>User/Issue Management"]
        EmailService["Nodemailer<br/>HTML Templates"]
    end

    subgraph Data["💾 Data Layer"]
        Firestore["Firebase Firestore<br/>GeoPoint Queries"]
        FirebaseAuth["Firebase Auth<br/>JWT Tokens"]
    end

    subgraph AI["🤖 AI Layer"]
        Gemini["Gemini 1.5 Flash<br/>Natural Language Insights"]
    end

    NextJS --> Express
    Leaflet --> NextJS
    AdminUI --> AdminModule
    Express --> Firestore
    Express --> FirebaseAuth
    Express --> Gemini
    EmailService --> Express
    AdminModule --> Firestore

    style Frontend fill:#1976d2,stroke:#0d47a1,stroke-width:2px,color:#fff
    style Backend fill:#388e3c,stroke:#2e7d32,stroke-width:2px,color:#fff
    style Data fill:#7b1fa2,stroke:#6a1b9a,stroke-width:2px,color:#fff
    style AI fill:#f57c00,stroke:#e65100,stroke-width:2px,color:#fff

Architecture Layers

🎨 Frontend

Next.js 14

App Router
React Server Components
Leaflet heatmaps
Admin dashboard

⚙️ Backend

Express API

TypeScript
Railway deployment
40+ endpoints
Email service

💽 Database

Firestore

GeoPoint queries
Composite indexes
Real-time sync
Role-based access

🤖 AI

Gemini AI

Plain-English reports
Pattern analysis
Trend insights
1500 req/day

🛠️ Technology Stack

💻 Frontend Stack

Features:

🚀 Server-side rendering for performance
🎨 Modern UI with Tailwind CSS
📱 Responsive design
⚡ Optimized for speed
🗺️ OpenStreetMap + Leaflet integration

⚙️ Backend Stack

Features:

🔒 Type-safe APIs with TypeScript
🗄️ MongoDB with geospatial support
🐳 Containerized deployment
🔐 JWT authentication
📊 RESTful architecture
💰 100% Free hosting

☁️ Modern Cloud Stack

Backend
Deployment

NoSQL +
Geospatial

Interactive
Maps

AI
Insights

Auth &
Security

Open Source
Maps

📊 Data Model

Infrastructure Issue Entity

Field	Type	Description
issue_id	UUID	Unique identifier
category	Enum	Water, Electricity, WiFi, Sanitation, etc.
latitude	Float	Geographic latitude
longitude	Float	Geographic longitude
severity	Integer	Severity level (1-5)
timestamp	DateTime	Issue creation time
status	Enum	Open, In Progress, Resolved
description	Text	Issue details
building_id	String	Associated zone identifier (optional)

🚀 Quick Start

📋 Prerequisites

v18 or higher

Free tier cluster

From AI Studio

⚡ 3-Step Setup

1️⃣ Firebase Setup

# Create Firebase project
# (console.firebase.google.com)

# Enable Firestore
# Enable Authentication
# Download service account key

Get:

Project ID
Service account JSON
Web app config

📖 Full Guide

2️⃣ Backend Deploy

cd backend
npm install

# Add .env file
MONGODB_URI='mongodb+srv://user:pass@cluster.mongodb.net'
GOOGLE_GEMINI_API_KEY='your_key'
EMAIL_USER='your@gmail.com'
EMAIL_PASS='app_password'

# Deploy to Railway
npm run build

📖 Railway Guide

3️⃣ Frontend Deploy

cd frontend
npm install

# Add .env.local
NEXT_PUBLIC_API_URL='https://your-api.railway.app'

# Run locally
npm run dev

# Deploy to Vercel
vercel --prod

📖 Integration Guide

🌐 Access Points

Service	URL	Description
🎨 Frontend	http://localhost:3000	Next.js app with heatmaps
⚙️ Backend	http://localhost:3001	Express API on Railway
🔥 Firestore	Firebase Console	Database & authentication
📧 Admin Panel	/admin/dashboard	User/issue management

🔑 Get API Keys (All Free!)

🤖 Gemini API Key (1500 requests/day)

Visit aistudio.google.com
Click "Create API Key"
Copy to GOOGLE_GEMINI_API_KEY in .env

🔥 Firebase Config (No credit card)

Go to Firebase Console
Create new project
Enable Firestore Database
Enable Authentication (Email & Google)
Project Settings → Service Accounts → Generate new private key
Copy JSON to FIREBASE_SERVICE_ACCOUNT_KEY

📧 Gmail SMTP (For email notifications)

Enable 2FA on your Google account
Generate App Password: myaccount.google.com/apppasswords

Add to .env:

EMAIL_USER=your@gmail.com
EMAIL_PASS=your_16_char_app_password

📄 Environment Variables

Backend (.env):

MONGODB_URI='mongodb+srv://user:pass@cluster.mongodb.net/citycare'
GOOGLE_GEMINI_API_KEY='AIzaSy...'
EMAIL_USER='your@gmail.com'
EMAIL_PASS='your_app_password'
PORT=3001
FRONTEND_URL='http://localhost:3000'

Frontend (.env.local):

NEXT_PUBLIC_API_URL='http://localhost:3001'

📁 Project Structure

citycare/
├── 📄 README.md                    # You are here!
├── 🐳 docker-compose.yml           # Multi-service orchestration
├── 📚 docs/                        # Comprehensive documentation
│   ├── DATABASE_ARCHITECTURE.md   # MongoDB schema guide
│   ├── architecture/              # System design docs
│   ├── api/                       # API specifications
│   └── prompts/                   # AI prompt templates
│
├── ⚙️ backend/                     # Node.js + Express + TypeScript
│   ├── src/
│   │   ├── config/                # MongoDB & Cloudinary setup
│   │   ├── modules/               # Feature modules
│   │   │   ├── issues/           # Issue management
│   │   │   ├── analytics/        # Data analytics
│   │   │   ├── ai/               # Gemini integration
│   │   │   └── auth/             # JWT authentication
│   │   ├── middlewares/          # Express middleware
│   │   ├── types/                # TypeScript definitions
│   │   └── utils/                # Helper functions
│   └── package.json              # Dependencies (MongoDB, Express)
│
├── 🎨 frontend/                    # Next.js 14 + TypeScript
│   ├── src/
│   │   ├── app/                  # Next.js app router
│   │   ├── components/           # React components
│   │   │   ├── Map/             # Leaflet + OpenStreetMap
│   │   │   ├── Charts/          # Data visualization
│   │   │   └── Dashboard/       # Admin interface
│   │   ├── lib/                 # Utilities & API client
│   │   └── styles/              # Tailwind CSS
│   └── public/                  # Static assets
│
├── 📊 analytics/                   # Analytics Scripts
│   └── bigquery/              # Data analysis queries
│
└── 🏗️ infra/                       # Infrastructure as Code
    ├── cloudrun.yaml             # Cloud Run deployment
    └── sql/                      # Database initialization

🧪 Testing

# Backend tests
cd backend
npm test
npm run test:coverage

# Frontend tests
cd frontend
npm test

📦 Deployment

Deploy to Railway in Minutes

⚙️ Backend (Railway)

# Build and deploy
cd backend
railway link
railway up

Auto-configured:

✅ MongoDB Atlas integration
✅ Environment variables
✅ Health checks
✅ Auto-scaling
✅ Free tier: 5GB bandwidth

🎨 Frontend (Vercel)

# Build Next.js app
cd frontend
npm run build

# Deploy to Vercel
vercel --prod

Features:

✅ Global CDN
✅ Automatic SSL
✅ Optimized builds
✅ Preview deployments
✅ Analytics included

🔒 Security & Best Practices

🛡️ Authentication

Email/password login
Google OAuth
JWT token validation
Session management
Role-based access control

🔐 Data Protection

SQL injection prevention
XSS protection
CORS security
Input sanitization
Environment encryption

⚡ Rate Limiting

API throttling
DDoS protection
Request validation
IP whitelisting
Quota management

📈 Scalability & Future Roadmap

Built to Scale: City → Multi-City → Global Smart Infrastructure

🏢 Multi-Campus

Extend to multiple institutions with tenant isolation

📱 IoT Integration

Connect real-time sensors for automated monitoring

📲 Mobile Apps

Native iOS/Android apps for field staff

🌆 Smart City

Scale to public infrastructure management

🤝 Contributing

graph LR
    A[🍴 Fork] --> B[🌿 Branch]
    B --> C[💻 Code]
    C --> D[✅ Test]
    D --> E[📝 Commit]
    E --> F[🚀 Push]
    F --> G[🔄 Pull Request]

    style A fill:#e3f2fd
    style G fill:#c8e6c9

Quick Steps:

🍴 Fork the repository
🌿 Create feature branch (git checkout -b feature/AmazingFeature)
💻 Make your changes
✅ Add tests
📝 Commit (git commit -m 'Add AmazingFeature')
🚀 Push to branch (git push origin feature/AmazingFeature)
🔄 Open a Pull Request

📄 License

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

🙏 Acknowledgments

Document Database

Flexible schema and powerful query language

AI Intelligence

Natural language insights and automated report generation

Interactive Maps

Open source mapping with no API key required

Open Source Maps

Free, unlimited map tiles with no API key required

📞 Contact & Support

Project Link: https://github.com/deepaksoni47/CityCare

🌟 Star this repository if you find it useful! 🌟

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
analytics/bigquery		analytics/bigquery
backend		backend
docs		docs
frontend		frontend
infra		infra
scripts		scripts
.env.docker.example		.env.docker.example
.env.example		.env.example
.gitignore		.gitignore
IMPLEMENTATION_CHECKLIST.md		IMPLEMENTATION_CHECKLIST.md
MIGRATION_CHECKLIST.md		MIGRATION_CHECKLIST.md
MIGRATION_SUMMARY.md		MIGRATION_SUMMARY.md
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
package.json		package.json
quick-start.bat		quick-start.bat
quick-start.sh		quick-start.sh
railway.toml		railway.toml

Folders and files

Latest commit

History

Repository files navigation

🏙️ CityCare

Intelligent Urban Infrastructure Management Platform

Data-driven visibility into city systems. Predictive maintenance powered by AI. Community engagement that makes a difference.

🎯 The Challenge

💡 The CityCare Solution

How It Works

✨ Core Capabilities

🗺️ Spatial Intelligence

🤖 AI-Powered Insights

📊 Comprehensive Analytics

🏆 Community Engagement

👥 Admin Command Center

📧 Smart Notifications

�️ Technology Stack

💻 Frontend

⚙️ Backend

💾 Database & Storage

🤖 AI & Intelligence

🏗️ System Architecture

Architecture Layers

🎨 Frontend

⚙️ Backend

💽 Database

🤖 AI

🛠️ Technology Stack

💻 Frontend Stack

⚙️ Backend Stack

☁️ Modern Cloud Stack

📊 Data Model

Infrastructure Issue Entity

🚀 Quick Start

📋 Prerequisites

⚡ 3-Step Setup

1️⃣ Firebase Setup

2️⃣ Backend Deploy

3️⃣ Frontend Deploy

🌐 Access Points

🔑 Get API Keys (All Free!)

📄 Environment Variables

📁 Project Structure

🧪 Testing

📦 Deployment

Deploy to Railway in Minutes

⚙️ Backend (Railway)

🎨 Frontend (Vercel)

🔒 Security & Best Practices

🛡️ Authentication

🔐 Data Protection

⚡ Rate Limiting

📈 Scalability & Future Roadmap

Built to Scale: City → Multi-City → Global Smart Infrastructure

🏢 Multi-Campus

📱 IoT Integration

📲 Mobile Apps

🌆 Smart City

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Contact & Support

🌟 Star this repository if you find it useful! 🌟

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages