🏙️ ISSOP - Intelligent Smart City Operations Platform

A comprehensive smart city management system connecting citizens, field agents, and administrators for efficient urban service delivery.

📋 Table of Contents

Overview
Features
Architecture
Tech Stack
Getting Started
Project Structure
Notification System
API Documentation
Deployment
Testing
Contributing
License

🌟 Overview

ISSOP (Intelligent Smart City Operations Platform) is a modern, real-time platform designed to streamline urban service management. It enables citizens to report issues, field agents to respond efficiently, and administrators to monitor and manage city operations from a centralized dashboard.

Key Capabilities

📱 Mobile App - Citizens report issues with photos and location
👷 Agent Portal - Field agents receive and manage assigned tasks
🖥️ Admin Dashboard - Real-time monitoring and analytics
🔔 Smart Notifications - Hourly reminders and instant updates
🗺️ Live Tracking - Real-time agent location and task status
📊 Analytics - Comprehensive insights and performance metrics

✨ Features

For Citizens (Mobile App)

✅ Report issues with photos, location, and description
✅ Track request status in real-time
✅ Receive notifications when issues are resolved
✅ Hourly reminders for pending requests
✅ View nearby agents and estimated response time
✅ Rate and review completed services

For Field Agents (Mobile App)

✅ Receive task assignments instantly
✅ Update task status (In Progress, Completed)
✅ Upload completion proof with photos
✅ Navigate to task locations with maps
✅ Hourly reminders for assigned tasks
✅ View task history and performance metrics

For Administrators (Web Dashboard)

✅ Real-time dashboard with live statistics
✅ Monitor all requests and agent activities
✅ Assign tasks to available agents
✅ View analytics and performance reports
✅ Manage users and roles (SUPERADMIN)
✅ Live map with agent locations
✅ Daily summary reports at 9 AM
✅ Alert notifications for urgent issues

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     ISSOP Platform                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │   Mobile     │  │    Admin     │  │   Backend    │    │
│  │     App      │  │  Dashboard   │  │     API      │    │
│  │  (React      │  │  (Next.js)   │  │  (Node.js)   │    │
│  │   Native)    │  │              │  │              │    │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │
│         │                  │                  │            │
│         └──────────────────┴──────────────────┘            │
│                            │                               │
│                    ┌───────▼────────┐                      │
│                    │   Socket.IO    │                      │
│                    │  (Real-time)   │                      │
│                    └───────┬────────┘                      │
│                            │                               │
│         ┌──────────────────┼──────────────────┐           │
│         │                  │                  │           │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐   │
│  │  PostgreSQL  │  │  Cloudinary  │  │   Node-Cron  │   │
│  │  (Database)  │  │   (Images)   │  │ (Scheduler)  │   │
│  └──────────────┘  └──────────────┘  └──────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

System Flow

Citizen reports issue via mobile app
Backend stores request and notifies admins
Admin assigns task to available agent
Agent receives notification and accepts task
Agent updates status and uploads completion proof
Citizen receives completion notification
Scheduler sends hourly reminders for pending tasks

🛠️ Tech Stack

Backend

Runtime: Node.js 20.x
Framework: Express.js
Database: PostgreSQL with Prisma ORM
Real-time: Socket.IO
Authentication: JWT (JSON Web Tokens)
File Storage: Cloudinary
Scheduling: node-cron
API Docs: Swagger/OpenAPI

Admin Dashboard

Framework: Next.js 16 (React 19)
Language: TypeScript
Styling: Tailwind CSS
UI Components: Radix UI + shadcn/ui
State Management: Redux Toolkit
Maps: Leaflet + React Leaflet
Charts: Recharts
Animations: Framer Motion

Mobile App

Framework: React Native (Expo)
Language: TypeScript
Navigation: React Navigation
State: Redux Toolkit
Maps: React Native Maps
Camera: Expo Camera & Image Picker

🚀 Getting Started

Prerequisites

Node.js >= 20.11.1
npm >= 9.8.1
PostgreSQL >= 14
Git

Installation

1. Clone the Repository

git clone https://github.com/Temsegn/ISSOP-Platform.git
cd ISSOP-Platform

2. Setup Backend

cd Backend

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local

# Edit .env.local with your credentials:
# - DATABASE_URL
# - JWT_SECRET
# - CLOUDINARY credentials

# Run database migrations
npx prisma migrate dev

# Seed database (optional)
npx prisma db seed

# Start server
npm run dev

Backend runs on: http://localhost:3000

3. Setup Admin Dashboard

cd Admin

# Install dependencies
npm install

# Environment is pre-configured in .env.local
# Points to: https://issop-platform.onrender.com/api/v1

# Start development server
npm run dev

Admin Dashboard runs on: http://localhost:3000

4. Setup Mobile App

cd mobile

# Install dependencies
npm install

# Start Expo
npm start

# Scan QR code with Expo Go app
# Or press 'a' for Android, 'i' for iOS simulator

📁 Project Structure

ISSOP-Platform/
├── Backend/                    # Node.js API Server
│   ├── prisma/
│   │   ├── schema.prisma      # Database schema
│   │   └── seed.js            # Database seeding
│   ├── src/
│   │   ├── config/            # Configuration files
│   │   ├── middleware/        # Express middlewares
│   │   ├── modules/           # Feature modules
│   │   │   ├── auth/          # Authentication
│   │   │   ├── users/         # User management
│   │   │   ├── requests/      # Request handling
│   │   │   ├── tasks/         # Task management
│   │   │   ├── notifications/ # Notifications
│   │   │   └── analytics/     # Analytics & reports
│   │   ├── services/          # Business logic
│   │   │   └── notification-scheduler.js
│   │   ├── app.js             # Express app
│   │   └── server.js          # Server entry point
│   ├── tests/                 # Unit & integration tests
│   ├── .env.example           # Environment template
│   └── package.json
│
├── Admin/                      # Next.js Admin Dashboard
│   ├── app/                   # App router pages
│   │   ├── dashboard/         # Dashboard pages
│   │   │   ├── page.tsx       # Main dashboard
│   │   │   ├── requests/      # Request management
│   │   │   ├── users/         # User management
│   │   │   ├── agents/        # Agent monitoring
│   │   │   ├── analytics/     # Analytics
│   │   │   ├── roles/         # Role management
│   │   │   └── settings/      # Settings
│   │   └── login/             # Login page
│   ├── components/            # React components
│   │   ├── dashboard/         # Dashboard components
│   │   └── ui/                # UI components (shadcn)
│   ├── lib/                   # Utilities
│   │   ├── api.ts             # API client
│   │   ├── socket.ts          # Socket.IO client
│   │   └── types.ts           # TypeScript types
│   ├── store/                 # Redux store
│   ├── .env.local             # Environment config
│   └── package.json
│
├── mobile/                     # React Native Mobile App
│   ├── src/
│   │   ├── screens/           # App screens
│   │   ├── components/        # React components
│   │   ├── navigation/        # Navigation config
│   │   ├── services/          # API & services
│   │   ├── store/             # Redux store
│   │   └── utils/             # Utilities
│   ├── app.json               # Expo configuration
│   └── package.json
│
├── docs/                       # Documentation
├── COMPLETE-FIXES-SUMMARY.md  # All fixes summary
└── README.md                   # This file

🔔 Notification System

Overview

ISSOP features a comprehensive notification system with real-time delivery and scheduled reminders.

Notification Types

Type	Recipient	Trigger	Frequency
Task Assignment	Agent	Request assigned	Instant
Status Update	Citizen	Status changes	Instant
Completion	Citizen	Request completed	Instant
Hourly Reminder	Citizen/Agent	Pending >1 hour	Every hour
Alert	Admin	Pending >24 hours	Every 24 hours
Daily Summary	Admin	Platform stats	9:00 AM daily

Hourly Reminders

How it works:

Cron job runs every hour at minute 0 (10:00, 11:00, 12:00, etc.)
Checks all requests pending for more than 1 hour
Sends reminders to:
- Citizens: "Your request has been pending for X hours. We're working on it!"
- Agents: "Reminder: Task assigned to you for X hours. Please update status."
- Admins: For requests >24 hours old

Configuration:

// Backend/src/services/notification-scheduler.js
cron.schedule('0 * * * *', async () => {
  // Hourly reminder logic
});

Completion Notifications

When a request is marked as COMPLETED:

✅ Great news! Your request "Fix Pothole" has been completed. 
Thank you for using ISSOP!

When a request is IN_PROGRESS:

🔧 Your request "Fix Pothole" is now being worked on by our team.

Real-Time Delivery

All notifications are delivered via Socket.IO for instant updates:

// Client connects
socket.on('notification_received', (notification) => {
  // Display notification in app
});

// Server sends
socketService.emitToUser(userId, 'notification_received', notification);

API Endpoints

Get Notifications:

GET /api/v1/notifications
Authorization: Bearer <token>

Mark as Read:

PATCH /api/v1/notifications/:id/read
Authorization: Bearer <token>

📚 API Documentation

Base URL

Production: https://issop-platform.onrender.com/api/v1
Local: http://localhost:3000/api/v1

Authentication

All protected endpoints require JWT token:

Authorization: Bearer <your-jwt-token>

Key Endpoints

Authentication

POST /auth/register          # Register new user
POST /auth/login             # Login
GET  /auth/me                # Get current user

Requests

GET    /requests             # List all requests
POST   /requests             # Create new request
GET    /requests/:id         # Get request details
PATCH  /requests/:id/status  # Update status
PATCH  /requests/:id/assign  # Assign to agent

Users

GET    /users                # List users
GET    /users/:id            # Get user details
PATCH  /users/:id            # Update user
DELETE /users/:id            # Delete user
PATCH  /users/:id/role       # Update user role

Notifications

GET    /notifications        # Get user notifications
PATCH  /notifications/:id/read  # Mark as read

Analytics

GET /analytics/summary       # Dashboard statistics
GET /analytics/agents        # Agent performance

Swagger Documentation

Interactive API documentation available at:

http://localhost:3000/api-docs

🌐 Deployment

Backend (Render.com)

Create Web Service
- Connect GitHub repository
- Select Backend folder
- Build Command: npm install && npx prisma generate
- Start Command: npm start

Environment Variables

DATABASE_URL=postgresql://...
JWT_SECRET=your-secret-key
CLOUDINARY_CLOUD_NAME=...
CLOUDINARY_API_KEY=...
CLOUDINARY_API_SECRET=...
PORT=3000

Database
- Create PostgreSQL database on Render
- Run migrations: npx prisma migrate deploy

Admin Dashboard (Vercel)

Deploy to Vercel
```
cd Admin
vercel
```

Environment Variables

NEXT_PUBLIC_API_URL=https://issop-platform.onrender.com/api/v1
NEXT_PUBLIC_SOCKET_URL=https://issop-platform.onrender.com

Mobile App (Expo)

Build for Production

cd mobile
eas build --platform android
eas build --platform ios

Submit to Stores

eas submit --platform android
eas submit --platform ios

🧪 Testing

Backend Tests

cd Backend

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test
npm test -- auth.service.test.js

Test Suites:

Unit tests for services
Integration tests for API endpoints
Database tests with Prisma mock

Admin Dashboard

cd Admin

# Type checking
npm run type-check

# Linting
npm run lint

# Build test
npm run build

Mobile App

cd mobile

# Run tests
npm test

# Type checking
npm run type-check

👥 User Roles

USER (Citizen)

Report issues
Track request status
Receive notifications
Rate completed services

AGENT (Field Agent)

View assigned tasks
Update task status
Upload completion proof
Navigate to locations

ADMIN (Administrator)

View all requests
Assign tasks to agents
Monitor agent activities
View analytics (area-specific)

SUPERADMIN (Super Administrator)

All ADMIN permissions
Manage users and roles
System-wide analytics
Platform configuration

🔐 Security

Authentication: JWT with secure token storage
Authorization: Role-based access control (RBAC)
Data Validation: Zod schema validation
SQL Injection: Protected by Prisma ORM
XSS Protection: Helmet.js middleware
CORS: Configured for specific origins
Rate Limiting: Implemented on sensitive endpoints
Password Hashing: bcrypt with salt rounds

📊 Performance

Real-time Updates: Socket.IO for instant notifications
Caching: API response caching (30 seconds TTL)
Database Indexing: Optimized queries with indexes
Image Optimization: Cloudinary transformations
Code Splitting: Next.js automatic code splitting
Lazy Loading: Components loaded on demand

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch
```
git checkout -b feature/amazing-feature
```
Commit your changes
```
git commit -m 'Add amazing feature'
```
Push to the branch
```
git push origin feature/amazing-feature
```
Open a Pull Request

Coding Standards

Backend: ESLint configuration
Frontend: TypeScript strict mode
Commits: Conventional commits format
Tests: Required for new features

📝 License

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

📞 Support

For issues, questions, or contributions:

GitHub Issues: Create an issue
Documentation: Check /docs folder
Email: support@issop.platform

🙏 Acknowledgments

Prisma - Modern database toolkit
Next.js - React framework
Socket.IO - Real-time engine
Cloudinary - Media management
shadcn/ui - UI components
Render.com - Hosting platform

📈 Roadmap

Version 2.6.0 (Planned)

Version 3.0.0 (Future)

📸 Screenshots

Admin Dashboard

Real-time monitoring with live statistics

Mobile App

Citizen request submission interface

Live Map

Real-time agent tracking

🎯 Project Status

Current Version: 2.5.0
Status: ✅ Production Ready
Last Updated: April 8, 2026
Maintained: Yes

Built with ❤️ for Smart Cities

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
.github/workflows		.github/workflows
.vscode		.vscode
Admin		Admin
Backend		Backend
Mobile		Mobile
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

🏙️ ISSOP - Intelligent Smart City Operations Platform

📋 Table of Contents

🌟 Overview

Key Capabilities

✨ Features

For Citizens (Mobile App)

For Field Agents (Mobile App)

For Administrators (Web Dashboard)

🏗️ Architecture

System Flow

🛠️ Tech Stack

Backend

Admin Dashboard

Mobile App

🚀 Getting Started

Prerequisites

Installation

1. Clone the Repository

2. Setup Backend

3. Setup Admin Dashboard

4. Setup Mobile App

📁 Project Structure

🔔 Notification System

Overview

Notification Types

Hourly Reminders

Completion Notifications

Real-Time Delivery

API Endpoints

📚 API Documentation

Base URL

Authentication

Key Endpoints

Authentication

Requests

Users

Notifications

Analytics

Swagger Documentation

🌐 Deployment

Backend (Render.com)

Admin Dashboard (Vercel)

Mobile App (Expo)

🧪 Testing

Backend Tests

Admin Dashboard

Mobile App

👥 User Roles

USER (Citizen)

AGENT (Field Agent)

ADMIN (Administrator)

SUPERADMIN (Super Administrator)

🔐 Security

📊 Performance

🤝 Contributing

Coding Standards

📝 License

📞 Support

🙏 Acknowledgments

📈 Roadmap

Version 2.6.0 (Planned)

Version 3.0.0 (Future)

📸 Screenshots

Admin Dashboard

Mobile App

Live Map

🎯 Project Status

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Packages