Domain: Governance / Public Welfare
Tagline: Empowering citizens, enabling better governance.
Civix is a full-stack web application designed to streamline the process of reporting, tracking, and resolving local civic issues such as potholes, broken streetlights, and uncollected garbage. It provides a bridge between citizens and municipal authorities, bringing accountability and transparency to local issue resolution.
Caption: Citizen view showing issue reporting interface
Local civic issues often go unnoticed or unresolved due to:
- Lack of structured, user-friendly reporting systems
- No transparent status tracking
- Difficulty in community prioritization
Caption: Step-by-step issue reporting process
- 📍 Report Issues: Submit problems with description, live location (via map), and image
- 🔁 Track Status: View transitions from Open → In Progress → Resolved
- 👍 Upvote Issues: Support others' reports to highlight common concerns
- 📊 Dashboard: View, filter, and manage all reported issues
- 🔧 Status Management: Update progress and mark resolutions
- 🔒 Role-Based Access: Secure login for Citizens and Admins
Civix now includes a fully frontend civic learning module to educate users—especially students and first-time voters—about their rights and responsibilities.
Route: /civic-education
File: src/Pages/CivicEducation.jsx
- 🧠 Interactive Quiz System with progress tracking and localStorage-based scores
- 🏆 Gamified XP system, achievements, and level-ups
- 🗂️ Tabbed layout for Overview, Learn, Quiz, and Resources
- 🔖 Bookmark favorite sections and save them locally
- 📊 Reading Progress Bar and Civic Journey visualization
- 💡 Animated “Did You Know?” facts carousel
- 📥 Downloadable PDFs and curated civic resources
- 🎉 Celebration animations on milestone completions
Civix now includes a standalone interactive simulator that allows users to step into civic leadership roles. Through animated dilemmas and slider-based decisions, users make trade-offs and explore the consequences of their choices—all within a frontend-only experience.
Route: /civic-simulator
File: src/Pages/CivicSimulator.jsx
- 🎮 Scenario Cards – Solve dilemmas like budget allocation or policy conflicts using sliders and toggles
- 🧠 Outcome Feedback – Dynamic responses based on user choices (public satisfaction, resource balance)
- 📊 Civic Style Profiling – Discover civic personas like “Planner” or “Advocate” based on decisions
- 🔁 Replayable Challenges – Rerun scenarios to improve your score and try alternate outcomes
- 🏅 XP & Badges – Earn experience points and unlock achievement badges locally
- 💡 Frontend-Only Logic – Built entirely in React with
localStoragepersistence for decision history and XP tracking
- React.js
- Tailwind CSS – Modern responsive UI
- Leaflet.js – Interactive maps for location tagging
- Node.js + Express.js
- PostgreSQL – Relational DB for reports and user data
- JWT Authentication – Secure role-based access
- Multer – File upload handling
- Swagger – API documentation
- Helmet.js – Security middleware
- Express Rate Limit – API protection
- Cloudinary – Image uploads and hosting
- JWT Authentication – Secure role-based access
- JWT-based authentication with role management
- Admin/User role separation for different access levels
- Secure password hashing using bcrypt
- Token expiration and refresh handling
- GET /api/issues - Retrieve all civic issues
- POST /api/issues - Create new issue with file upload
- PATCH /api/issues/:id/status - Update issue status (Admin only)
- POST /api/auth/signup - User registration
- POST /api/auth/login - User authentication
- Rate limiting (100 requests per 15 minutes)
- Input validation using express-validator
- XSS protection and security headers
- CORS configuration for frontend integration
- File upload security with type validation
- Interactive Swagger UI at
/api-docs - Complete endpoint documentation with examples
- Schema definitions for request/response objects
- Authentication testing directly in browser
- PostgreSQL for reliable data storage
- Optimized queries with proper indexing
- User management with secure credential storage
- Issue tracking with status management
- Image upload support for issue reporting
- File validation and security checks
- Organized storage in uploads directory
- Efficient file handling with Multer middleware
Implementation:
darkMode: 'class'intailwind.config.js- User preference saved via
localStorage - Toggle switch:
src/ThemeToggle.jsx(used inHome.jsx)
How to Use:
- Locate the toggle button (🌙/☀️) in the header
- Click to switch between:
- Light Mode: White/light gray backgrounds (
bg-slate-50) with dark text (text-gray-900) - Dark Mode: Dark gray backgrounds (
dark:bg-gray-800) with light text (dark:text-gray-100)
- Light Mode: White/light gray backgrounds (
Caption: Admin dashboard with issue management tools
- Node.js 16+
- npm 8+
- PostgreSQL 14+
- Cloudinary account (for image uploads)
# Register new user
curl -X POST http://localhost:5000/api/auth/signup \
-H "Content-Type: application/json" \
-d '{"username":"john_doe","email":"john@example.com","password":"password123"}'
# Login user
curl -X POST http://localhost:5000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"john@example.com","password":"password123"}'# Get all issues
curl -X GET http://localhost:5000/api/issues
# Create new issue with image
curl -X POST http://localhost:5000/api/issues \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-F "title=Pothole on Main Street" \
-F "description=Large pothole causing traffic issues" \
-F "location=Main Street & 5th Ave" \
-F "category=road" \
-F "file=@/path/to/image.jpg"
# Update issue status (Admin only)
curl -X PATCH http://localhost:5000/api/issues/1/status \
-H "Authorization: Bearer ADMIN_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status":"in-progress"}'- Swagger UI:
http://localhost:5000/api-docs - Interactive testing of all endpoints
- Complete schema documentation
- Authentication examples
📦 1.Clone the repository:
git clone https://github.com/Harshs16/civix.git
cd Civix
📦 2. **Install Dependencies**
Make sure you have **Node.js** and **npm** installed.
Then, install the project dependencies:
```bash
npm install
Use a meaningful branch name:
git checkout -b your-feature-name
Example:
git checkout -b improve-readme
🛠️ 4. Make Your Changes
- Improve the code, fix bugs, or update docs.
- If you're running the project:
npm start
✅ 5. Stage and Commit
git add .
git commit -m "feat: your clear and concise commit message"
🚀 6. Push Your Branch
git push origin your-feature-name
🔁 7. Create a Pull Request
- Go to your forked repo on GitHub
- Click “Compare & pull request”
- Add a helpful description of what you changed and why
- 🔔 Push notifications for issue updates
- 📈 Analytics for civic issue trends
- 🌐 Multilingual support
- 📱 Mobile app (React Native)
Pull requests are welcome! For major changes, please open an issue first to discuss your ideas.
MIT License. See LICENSE file for more details.