Live Demo: https://fixam.maxcit.com/

A comprehensive civic engagement ecosystem that empowers citizens to report municipal issues via WhatsApp and enables authorities to manage, analyze, and resolve them efficiently through advanced AI and automation.

Codebase/
├── frontend/              # Web interface
│   ├── admin/             # Admin Portal
│   │   ├── issues.html    # Issue Management & Timeline
│   │   ├── overview.html  # Analytics & Insights Dashboard
│   │   └── users.html     # User & Group Management
│   ├── css/
│   │   └── style.css      # Design System
│   ├── js/                # Application Logic
│   │   ├── map.js         # Interactive Civic Map
│   │   └── ...
│   ├── index.html         # Public Civic Map
│   └── dashboard.html     # Public Statistics
│
├── backend/               # Node.js API Core
│   ├── db/                # PostgreSQL Schema & Migrations
│   ├── services/
│   │   ├── aiService.js   # AI Integration (Classification, Summarization)
│   │   ├── whatsappHandler.js # Conversational Logic & State Machine
│   │   └── ...
│   ├── ai_service/        # Local Python AI Microservices
│   │   ├── main.py        # FastAPI Entrypoint
│   │   └── ...            # Whisper, NudeNet, Embeddings
│   └── ...

The primary reporting channel, designed for accessibility and ease of use.

• Conversational Reporting: Guided flow for citizens to report issues naturally.
• AI-Powered Analysis: instant categorization, summarization, and urgency detection using Embeddings & TextRank.
• Voice-to-Text: Native support for Voice Notes (Krio/English), transcribed locally via Whisper.
• Media Support: Users can send photos or videos as evidence.
• Safety First: Automated content moderation filters unsafe images (e.g., nudity) using local NudeNet.
• Location Intelligence: Handles GPS location sharing and text-based addresses with reverse geocoding.
• Duplicate Detection: Smart detection of similar issues within a 100m radius to prevent spam and redundancy.
• Automated Feedback Loop: Citizens receive real-time status updates via WhatsApp when their issue is acknowledged or resolved, keeping them informed without manual follow-ups.

Transparent real-time visualization for the community.

• Interactive Map: Visualizes reported issues with color-coded markers (Critical, In Progress, Resolved).
• Vote & Support: Citizens can upvote issues to signal priority to authorities.
• Search & Filter: Find issues by category, ID, or status.
• Statistics: Public view of resolution rates and key metrics.

A powerful suite for government and operational teams.

• Dashboard & Analytics: High-level overview of reporting trends, resolution rates, and critical hotspots.
• Issue Management:
  • Detailed view of every report with geolocation, evidence, and AI analysis.
  • Activity Timeline: Full audit trail showing who reported it, when, and every status change.
  • Status Workflow: Manage lifecycle (Acknowledged → In Progress → Fixed) with mandatory resolution notes.
• Duplicate Management: Advanced tools to link/unlink reports, aggregating votes and keeping the map clean.
• User & Group Management:
  • Manage personnel (Admins, Operations, Users).
  • Create Departments/Groups (e.g., "Roads Authority", "Water Board") to organize operational teams.
• Role-Based Access: Granular permissions for Admins vs. Operational staff.
• Persistent Filtering: Shareable URLs with pre-applied filters for efficient collaboration.

Bridging the gap between report and resolution.

• Smart Routing: Issues are automatically forwarded to the relevant department based on category (e.g., "Electricity" → Energy Authorities/EDSA).
• Instant Notifications: Operational team members receive immediate WhatsApp alerts containing:
  • 🚨 Issue Title & ID
  • 📍 Precise Location/Address
  • 🔗 Direct Link to Web Portal
• Broadcast System: Ensures entire teams are synchronized on critical infrastructure failures.

Privacy-focused, offline-capable AI services running alongside the platform.

• Text Classification: Automatically tags issues (e.g., "Pothole" → "Road Infrastructure").
• Transcription: Voice-to-text for inclusive reporting.
• Content Safety: On-device image analysis to protect the platform from abuse.

Gamifying civic engagement to encourage consistent participation.

• Earn Points: Citizens accumulate digital points for positive actions:
  • +10 Points: Reporting a valid issue.
  • +50 Points: When a reported issue is physically resolved (Verified Fix).
  • +1 Point: Each time a community member upvotes their report.
• Leaderboard: Users can track their "Citizen Score" directly via WhatsApp.
• Incentives: High-scoring citizens gain recognition, fostering a sense of ownership and civic pride.

• Node.js (v16+)
• PostgreSQL (v12+ with PostGIS)
• Python 3.8+ (for AI Service)
• FFmpeg (for voice processing)

psql -U postgres -c "CREATE DATABASE fixam_db;"

cd backend
npm install
# Configure .env (see template)
npm run db:setup  # Inits schema & seeds mock data
npm start

cd backend/ai_service
pip install -r requirements.txt
python main.py

# Serve static files from root
npx serve frontend

• Frontend: Vanilla JS, Leaflet/Mapbox, Chart.js, CSS
• Backend: Node.js, Express, Socket.io
• Database: PostgreSQL
• AI/ML: Python (FastAPI), Whisper (OpenAI), NudeNet, SentenceTransformers (Embeddings), Summa (TextRank)
• Integration: WhatsApp Business API (Meta), OpenStreetMap Nominatim

ISC