Khabri - Intelligent City Issue Reporting Platform

Overview

Khabri is a real-time city issue reporting platform that uses Google Gemini AI to validate, aggregate, and escalate citizen reports to government authorities. The platform reduces noise through intelligent aggregation and provides transparency to citizens about government response.

🎯 Key Features

• AI-Powered Validation: Gemini AI validates reports for authenticity and quality
• Noise Reduction: Aggregates multiple reports of same issue into clean data
• Government Integration: Severity-aware threshold monitoring with department routing
• Real-time Transparency: Citizens can see escalation status and government response
• Social Media Integration: Processes Twitter/X reports through same AI pipeline

🏗️ Architecture

• Backend: Google Firebase (Auth, Firestore, Functions, Storage)
• AI Processing: Google Gemini AI (Multimodal analysis)
• Message Queue: Google Cloud Pub/Sub
• Notifications: FCM, SMS Gateway, Email Service
• Language: TypeScript/Node.js

📋 Project Status

Current Phase: Setup & Planning
Development Timeline: 8-10 weeks to MVP
Last Updated: January 2024

Development Phases

• Architecture Design & Documentation
• Low Level Design (LLD)
• API Specifications & Mock Stubs
• Phase 1: Project Setup & Infrastructure
• Phase 2: Authentication System
• Phase 3: Core Report Processing
• Phase 4: Gemini AI Integration
• Phase 5: Aggregation System
• Phase 6: Government Threshold & Alerts
• Phase 7: Location-based API
• Phase 8: Social Media Integration
• Phase 9: Testing & Quality Assurance
• Phase 10: Deployment & Production

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Google Cloud Platform account
• Firebase CLI
• Git

Repository Setup

# Clone the repository
git clone https://github.com/your-org/khabri-backend.git
cd khabri-backend

# Install dependencies
npm install

# Install Firebase CLI globally
npm install -g firebase-tools

# Login to Firebase
firebase login

# Initialize Firebase project (follow prompts)
firebase init

Environment Configuration

# Copy environment template
cp .env.example .env.local

# Edit environment variables
# Add your Firebase config, Gemini AI keys, etc.
nano .env.local

Development Setup

# Start Firebase emulators
npm run emulators

# Start development server
npm run dev

# Run tests
npm test

# Deploy to staging
npm run deploy:staging

📁 Project Structure

khabri-backend/
├── docs/                          # Documentation
│   ├── LOW_LEVEL_DESIGN.md        # Technical specifications
│   ├── API_STUBS.md               # Mock API for frontend
│   └── DEVELOPMENT_PLAN.md        # Implementation roadmap
├── functions/                     # Firebase Cloud Functions
│   ├── src/
│   │   ├── auth/                  # Authentication services
│   │   ├── reports/               # Report processing
│   │   ├── aggregation/           # Data aggregation
│   │   ├── ai/                    # Gemini AI integration
│   │   ├── government/            # Government alerts
│   │   ├── location/              # Location-based APIs
│   │   └── utils/                 # Utility functions
│   ├── package.json
│   └── tsconfig.json
├── firestore/                     # Firestore configuration
│   ├── rules/                     # Security rules
│   └── indexes.json               # Database indexes
├── storage/                       # Cloud Storage rules
├── scripts/                       # Build and deployment scripts
├── tests/                         # Test suites
│   ├── unit/                      # Unit tests
│   ├── integration/               # Integration tests
│   └── e2e/                       # End-to-end tests
├── .github/                       # GitHub workflows
│   └── workflows/                 # CI/CD pipelines
├── firebase.json                  # Firebase configuration
├── .firebaserc                    # Firebase project settings
├── package.json                   # Root package configuration
└── README.md                      # This file

🔧 Available Scripts

# Development
npm run dev              # Start development server
npm run build            # Build for production
npm run serve            # Serve built functions locally

# Testing
npm test                 # Run all tests
npm run test:unit        # Run unit tests
npm run test:integration # Run integration tests
npm run test:e2e         # Run end-to-end tests
npm run test:coverage    # Generate coverage report

# Firebase
npm run emulators        # Start Firebase emulators
npm run emulators:ui     # Start emulators with UI
npm run deploy:staging   # Deploy to staging
npm run deploy:prod      # Deploy to production

# Code Quality
npm run lint             # Lint TypeScript code
npm run lint:fix         # Fix linting issues
npm run format           # Format code with Prettier
npm run type-check       # TypeScript type checking

# Database
npm run db:backup        # Backup Firestore data
npm run db:seed          # Seed test data
npm run db:migrate       # Run database migrations

🗃️ Database Schema

Core Collections

• users/{userId} - User profiles and trust scores
• reports/{reportId} - Individual validated reports (internal processing)
• aggregations/{aggregationId} - Noise-reduced aggregated issues (API primary source)
• government_alerts/{alertId} - Government notification tracking
• thresholds/config - System configuration and thresholds

See Low Level Design for complete schema specifications.

🔌 API Endpoints

Authentication

• POST /auth/register - User registration
• POST /auth/login - User authentication

Reports

• POST /reports/submit - Submit new issue report
• GET /reports/my-reports - Get user's reports
• GET /reports/{reportId} - Get report details

Location-based Queries

• GET /location/escalated-reports - Get nearby escalated issues
• GET /location/heatmap - Get issue density data

Government Dashboard

• GET /government/dashboard - Official dashboard data

See API Stubs for complete API documentation and mock responses.

🧪 Testing Strategy

Unit Tests

• Individual function testing
• Mock external dependencies
• 90%+ code coverage target

Integration Tests

• Firebase services integration
• Gemini AI pipeline testing
• End-to-end workflows

Load Testing

• Aggregation system performance
• API response times
• Concurrent user handling

📊 Monitoring & Logging

• Firebase Performance Monitoring: API performance tracking
• Google Cloud Logging: Centralized log aggregation
• Custom Metrics: Business KPIs and system health
• Alerting: SLA monitoring and incident response

🚀 Deployment

Environments

• Development: Local emulators
• Staging: Firebase staging project
• Production: Firebase production project

CI/CD Pipeline

1. Pull Request: Automated testing and linting
2. Staging Deployment: Auto-deploy to staging on merge to develop
3. Production Deployment: Manual approval for main branch
4. Rollback: Automated rollback on critical errors

🤝 Contributing

We welcome contributions! Please read our Contributing Guidelines before submitting PRs.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following our coding standards
4. Write/update tests for your changes
5. Run the test suite: npm test
6. Commit with conventional commit format: feat: add amazing feature
7. Push to your fork: git push origin feature/amazing-feature
8. Submit a Pull Request

Commit Message Convention

We use Conventional Commits:

type(scope): description

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

🔒 Security

Reporting Security Issues

Please report security vulnerabilities to: security@khabri.com

Security Measures

• Firebase Authentication with JWT tokens
• Firestore Security Rules for data access control
• Image encryption in Cloud Storage
• API rate limiting and abuse prevention
• Regular security audits and dependency updates

📈 Performance Benchmarks

Target Metrics

• Location API: <500ms response time
• Report Submission: <2s processing time
• AI Validation: <5s end-to-end
• Government Alerts: <1s delivery time
• Uptime: 99.9% availability

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@khabri.com

📄 License

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

🙏 Acknowledgments

• Google Firebase team for the robust platform
• Google Gemini AI for multimodal capabilities
• Open source community for tools and libraries

---

Built with ❤️ for better cities and transparent governance