Skip to content

Commit ab26bc9

Browse files
KrishCodeswKrishCodesw
committed
final documentation
1 parent 479e28d commit ab26bc9

1 file changed

Lines changed: 112 additions & 68 deletions

File tree

‎README.md‎

Lines changed: 112 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,175 @@
1-
JanSamwaad – Crowdsourced Civic Issue Reporting
1+
# JanSamwaad – Crowdsourced Civic Issue Reporting
22

3+
> JanSamwaad is a civic-tech platform that enables citizens to report local civic issues, see them on a live map, and track how authorities respond over time.
34
4-
JanSamwaad is a civic-tech platform that enables citizens to report local civic issues, see them on a live map, and track how authorities respond over time. The goal is to make everyday issues like potholes, garbage, broken street lights, and water problems visible, transparent, and easier to resolve collaboratively.
5+
---
56

7+
## 📋 Table of Contents
68

7-
1. Problem and vision
9+
- [About](#about)
10+
- [Problem and Vision](#problem-and-vision)
11+
- [The Problem](#the-problem)
12+
- [The Vision](#the-vision)
13+
- [Core Features](#core-features)
14+
- [Citizen Features](#citizen-features)
15+
- [Admin/Official Features](#adminofficial-features)
16+
- [NGO & Community Features](#ngo--community-features)
17+
- [System Architecture](#system-architecture)
18+
- [High-Level Overview](#high-level-overview)
19+
- [Logical Components](#logical-components)
820

9-
The problem
10-
Citizens face everyday civic issues but current channels are often:
11-
12-
Fragmented (different numbers/apps for different departments)
21+
---
1322

14-
Non-transparent (no clear status, no way to track progress)
23+
## About
1524

16-
Slow (no prioritization, no data-driven planning)
25+
JanSamwaad is designed to make everyday civic issues like potholes, garbage, broken street lights, and water problems visible, transparent, and easier to resolve collaboratively. By providing a unified platform for citizens, authorities, and NGOs, we aim to improve accountability and accelerate issue resolution.
1726

18-
This leads to frustration, duplicate complaints, and poor accountability.
27+
---
1928

20-
The vision
21-
JanSamwaad aims to become a single unified interface where:
29+
## Problem and Vision
2230

23-
Citizens can easily report local problems with location and photos
31+
### The Problem
2432

25-
Issues are mapped, prioritized, and routed to the right authority
33+
Citizens face everyday civic issues but current channels are often:
2634

27-
Progress is visible to everyone, building trust and accountability
35+
- **Fragmented** – Different numbers/apps for different departments
36+
- **Non-transparent** – No clear status, no way to track progress
37+
- **Slow** – No prioritization, no data-driven planning
2838

29-
NGOs and civic groups can use data to drive campaigns and advocacy
39+
This leads to frustration, duplicate complaints, and poor accountability.
3040

41+
### The Vision
3142

32-
2. Core features
33-
Citizen features
34-
Report an Issue
43+
JanSamwaad aims to become a single unified interface where:
3544

36-
Submit a title, description, category (pothole, garbage, water, electricity, etc.)
45+
- **Citizens** can easily report local problems with location and photos
46+
- **Issues** are mapped, prioritized, and routed to the right authority
47+
- **Progress** is visible to everyone, building trust and accountability
48+
- **NGOs and civic groups** can use data to drive campaigns and advocacy
3749

38-
Attach one photo as evidence
50+
---
3951

40-
The exact location is auto-fetched and submitted with the report
52+
## Core Features
4153

42-
See a confirmation with a unique issue ID
54+
### Citizen Features
4355

44-
Issues Near You
56+
#### Report an Issue
4557

46-
Interactive map (Leaflet/OpenStreetMap style) showing issues around the user
58+
- Submit a title, description, and category (pothole, garbage, water, electricity, etc.)
59+
- Attach one photo as evidence
60+
- The exact location is auto-fetched and submitted with the report
61+
- See a confirmation with a unique issue ID
4762

48-
Colored markers or pins by status (e.g., Open / In Progress / Resolved)
63+
#### Issues Near You
4964

50-
Quick filters (category, status, distance)
65+
- Interactive map (Leaflet/OpenStreetMap style) showing issues around the user
66+
- Colored markers or pins by status (e.g., Open / In Progress / Resolved)
67+
- Quick filters (category, status, distance)
68+
- List view of nearby issues with concise cards
5169

52-
List view of nearby issues with concise cards
70+
#### My Issues
5371

54-
My Issues
72+
- Personal dashboard with all issues reported by the logged-in user
73+
- Status timeline for each issue (Submitted → In Progress → Resolved → Verified)
5574

56-
Personal dashboard with all issues reported by the logged-in user
75+
#### Real-time Updates
5776

58-
Status timeline for each issue (Submitted → In Progress → Resolved → Verified)
77+
Notifications (email/SMS/WhatsApp, depending on your implementation) when:
78+
- An issue is created
79+
- Status changes (acknowledged, in progress, resolved)
80+
- Deep links that open directly to the issue page
5981

82+
---
6083

61-
Real-time updates
84+
### Admin/Official Features
6285

63-
Notifications (email/SMS/WhatsApp, depending on your implementation) when:
86+
#### Issue Management Dashboard
6487

65-
An issue is created
88+
- Secure login for admins/officials through **RBAC** (Role Based Access Control)
89+
- Table of all issues with sorting and filters (status, category & date)
90+
- Quick view of details and photos
91+
- Ability to change status and add public updates
6692

67-
Status changes (acknowledged, in progress, resolved)
93+
#### Issue Lifecycle
6894

69-
Deep links that open directly to the issue page
95+
Configurable status flow, for example:
96+
```
97+
New → Acknowledged → In Progress → Resolved → Verified by Citizen / Rejected
98+
```
7099

71-
Admin / “Official” features
72-
Issue management dashboard
100+
- Status history with timestamps
101+
- Optional assignment to departments, wards, or officers *(In progress - currently under development)*
73102

74-
Secure login for admins/officials through RBAC (Role based access control)
103+
#### Moderation & Validation
75104

76-
Table of all issues with sorting and filters (status, category & date)
105+
- Queue of newly submitted issues that can be quickly validated
106+
- Option to reject spam/test issues with a reason visible to the citizen
107+
- Basic checks like minimum description, at least one evidence field, etc.
77108

78-
Quick view of details and photos
109+
---
79110

80-
Ability to change status and add public updates
111+
### NGO & Community Features
81112

82-
Issue lifecycle
113+
> **Note:** Optional / Roadmap features
83114
84-
Configurable status flow, for example:
115+
- Read-only dashboards for partner NGOs to monitor issues in their domain or geographies
116+
- Ability to "adopt" issues, mark involvement, or add NGO-specific updates
117+
- Aggregate statistics for campaigns (e.g., "100 garbage dumps cleaned in Ward X")
85118

86-
New → Acknowledged → In Progress → Resolved → Verified by Citizen / Rejected
119+
---
87120

88-
Status history with timestamps
121+
## System Architecture
89122

90-
Optional assignment to departments, wards, or officers (In progress - currently under development)
123+
### High-Level Overview
91124

92-
Moderation & validation
125+
| Component | Technology |
126+
|-----------|------------|
127+
| **Frontend** | Next.js (React), TypeScript, Tailwind CSS, Leaflet (OpenStreetMap) for mapping |
128+
| **Backend** | Next.js API routes or Node.js/Express with REST endpoints |
129+
| **Database** | Supabase (PostgreSQL) |
130+
| **Authentication** | Email/password, Google auth plus admin roles |
131+
| **Notifications** | Email provider (e.g., SMTP, Resend), optional SMS/WhatsApp integration |
93132

94-
Queue of newly submitted issues that can be quickly validated
133+
### Logical Components
95134

96-
Option to reject spam/test issues with a reason visible to the citizen
135+
1. **Client App** – UI components, forms, map view, state management
136+
2. **API Layer** – Authentication, authorization, issue CRUD, listing & search, admin actions
137+
3. **Geo Services** – Geospatial queries (issues near location/map bounds), clustering/pagination
138+
4. **Notification Service** – Triggered on issue creation and status changes
139+
5. **Admin Panel** – Protected pages and endpoints for validation and lifecycle management
97140

98-
Basic checks like minimum description, at least one evidence field, etc.
141+
---
99142

100-
NGO & community features (optional / roadmap)
101-
Read-only dashboards for partner NGOs to monitor issues in their domain or geographies
143+
## 🚀 Getting Started
102144

103-
Ability to “adopt” issues, mark involvement, or add NGO-specific updates
145+
1. Clone the repo
104146

105-
Aggregate statistics for campaigns (e.g., “100 garbage dumps cleaned in Ward X”)
147+
git clone https://github.com/your-username/jansamwaad.git
148+
cd jansamwaad
106149

150+
2. Install dependencies
107151

108-
System Architecture
152+
npm install
153+
# or
154+
pnpm install
109155

156+
3. Create a .env.local file (or equivalent) with values
110157

111-
High-level
112-
Frontend: Next.js (React), TypeScript, Tailwind CSS, Leaflet (OpenStreetMap) for mapping.​
158+
4. Run database migrations (prisma commands)
113159

114-
Backend: Next.js API routes or Node.js/Express with REST endpoints.​
160+
5. Start development server
115161

116-
Database: Supabase (PostgreSQL).​
162+
npm run dev
117163

118-
Auth: Email/password , Google auth plus admin roles.​
119164

120-
Notifications: Email provider (e.g., SMTP, Resend), optional SMS/WhatsApp integration.​
165+
## 🤝 Contributing
121166

122-
Logical components
123-
Client App – UI components, forms, map view, state management.
167+
Contributing, suggestions, and issue reports are welcome.
124168

125-
API Layer – authentication, authorization, issue CRUD, listing & search, admin actions.
169+
Open an issue describing the bug/feature clearly.
126170

127-
Geo Services – geospatial queries (issues near location/map bounds), clustering/pagination.​
171+
For major changes, discuss in an issue first so design decisions are aligned.
128172

129-
Notification Service – triggered on issue creation and status changes.
173+
Follow existing code style and include basic tests where relevant.
130174

131-
Admin Panel – protected pages and endpoints for validation and lifecycle management.
175+
---

0 commit comments

Comments
 (0)