{"id":51463274,"url":"https://github.com/kulkarnishub377/civicmind","last_synced_at":"2026-07-06T08:01:00.620Z","repository":{"id":368843236,"uuid":"1287119205","full_name":"kulkarnishub377/CivicMind","owner":"kulkarnishub377","description":"AI-powered platform that helps communities make smarter decisions using real-time data, predictive analytics, and autonomous AI agents","archived":false,"fork":false,"pushed_at":"2026-07-02T12:50:03.000Z","size":3620,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-02T14:03:39.070Z","etag":null,"topics":["ai","fastapi","gemini","google-cloud","nextjs","python","vertext-ai"],"latest_commit_sha":null,"homepage":"https://kulkarnishub377.github.io/CivicMind/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kulkarnishub377.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-02T11:54:56.000Z","updated_at":"2026-07-02T12:50:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kulkarnishub377/CivicMind","commit_stats":null,"previous_names":["kulkarnishub377/civicmind"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kulkarnishub377/CivicMind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2FCivicMind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2FCivicMind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2FCivicMind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2FCivicMind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kulkarnishub377","download_url":"https://codeload.github.com/kulkarnishub377/CivicMind/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2FCivicMind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35182322,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","fastapi","gemini","google-cloud","nextjs","python","vertext-ai"],"created_at":"2026-07-06T08:00:59.473Z","updated_at":"2026-07-06T08:01:00.611Z","avatar_url":"https://github.com/kulkarnishub377.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CivicMind - Community Decision Intelligence Platform\n\n\u003cdiv align=\"center\"\u003e\n\n# 🏙️ CivicMind\n## Community Decision Intelligence Platform\n\n**AI-powered platform that helps communities make smarter decisions using real-time data, predictive analytics, and autonomous AI agents**\n\n[![Google Cloud](https://img.shields.io/badge/Google%20Cloud-Vertex%20AI-blue)](https://cloud.google.com/vertex-ai)\n[![Gemini](https://img.shields.io/badge/Gemini-2.5-orange)](https://ai.google.dev/)\n[![BigQuery](https://img.shields.io/badge/BigQuery-Analytics-green)](https://cloud.google.com/bigquery)\n[![FastAPI](https://img.shields.io/badge/FastAPI-Backend-teal)](https://fastapi.tiangolo.com/)\n[![Vanilla JS](https://img.shields.io/badge/Vanilla%20JS-ES6-yellow.svg)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003c/div\u003e\n\n\n---\n\n## 📸 Interface Preview\n\nHere is a visual overview of the **CivicMind** Glassmorphic platform:\n\n| 📊 City Dashboard | ⚡ Executive Decision Center |\n|:---:|:---:|\n| ![City Dashboard](frontend_demo/dashboard.png) | ![Decision Center](frontend_demo/desion.png) |\n| *Real-time metrics, comparison trends, and Community Pulse* | *Multi-agent insights, priority risk queue, and action recommendations* |\n\n| 🛡️ Citizen Operations Portal | 🧠 AI Forecasting \u0026 Analytics |\n|:---:|:---:|\n| ![Citizen Portal](frontend_demo/citizen.png) | ![Forecasting Analytics](frontend_demo/forcaste.png) |\n| *Citizen issue filing form and dynamic resolution logging* | *Predictive ML trends, confidence bounds, and impact analysis* |\n\n| 💬 AI Decision Assistant |\n|:---:|\n| ![AI Chat Assistant](frontend_demo/ai.png) |\n| *Natural language query agent with Vertex AI and RAG integration* |\n\n---\n\n## 🎯 Problem Statement\n\nCommunities generate massive amounts of data — citizen complaints, weather, traffic, pollution, water usage, public health — but decision-makers struggle to answer:\n\n- **What** is happening?\n- **Why** is it happening?\n- **What will** happen next?\n- **What should** we do?\n\n**CivicMind** becomes the AI brain for community decision-making.\n\n---\n\n## 🏗️ Architecture\n\n```\nData Sources (Mock/BigQuery)\n        ↓\n   Analytics Engine\n        ↓\n   Vertex AI + Gemini\n        ↓\n   Agent Layer (4 AI Agents)\n   ├── 🌿 Environment Agent → AQI, Weather, Flood Risk\n   ├── 🚗 Mobility Agent → Traffic, Transit, Congestion  \n   ├── 👥 Citizen Agent → Complaints, Sentiment, Satisfaction\n   └── 💡 Recommendation Agent → Combines all → Action Plans\n        ↓\n   Community Dashboard + Command Center + Chat + Simulator\n```\n\n---\n\n## 🚀 Features\n\n### 1. Executive Command Center (`/decision-center`)\n- **Critical Issues Table** with severity, confidence, and trend indicators\n- **Action Items** with Impact vs Cost priority matrix\n- **Agent Collaboration Timeline** — watch AI agents detect, analyze, and collaborate in real-time\n- **Community Pulse** — sentiment analysis with ward-by-ward breakdown\n- **AI Executive Summary** — one-paragraph crisis overview\n\n### 2. Community Dashboard (`/`)\n- Real-time metrics: AQI, Traffic, Water Usage, Complaints, Safety, Community Pulse\n- Community Health Score (0-100) with animated score drop during crisis\n- 5-ward comparison bars with crisis indicators\n- 30-day trend charts\n- **Explainable AI** — every prediction includes WHY\n\n### 3. AI Chat Assistant (`/chat`)\n- \"Ask Your Community\" natural language interface\n- Agent-attributed responses (Environment/Mobility/Citizen/Recommendation)\n- Confidence scores on every response\n- Explainable AI — every answer includes WHY\n- Suggested crisis-related questions\n\n### 4. Predictive Analytics (`/analytics`)\n- Flood, Water, Traffic, Waste, Pollution risk predictions\n- AQI/Rainfall/Traffic/Sentiment trend charts\n- Radar ward comparison\n- Time range selector + ward filters\n\n### 5. What-If Simulator (`/simulator`)\n- **Digital Twin** — simulate policy changes before implementation\n- Before/After community score comparison\n- Risk level reduction visualization\n- **Explainable AI** — every simulation explains WHY the predicted impact\n- Crisis Response Demo scenario\n- Custom scenario input\n\n### 6. Community Health Score\n- **20%** Environment | **20%** Mobility | **20%** Water | **20%** Safety | **20%** Satisfaction\n- Per-ward breakdown with category scores\n- AI explains score changes\n\n### 7. Live Community Health Map\n- SVG city map with ward-level health visualization\n- Color-coded by score (Green/Yellow/Orange/Red)\n- Click to drill down into ward details\n- Pulsing indicators for crisis wards\n\n### 8. Explainable AI (贯穿所有功能)\n- Every prediction answers **WHY**\n- Driver analysis with contribution bars\n- Confidence intervals\n- Methodology transparency\n- Agent attribution on all AI outputs\n\n### 9. Community Pulse\n- Sentiment analysis from citizen complaints\n- Positive/Neutral/Negative breakdown\n- Ward-by-ward pulse scores\n- AI insight on sentiment drivers\n\n---\n\n## 🛠️ Tech Stack \u0026 Architecture Deep-Dive\n\n### 1. Unified Frontend Client Stack\n*   **Structure:** Semantic **HTML5** structure optimized for fast rendering and browser search engine indexation.\n*   **Styling (Modern Glassmorphic Slate Theme):** Pure **CSS3** design utilizing:\n    *   Glassmorphism blur filters (`backdrop-filter: blur(12px)`) with subtle borders (`rgba(255, 255, 255, 0.07)`).\n    *   Interactive radio selection capsules and custom ranges/sliders.\n    *   Sleek scrollbar modifications to replace chunky default browser layouts.\n    *   Responsive layouts using dynamic grids (`display: grid`) and flexboxes.\n    *   Color-coded glowing urgency indicators matching ticket levels.\n*   **Application Logic:** Modular **ES6 JavaScript** featuring:\n    *   Active view controller and client-side page state retention.\n    *   Local database fallbacks to support zero-downtime, fully interactive offline demos via `file:///` protocol.\n    *   Dynamic DOM rendering and custom HTML escaper layers.\n*   **Data Visualization:** **Chart.js v4 (via CDN)** rendering line charts with confidence bounds, multi-dataset ward comparisons, complaint categories doughnuts, and simulator outcomes comparison graphs.\n*   **Icons \u0026 Assets:** **FontAwesome Icons v6.5** and Google Fonts (**Sora**, **Outfit**, **JetBrains Mono**).\n\n### 2. High-Performance API Backend\n*   **Framework:** **FastAPI 0.111.0** (Python 3.10+) serving high-speed JSON responses.\n*   **Routing \u0026 Controllers:** Segmented routers (Dashboard, Chat, Predict, Recommend, Simulate, Agents, Decision Center).\n*   **Static Serving:** Configured via `aiofiles` and `StaticFiles` to serve the unified static UI natively from root `/`, creating a single-port deployment structure.\n*   **ASGI Server:** **Uvicorn 0.30.0** handling async request loops and reload triggers.\n*   **Validation:** **Pydantic v2** enforcing strict request/response schema boundaries.\n\n### 3. AI Agents \u0026 Machine Learning Core\n*   **Predictive Modeling:** **Scikit-Learn 1.5.0** \u0026 **NumPy** power ML algorithms that forecast flood probability, water scarcity margins, traffic indices, waste overflow limits, and emission metrics.\n*   **Data Manipulation:** **Pandas 2.2.2** generating time-series forecast vectors.\n*   **Generative AI Orchestration:** **Google Gemini 2.5** (via `google-generativeai` and Vertex AI) powers the:\n    *   **Decision Strategy Synthesizer:** Compiles raw ward statistics into actionable policy targets.\n    *   **Intelligent Chat Assistant:** Natural language search answering with citations, references, and follow-up suggestion blocks.\n*   **Multi-Agent Collaborative Matrix:**\n    *   🌿 **EcoWatch Agent:** Assesses environment, air pollution spikes, and weather anomalies.\n    *   🚗 **TransitFlow Agent:** Assesses road delays, delays, and scheduling bottle-necks.\n    *   👥 **CivicVoice Agent:** Evaluates citizen grievances volume and public sentiment indices.\n    *   💡 **Strategy Engine:** Recommendation synthesis compiling individual metrics into critical priority queues.\n*   **Orchestration Loop:** Driven by Google's **Agent Development Kit (ADK)** combined with a custom asynchronous blackboard state machine. Rather than using external pipelines, the agents post metrics, anomalies, and observations to a central memory state, allowing the **Strategy Engine** to run complex heuristic reasoning and compile high-impact, conflict-free recommendations.\n\n### 4. Database \u0026 Cloud Architecture (Enterprise Grade)\n*   **Data Warehouse:** **Google BigQuery** (leveraged for historical logs storage).\n*   **Object Storage:** **Google Cloud Storage (GCS)** holding raw unstructured reports.\n*   **RAG Engine:** **Vertex AI Vector Search** providing fast context search injections for LLM requests.\n*   **Containerization:** **Docker** and **Docker Compose** orchestrating isolated client/server processes.\n*   **Access Security \u0026 RBAC (Future Architecture):** Planned integration with **Google Cloud Identity Platform** and **OAuth2/JWT** bearer tokens in FastAPI, implementing Role-Based Access Control (RBAC) to differentiate Citizen access (reporting and local tracking) from Government/Admin executive centers (running simulator twins and authorizing recommendations).\n\n---\n\n## 📁 Project Structure\n\n```\ncivicmind/\n├── backend/                     # FastAPI Server \u0026 App Source\n│   ├── main.py                  # Server entrypoint (serves static UI at /)\n│   ├── static/                  # ⭐ Unified Frontend static assets\n│   │   ├── index.html           # Main markup structure\n│   │   ├── styles.css           # Glassmorphic Slate stylesheet\n│   │   └── app.js               # Responsive charts \u0026 state logic\n│   ├── routers/                 # API endpoint routers\n│   │   ├── dashboard.py\n│   │   ├── chat.py\n│   │   ├── predict.py\n│   │   ├── recommend.py\n│   │   ├── simulate.py\n│   │   ├── agents.py\n│   │   └── decision_center.py\n│   ├── models/                  # Core computations \u0026 scoring\n│   │   ├── scorer.py\n│   │   └── predictor.py\n│   ├── agents/                  # Multi-Agent systems\n│   │   ├── environment_agent.py\n│   │   ├── mobility_agent.py\n│   │   ├── citizen_agent.py\n│   │   └── recommendation_agent.py\n│   └── data/generate_data.py   # Mock data generator\n│\n├── frontend_demo/               # Demo preview screenshot files\n│   ├── dashboard.png\n│   ├── desion.png\n│   ├── citizen.png\n│   ├── forcaste.png\n│   └── ai.png\n│\n├── .github/                     # GitHub community guidelines \u0026 issue templates\n├── LICENSE                      # MIT License\n├── CONTRIBUTING.md              # Contribution rules\n├── CODE_OF_CONDUCT.md           # Contributor Covenant CoC\n└── docker-compose.yml           # Multi-service container config\n```\n\n---\n\n## ⚡ Quick Start\n\n### Method 1: Served Unified Application (Recommended)\n1. **Navigate into the backend directory:**\n   ```bash\n   cd backend\n   ```\n2. **Install dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n3. **Launch the FastAPI app:**\n   ```bash\n   python main.py\n   ```\n4. **Open the live application:**\n   Go to `http://127.0.0.1:8000/` to view the fully styled CivicMind dashboard connected to the active API.\n\n### Method 2: Offline Static File Access\n1. Simply double-click and open the file [`backend/static/index.html`](file:///d:/SK_docs/projet/cdip/backend/static/index.html) in any browser.\n2. The application will run entirely client-side, automatically falling back to the local database to support charts, chat, and simulations offline!\n\n---\n\n## 🎬 Killer Demo Flow (3 Minutes)\n\n**Don't demo features. Demo a crisis.**\n\n1. **Detect** → Dashboard shows score dropping 81→68, crisis alert 🔴\n2. **Analyze** → Click Ward D on city map, see compound risk\n3. **Predict** → AI explains: \"Flood risk HIGH because rainfall +40%, drainage complaints +18%\"\n4. **Agent Timeline** → Watch 4 agents collaborate in real-time\n5. **Recommend** → Decision Center shows 6 immediate actions with Impact/Cost\n6. **Simulate** → \"Deploy emergency teams\" → Score 68→76, Flood Risk 86%→57%\n7. **Decide** → Mayor makes data-driven decision with full AI explanation\n\n**Detect → Analyze → Predict → Recommend → Simulate → Decide**\n\n---\n\n\n\n## 🔮 Future Scope\n\n- Real-time IoT sensor data integration\n- BigQuery streaming inserts\n- Vertex AI RAG with community policies\n- Cloud Run deployment\n- ADK agent deployment\n- Looker Studio dashboards\n- Mobile app\n- Multi-city support\n- Video stream analysis for traffic/safety\n\n---\n\n**CivicMind transforms fragmented community data into predictive insights, explainable recommendations, and simulated outcomes, enabling governments and communities to make smarter, faster, and more resilient decisions.**\n\nBuilt with ❤️ by [Shubham Kulkarni](https://kulkarnishub377.github.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkulkarnishub377%2Fcivicmind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkulkarnishub377%2Fcivicmind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkulkarnishub377%2Fcivicmind/lists"}