Skip to content

README.md

Latest commit

 

History

History
408 lines (295 loc) · 8.53 KB

README.md

File metadata and controls

408 lines (295 loc) · 8.53 KB
Raw

🚗 CampusPool

A full-stack smart ride-sharing platform built for campus communities.

CampusPool helps students create, discover, join, and manage rides within their campus — making everyday transportation more affordable, convenient, and community-driven.

🔗 Live Demo

Coming soon

🎥 Project Demo

Coming soon

📌 Problem Statement

Students often travel between hostels, academic buildings, railway stations, markets, and other locations around campus.

When students travel individually:

  • Transportation costs increase.
  • Fuel is wasted.
  • Available seats in private vehicles go unused.
  • Students have no centralized way to coordinate rides.
  • Finding people travelling in the same direction becomes difficult.

CampusPool addresses this problem by providing a centralized platform where students can create and discover shared rides, join available seats, and coordinate their campus transportation.

The goal is simple:

Travel together. Save money. Reduce unnecessary trips. Build a better campus community.

✨ Features

🔐 Authentication

  • User Registration
  • User Login
  • User Logout
  • Passport-based authentication
  • Session-based authentication
  • Current-user endpoint (/auth/me)
  • Protected backend routes

🚗 Ride Management

  • Create a ride
  • View ride details
  • Edit your rides
  • Cancel your rides
  • Delete your rides
  • View available rides
  • Date and time based ride information

👥 Ride Participation

  • Join an available ride
  • Leave a joined ride
  • Automatic passenger tracking
  • Automatic seat availability
  • Full ride detection
  • Prevent duplicate joining
  • Prevent ride owners from joining their own ride

📊 Dashboard

  • View rides
  • Total ride count
  • Active ride count
  • Ride management
  • Ride status information

🎯 Smart Ride States

CampusPool dynamically handles ride states such as:

  • Available
  • Joined
  • Full
  • Cancelled

The interface updates available actions based on the current user's relationship with the ride.

🛠 Tech Stack

Frontend

  • React
  • Vite
  • React Router
  • Tailwind CSS
  • Axios
  • React Hook Form
  • Zod
  • Lucide React
  • Framer Motion

Backend

  • Node.js
  • Express.js
  • Passport.js
  • Express Session
  • Mongoose

Database

  • MongoDB
  • MongoDB Atlas

🏗️ Architecture

CampusPool follows a full-stack client-server architecture.

                    ┌─────────────────────┐
                    │      CampusPool     │
                    │     React Client    │
                    └──────────┬──────────┘
                               │
                               │ HTTP / Axios
                               ▼
                    ┌─────────────────────┐
                    │    Express Server   │
                    │       REST API      │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
        Authentication     Ride APIs        Dashboard
        Passport/Session   Create/Join/      Ride Management
                          Leave/Edit/Delete
                               │
                               ▼
                    ┌─────────────────────┐
                    │     MongoDB Atlas   │
                    │   Users & Rides     │
                    └─────────────────────┘

📂 Project Structure

The project is divided into separate frontend and backend responsibilities.

CampusPool/
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── context/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── utils/
│   │   └── App.jsx
│   │
│   ├── public/
│   ├── package.json
│   └── vite.config.js
│
├── backend/
│   ├── Controller/
│   │   ├── auth.js
│   │   └── dashboard.js
│   │
│   ├── models/
│   │   ├── userSchema.js
│   │   └── rideSchema.js
│   │
│   ├── Routes/
│   │   ├── auth.js
│   │   └── dashboard.js
│   │
│   ├── utils/
│   │   ├── ExpressError.js
│   │   └── wrapAsync.js
│   │
│   ├── middlewares.js
│   ├── schema.js
│   └── index.js
│
└── README.md

🔐 Authentication Flow

CampusPool uses Passport.js with session-based authentication.

User Login
     │
     ▼
React Frontend
     │
     │ POST /auth/login
     ▼
Express Backend
     │
     ▼
Passport Authentication
     │
     ▼
Session Created
     │
     ▼
Authenticated User

The frontend can restore the current authenticated user through:

GET /auth/me

This allows the React application to maintain the user's authentication state even after a page refresh.

🚦 Ride Lifecycle

A ride can move through different states depending on its availability and owner's actions.

                ┌──────────────┐
                │   Available  │
                └──────┬───────┘
                       │
              Last seat occupied
                       │
                       ▼
                ┌──────────────┐
                │     Full     │
                └──────────────┘


Available / Full
       │
       │ Owner cancels
       ▼
┌──────────────┐
│  Cancelled   │
└──────────────┘


Any ride
   │
   │ Owner deletes
   ▼
Removed from database

👤 User Actions

Ride Owner

The owner can:

  • Edit the ride
  • Cancel the ride
  • Delete the ride

Other Users

Users can:

  • Join an available ride
  • Leave a ride they joined
  • View ride information

The UI dynamically changes according to:

  • Current user
  • Ride ownership
  • Passenger status
  • Available seats
  • Ride status

⚙️ Installation

1. Clone the repository

git clone https://github.com/your-username/CampusPool.git

2. Navigate to the project

cd CampusPool

3. Install dependencies

Install dependencies for both frontend and backend according to their respective package.json files.

4. Configure environment variables

Create a .env file in the backend and configure the required environment variables.

MONGO_URL=your_mongodb_connection_string
SECRET=your_session_secret

5. Start the backend

nodemon index.js

6. Start the frontend

npm run dev

The frontend will then be available through the Vite development server.

🚀 Future Improvements

CampusPool is currently evolving beyond its initial release.

Planned improvements include:

  • 🔔 Real-time notifications
  • 💬 In-app chat
  • 🗺️ Google Maps integration
  • 📍 Location-based ride discovery
  • ⭐ Ride and user rating system
  • 💳 Payment integration
  • 🔄 Real-time ride updates using Socket.IO
  • 📱 Improved mobile experience

🛡️ Security

The application separates frontend UI protection from backend authorization.

Backend authentication and authorization are enforced through middleware, while the frontend maintains the current authentication state through the AuthContext and /auth/me endpoint.

Sensitive environment variables such as database credentials and session secrets are never committed to the repository.

📈 Version

CampusPool V1.0.0

Initial stable release featuring:

  • Authentication
  • Ride creation
  • Ride discovery
  • Ride joining
  • Ride leaving
  • Ride editing
  • Ride cancellation
  • Ride deletion
  • Passenger management
  • Seat availability tracking
  • Dashboard
  • Session persistence

👨‍💻 Author

Subhranil Mandal

CSE Student

JNU, New Delhi

❤️ About CampusPool

CampusPool is built around a simple idea:

Why travel alone when someone nearby is going the same way?

CampusPool aims to make campus transportation smarter, more affordable, and more connected — one shared ride at a time.