Kuzhiyundo?

Community-driven Pothole & Road Defect Tracking Platform

🌐 kuzhiyundo.com

Features • Tech Stack • Getting Started • Contributing • 🐛 Report a Bug • License

---

Kuzhiyundo? is an open-source, community-driven platform designed to crowdsource the mapping of potholes and bad road conditions. By empowering users to report, vote on, and avoid road hazards, the project aims to promote safer driving and hold authorities accountable.

The name "Kuzhiyundo" translates roughly to "Are there potholes?" in Malayalam.

🚀 Features

• 🗺️ Interactive Dark Map: A sleek, fully featured interactive map for browsing and hunting for potholes seamlessly.
• ✍️ Route Drawing Engine: Automatically maps out the most accurate pothole segment using OSRM routing. No more guessing exactly where the bad road starts and ends.
• 🚦 Severity Indicators: Color-coded paths and neon markers denote the severity of the road defect (Low, Medium, High).
• 👍 Voting System: Community members can upvote or downvote reported potholes to ensure report accuracy and prioritize repair efforts.
• 📸 Image Uploading: Users can attach visual evidence of potholes (compressed to 800×800 JPEG client-side before saving).
• 🔐 Authentication: Secure Google Sign-In using Firebase Authentication.
• ⚡ Realtime Updates: Potholes and votes sync instantly to all connected users without a page reload using Firestore real-time listeners.
• 🛡️ App Check: reCAPTCHA v3-backed Firebase App Check protects all API routes and Firestore writes from abuse.
• 🔍 Location Search: OLA Maps-powered address autocomplete to quickly navigate the map.

🛠️ Tech Stack

Frontend

• Next.js 15 (App Router)
• React 19
• Tailwind CSS v4
• Leaflet & react-leaflet for interactive maps
• react-leaflet-cluster for marker clustering
• Framer Motion for animations
• Lucide React for iconography

Backend & Data

• Firebase Firestore (Database — images stored as base64)
• Firebase Auth (Google Provider Auth)
• Firebase App Check (reCAPTCHA v3 — protects API routes and Firestore from abuse)

External APIs

• OSRM Router API for routing polylines
• Nominatim for reverse geocoding
• OLA Maps for address autocomplete (server-side only)
• Open Data Kerala GeoJSON for constituency/LSGD point-in-polygon lookup
• Google Maps Polyline Codec for encoding/decoding OSRM routes

🏁 Getting Started

Prerequisites

Ensure you have the following installed on your local machine:

• Node.js (v18 or higher)
• npm or yarn or pnpm
• A Firebase Project (with Firestore and Authentication enabled)
• Firebase App Check configured with reCAPTCHA v3

Installation

1. Clone the repository:

   git clone https://github.com/sajithlaldev/kuzhiyundo.git
   cd kuzhiyundo

2. Install dependencies:

   npm install

3. Set up Environment Variables: Create a .env.local file in the root directory based on the .env.example:

   NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
   NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
   NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
   NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project_id.firebasestorage.app
   NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
   NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
   NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id
   NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your_recaptcha_v3_site_key
   OLA_MAPS_API_KEY=your_ola_maps_api_key   # server-side only, used in /api/search

4. Run the development server:

   npm run dev

   Open http://localhost:3000 with your browser to see the application running.

🤝 Contributing

This is an open-source project, and contributions are highly appreciated! Whether it's adding new features, fixing bugs, or improving documentation, you can help make Kuzhiyundo? better.

How to Contribute

1. Fork the project.
2. Create your Feature Branch: git checkout -b feature/AmazingFeature
3. Commit your changes: git commit -m 'Add some AmazingFeature'
4. Push to the Branch: git push origin feature/AmazingFeature
5. Open a Pull Request.

Development Guidelines

• Always format your code before committing (npm run lint).
• Keep components modular and reusable where possible.
• Update documentation when adding new configuration or system capabilities.

🐛 Bug Reports & Feature Requests

Found a bug or have a feature idea? Please open an issue on the Issue Tracker.

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

_{Built with ❤️ by the open-source community for better, safer roads.}