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
- Backend Testing: Jest, Supertest, MongoDB Memory Server
- Frontend Unit/Component Testing: Vitest, React Testing Library
- Frontend E2E Testing: Cypress
We have a comprehensive testing suite to ensure code quality and stability.
These tests cover the API endpoints. They run against an in-memory MongoDB database to ensure a clean, isolated environment for each test run, preventing any impact on your development database.
To run all backend tests, navigate to the /backend directory and run:
npm testThese tests verify that individual React components render and behave correctly in isolation. We use Vitest and React Testing Library for this.
To run all frontend unit tests, navigate to the /frontend directory and run:
npm testE2E tests simulate real user workflows in a browser from start to finish. This helps catch bugs in critical user journeys like logging in, creating a post, or navigating the application.
To open the Cypress Test Runner, navigate to the /frontend directory and run:
npm run cypress:open
### 📥 Installation
📦 1.**Clone the repository**:
```bash
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.