BusMate — Smart Bus Booking

Problem & Requirements

BusMate addresses the operational pain points of campus transportation while meeting strict functional requirements.

Core Problems

Manual bookings cause long queues and seat conflicts.
Unclear availability leads to last-minute uncertainty.
Fragmented admin tools slow down route planning.
Limited visibility into boarding points and timings.

Requirements

Secure sign-up, login, and role-based access for students and admins.

Visual seat maps with instant updates to prevent double bookings.

Find buses quickly by boarding point, route, and time.

Tools for boarding points, bus models, and schedules.

Tech Stack & Why

Each tool was selected to balance performance, reliability, and developer velocity.

React 19 + Next.js 15

Server Components reduce client load for faster seat layouts.

App Router enables clear routing and API colocation.

Tailwind CSS v4

Utility-first styling speeds up UI iteration.

Consistent design tokens across pages.

NextAuth v5

Credential-based auth with secure sessions.

Works seamlessly with App Router APIs.

API Routes

Simple REST endpoints for booking and admin tools.

Co-located server logic improves maintainability.

Drizzle ORM

Type-safe queries from schema to frontend.

Minimal overhead for high-concurrency booking.

PostgreSQL

Reliable relational model for seats and routes.

JSONB for fast seat map reads.

TypeScript + ESLint

Catches errors early and enforces consistency.

Cleaner PRs and easier onboarding.

pnpm + Docker

Fast installs and reproducible environments.

Simplifies local and production setup.

Highlighted Solution & Data Flow

How BusMate turns complex booking into a predictable, real-time workflow.

Key Solution Highlights

Seat map engine renders live availability per bus model.
Boarding point filters reduce time to find a route.
Admin hub centralizes schedules and models.
Session-safe booking prevents seat collisions.

Data Flow Stages

NextAuth validates credentials and establishes a secure session.

Client queries boarding point routes and available buses.

Bus model layout + JSON seat statuses render the map.

/api/bookSeat writes to DB and confirms instantly.

Powerful Features

Everything you need to manage campus transportation efficiently and securely.

User Management

Secure registration with email validation, OTP verification, and role-based access control for students and administrators.

Route Filtering

Browse available buses by boarding point, filter by departure times, and select your preferred journey with ease.

Seat Selection

Interactive visual bus layout with real-time seat availability, gender-based seat allocation, and instant booking confirmation.

Secure Booking

NextAuth integration for secure authentication, encrypted sessions, and protected API endpoints for all transactions.

Real-time Updates

Live seat map updates, instant booking confirmation, and real-time availability status across all buses.

Admin Dashboard

Comprehensive admin panel to manage boarding points, bus models, routes, and view detailed user booking analytics.

API Documentation

RESTful API endpoints for authentication, booking, and administration.

POST /api/register

{
  "rollNo": "cs001",
  "name": "John Doe",
  "email": "john@example.com",
  "boardingPoint": "Main Gate",
  "gender": "male",
  "phone": "1234567890",
  "password": "secure_password"
}

POST /api/auth/[...nextauth]

NextAuth authentication handler (Credentials provider).

GET /api/dashboard

Get current user dashboard with bookings (Auth required).

POST /api/bookSeat

Book a seat on a bus (Auth required).

{
  "seatId": "L2-03",
  "busId": "550e8400-e29b-41d4-a716-446655440000"
}

GET /api/bus/[busId]

Get bus details including model and current seat status.

GET /api/boarding-points

List all available boarding points.

GET /api/bus/byBoardingPoint/[boardingPointId]

Get buses available for a specific boarding point.

POST /api/admin/addBoardingPoints

Create a new boarding point.

POST /api/admin/addBus

Create a new bus with route configuration.

POST /api/admin/addModel

Create a new bus seat model (layout data).

Setup & Deployment

Get BusMate running locally or deploy it to production.

1. Clone Repository & Install

git clone https://github.com/Mohamed-Abu-Bakkar/BusMate.git
cd BusMate
pnpm install

2. Configure Environment

Create a .env.local file:

DATABASE_URL=postgres://root:root@localhost:5432/BusMate
AUTH_SECRET=your-secret-key-here
NEXT_PUBLIC_BASE_URL=http://localhost:3000

3. Start Database & Push Schema

# Start PostgreSQL (Docker)
docker run -d --name busmate-db -e POSTGRES_USER=root -e POSTGRES_PASSWORD=root -e POSTGRES_DB=BusMate -p 5432:5432 postgres:latest

# Apply schema
pnpm db:push

4. Start Development Server

pnpm dev

Open http://localhost:3000 in your browser.

Docker Compose Setup

BusMate includes a compose.yaml file for easy containerized deployment. This will start both the Next.js app and PostgreSQL database.

# Start services in the background
docker compose up -d --build

# View logs
docker compose logs -f

# Stop services
docker compose down

Environment File (.env)

Ensure your .env file references the Docker network correctly:

DATABASE_URL=postgres://root:root@postgres-container:5432/BusMate
AUTH_SECRET=your-secret-key-here
NEXT_PUBLIC_BASE_URL=http://localhost:3000
NODE_ENV=development

Vercel

Recommended for Next.js. Connect GitHub repo, set environment variables, and deploy with one click.

Railway

Full-stack deployment with managed PostgreSQL support. Simple configuration.

Production Checklist

✓ Set strong AUTH_SECRET
✓ Set NODE_ENV=production
✓ Configure PostgreSQL with SSL/TLS
✓ Replace demo OTP with real email/SMS service