Turning citizen voices into data-informed infrastructure decisions.
A multilingual, geospatial AI platform for citizen feedback, public investment prioritization, and policy decision support.
- Overview
- Problem Statement
- Key Features
- System Architecture
- Technology Stack
- Project Structure
- Getting Started
- API Documentation
- Deployment
- Supported Regions and Languages
- Privacy and Security
- Testing
- Future Scope
- Contributing
- License
- Author
CivicPulse is a multilingual AI-powered citizen infrastructure intelligence platform designed to connect grassroots public concerns with infrastructure planning and capital investment decisions.
Governments and public institutions receive citizen complaints through many different channels. However, these reports are often fragmented, difficult to analyze across languages, and disconnected from the processes used to prioritize public spending.
CivicPulse brings these workflows into a unified platform combining citizen feedback processing, geospatial analysis, infrastructure project ranking, expenditure-gap analysis, policy simulation, and AI-assisted reporting.
The project is designed around Digital Public Good principles, open data interoperability, and transparent decision support.
- Make citizen feedback more accessible across language barriers.
- Identify geographic concentrations of infrastructure problems.
- Prioritize projects using configurable, explainable criteria.
- Highlight potential gaps between public needs and planned investment.
- Support evidence-informed infrastructure and policy planning.
- Provide machine-readable data for interoperability with external tools.
Infrastructure investment may not reflect the geographic distribution or urgency of citizen needs.
Authorities need better ways to identify locations experiencing problems with roads, water, healthcare, energy, education, and other essential services.
Citizens who communicate in regional languages may encounter difficulties when reporting problems through systems designed primarily for a single language.
Voice reports, petitions, web forms, and other submissions can be difficult to consolidate into a consistent analytical dataset.
Infrastructure prioritization requires transparent criteria that account for demand, deficits, vulnerability, feasibility, and expected social impact.
CivicPulse aims to address these challenges through a unified citizen-feedback and infrastructure decision-support workflow.
- Voice-based grievance submission and speech-to-text processing.
- Web-based complaint forms.
- Language identification and translation workflows.
- Infrastructure-sector classification.
- Urgency and severity scoring.
- Community petitions and upvoting.
- Messaging-channel and SMS integration simulations.
- Interactive GIS visualization using Leaflet.
- Geographic clustering of citizen complaints using DBSCAN.
- Demand-hotspot identification.
- Infrastructure-deficit and vulnerability overlays.
- District-level demographic drilldowns.
- GeoJSON-compatible geographic data.
CivicPulse uses Multi-Criteria Decision Analysis (MCDA) to rank candidate projects using configurable weights.
The conceptual scoring model is:
[ S = w_1D + w_2I + w_3V + w_4F ]
Where:
- (S): Project priority score.
- (D): Citizen demand.
- (I): Infrastructure deficit.
- (V): Population vulnerability.
- (F): Project feasibility.
- (w_1, w_2, w_3, w_4): Configurable criterion weights.
The platform is designed to display ranked recommendations, estimated beneficiaries, indicative costs, implementation timelines, and relevant Sustainable Development Goal alignments.
These scores support decision-making and do not replace engineering assessments or formal public procurement procedures.
- Compares infrastructure needs with planned capital allocations.
- Identifies high-demand areas that may be inadequately funded.
- Highlights potential spending mismatches.
- Supports analysis of lower-priority versus high-need projects.
- Generates recommendations for further review by planning and finance teams.
- Interactive budget allocation across seven infrastructure sectors.
- Configurable vulnerability equity multiplier.
- Scenario-based comparison of investment choices.
- Indicative deficit-reduction and citizen-satisfaction metrics.
- Illustrative SDG progress and economic multiplier estimates.
Simulation outputs depend on the assumptions and datasets provided. They should not be interpreted as guaranteed economic forecasts.
- Drafts policy briefs and executive summaries.
- Assists with procurement tender specifications.
- Generates structured citizen-status notifications.
- Organizes findings into decision-support documents.
- Connects recommendations to underlying data where supported by the implementation.
AI-generated documents require human review before official use.
- CSV data exports.
- GeoJSON exports for geographic applications.
- JSON-LD data representations.
- REST API interoperability.
- OpenAPI documentation.
- Swagger UI and ReDoc support.
The goal is to make CivicPulse data easier to inspect, exchange, and reuse across compatible tools.
The following Mermaid diagram describes the high-level flow from citizen feedback to analytical insights and frontend dashboards.
flowchart TB
A["Citizen Feedback<br/>Voice · Web · Petitions · SMS"] --> B["Multilingual NLP<br/>Transcription · Translation"]
B --> C["Classification<br/>Sector · Urgency"]
C --> D["FastAPI Backend"]
D --> E[("Regional Data Store")]
E --> F["GIS Hotspot Engine<br/>DBSCAN"]
E --> G["Project Ranking<br/>MCDA"]
E --> H["Expenditure Auditor"]
E --> I["Policy Simulator"]
E --> J["AI Policy Copilot"]
F --> K["REST API"]
G --> K
H --> K
I --> K
J --> K
K --> L["React Frontend"]
L --> M["GIS Dashboard"]
L --> N["Recommendations"]
L --> O["Spend Gap Analysis"]
L --> P["Policy Simulator"]
L --> Q["Open Data Hub"]
| Layer | Responsibility |
|---|---|
| Citizen input | Collects citizen reports, petitions, and voice submissions |
| NLP processing | Processes language, transcribes audio, and classifies complaints |
| API backend | Validates requests and coordinates application services |
| Data layer | Supplies regional, demographic, complaint, and investment data |
| Analytics | Performs hotspot detection, project ranking, and expenditure analysis |
| Policy intelligence | Supports scenario analysis and AI-assisted document drafting |
| Frontend | Presents maps, recommendations, reports, and interactive tools |
| Interoperability | Exposes APIs and supported machine-readable data exports |
The diagram represents the intended logical architecture. Actual integrations and production capabilities depend on the implemented services and configuration.
| Technology | Purpose |
|---|---|
| React 19 | Frontend application |
| JavaScript | Frontend logic |
| Vite | Frontend development and build tooling |
| Python | Backend and analytics logic |
| FastAPI | REST API framework |
| Pydantic | Request and data validation |
| Leaflet | Interactive mapping |
| DBSCAN | Geographic density clustering |
| MCDA | Multi-criteria project prioritization |
| GeoJSON | Geographic data representation |
| CSV | Tabular data exchange |
| JSON-LD | Structured linked data |
| OpenAPI | API specification |
| Swagger UI / ReDoc | Interactive API documentation |
| Pytest | Backend testing |
| Cloudflare Workers | Frontend asset deployment, when configured |
CivicPulse/
├── backend/
│ ├── app/
│ │ ├── api/
│ │ │ └── endpoints.py
│ │ ├── models/
│ │ │ └── schemas.py
│ │ ├── services/
│ │ │ ├── multilingual_nlp.py
│ │ │ ├── voice_processor.py
│ │ │ ├── data_store.py
│ │ │ ├── hotspot_engine.py
│ │ │ ├── recommendation_engine.py
│ │ │ ├── misalignment_engine.py
│ │ │ ├── policy_simulator.py
│ │ │ └── ai_copilot.py
│ │ └── main.py
│ ├── tests/
│ │ └── test_api.py
│ └── requirements.txt
│
├── frontend/
│ ├── src/
│ │ ├── components/
│ │ │ ├── Navbar.jsx
│ │ │ ├── GISMap.jsx
│ │ │ ├── CitizenPortal.jsx
│ │ │ ├── RecommendationView.jsx
│ │ │ ├── MisalignmentView.jsx
│ │ │ ├── PolicySimulator.jsx
│ │ │ ├── AICopilotModal.jsx
│ │ │ └── DPGHub.jsx
│ │ ├── services/
│ │ │ └── api.js
│ │ ├── App.jsx
│ │ └── index.css
│ ├── index.html
│ ├── package.json
│ └── package-lock.json
│
├── README.md
├── SECURITY.md
├── LICENSE
├── NOTICE
├── COPYRIGHT
├── .nvmrc
├── package.json
└── wrangler.jsonc
This tree reflects the documented architecture. Keep it synchronized with the files actually present in the repository.
Install:
- Python 3.10 or later.
- Node.js 18 or later.
- npm 9 or later.
- Git.
Verify the installations:
python --version
node --version
npm --version
git --versionFrom the repository root:
npm install
npm run devThe root development script is intended to start both the FastAPI backend and React frontend.
Expected local addresses:
| Service | URL |
|---|---|
| Frontend | http://localhost:5173 |
| Backend API | http://localhost:8000 |
| Swagger UI | http://localhost:8000/docs |
| ReDoc | http://localhost:8000/redoc |
From the repository root:
cd backend
python -m pip install -r requirements.txt
python -m uvicorn app.main:app --port 8000 --reloadThe backend should be available at:
http://localhost:8000
API documentation:
http://localhost:8000/docs
Open a second terminal:
cd frontend
npm install
npm run devOpen:
http://localhost:5173
If the frontend and backend run on different hosts, configure the API base URL and CORS settings appropriately.
FastAPI provides interactive documentation when the backend is running.
| Documentation | Endpoint |
|---|---|
| Swagger UI | /docs |
| ReDoc | /redoc |
| OpenAPI schema | /openapi.json |
These endpoints describe the routes registered by the running backend.
For a deployed instance, replace localhost:8000 with the backend's actual address.
The repository includes configuration for deploying the built frontend as static assets.
Typical build configuration:
- Root directory:
/ - Build command:
npm run build - Deploy command:
npx wrangler deploy
The root build installs the frontend dependencies and builds the frontend assets. The wrangler.jsonc configuration serves the generated frontend and supports single-page application routing.
The backend must be hosted separately from the static frontend deployment.
Deployment checklist:
- Install Python dependencies.
- Configure production environment variables.
- Set the allowed frontend origins.
- Configure durable storage and production authentication.
- Deploy the FastAPI application to a Python-compatible host.
- Set the frontend API base URL.
- Verify the API, CORS, authentication, and application routes.
| Variable | Purpose |
|---|---|
CIVICPULSE_ENV |
Backend environment |
CIVICPULSE_ALLOWED_ORIGINS |
Allowed frontend origins |
CIVICPULSE_DEMO_MODE |
Controls demonstration sign-in behavior |
VITE_API_BASE_URL |
Public frontend API base URL |
Example frontend configuration:
VITE_API_BASE_URL=https://api.example.org/apiThe correct URL depends on the API routes registered by the deployed backend.
Security: Variables beginning with VITE_ are embedded in public frontend assets. Never place secrets or private credentials in them.
Consult SECURITY.md before production deployment.
CivicPulse documents regional baseline data for the following BRICS nations.
Actual regional coverage and language-processing quality depend on the configured datasets and processing services.
Citizen feedback may contain sensitive personal or location information. Deployments should incorporate appropriate safeguards.
- Validate input and restrict abusive requests.
- Apply authentication and authorization to administrative functions.
- Use HTTPS for production traffic.
- Configure CORS for trusted origins only.
- Minimize collection of personally identifiable information.
- Apply privacy-aware handling to geographic exports.
- Protect credentials through environment variables or secret-management systems.
- Establish appropriate data retention and deletion procedures.
- Use durable session and user storage in production.
- Review AI-generated recommendations before making consequential decisions.
Demonstration authentication and in-memory user/session stores are not suitable for production deployments.
Run the backend test suite from the repository root:
python -m pytest backend/tests -vRecommended verification areas include:
- API validation and error handling.
- Citizen grievance processing.
- Language and sector classification.
- Geographic hotspot calculations.
- MCDA ranking behavior.
- Expenditure-gap analysis.
- Policy simulation constraints.
- Data export formats.
- Production CORS and authentication.
Only report test counts and results after running the tests against the current codebase.
Potential extensions include:
- Production messaging and SMS integrations.
- Expanded regional language and dialect support.
- Improved voice processing in noisy environments.
- Regularly updated and independently verified infrastructure datasets.
- Historical-data validation for prioritization and policy models.
- Role-based access control and audit logging.
- Stronger privacy and security evaluations.
- Integration with authorized government data systems.
- Accessibility and low-bandwidth improvements.
- Independent assessments of open-data interoperability and Digital Public Good readiness.
Contributions, bug reports, and suggestions are welcome.
- Fork the repository.
- Create a feature branch.
- Implement your change.
- Run the relevant tests.
- Commit your changes with a descriptive message.
- Submit a pull request describing the change.
Example:
git checkout -b feature/your-feature
git add .
git commit -m "feat: describe your change"
git push origin feature/your-featureDo not commit credentials, real citizen records, or private datasets.
Copyright © 2026 Praveen Reddy.
See the repository's LICENSE, NOTICE, and COPYRIGHT files for the actual licensing terms.
The project documentation references AGPL-3.0 and Apache License 2.0. Ensure the checked-in license files consistently establish the intended licensing arrangement before distributing the project.
Praveen Reddy
AI/ML Developer · Software Developer · Open-Source Builder
- GitHub: @reddy895
CivicPulse
Building a more transparent, inclusive, and data-informed approach to infrastructure planning.