 |
From "who's driving to office today?" to a booked seat, a live map, and a settled wallet — in one platform.
A production-grade, full-stack Enterprise Carpooling Platform built for organizations that want to replace ad-hoc WhatsApp ride-shares with a single, structured, role-driven system — live tracking, dynamic RBAC, payments, and sustainability analytics included.
Built with ❤️ by a team of four. Every byte of this platform, from database schema to live-tracking UI, was designed, coded, and shipped by:
|
🧑💻 Ridham Patel Full-Stack · Cloud · Architecture · DevOps |
🧑💻 Hemant Pande Full-Stack · Schema · Integrations |
👩💻 Hetvi Hinsu Full-Stack · QA · Documentation |
👩💻 Honey Modha Full-Stack · UI/UX · Frontend |
- Meet the Team
- Problem Statement
- What RideBuddy Does
- Architecture
- Libraries & Tech Stack
- Data Model
- User Roles & Permissions
- Complete User Workflow
- Screens & Features
- Project Structure
- Quick Start
- Environment Variables
- Database Seeding
- End-to-End Demo Script
- Cross-Cutting Features
- API Guide
- Documentation
- Build Status
Daily commuting inside a single organization still runs on:
- 💬 Ad-hoc WhatsApp groups — "anyone going toward Gandhinagar?" with no structure, no history, no accountability.
- 🚗 Empty seats, wasted fuel — every employee drives alone; nobody coordinates who's already heading the same way.
- 📍 Zero visibility — no way to know where a shared ride actually is, or when it'll arrive.
- 💸 Manual, informal money — cash handed over post-ride, no record, no wallet, no receipts.
- 🌱 No sustainability tracking — organizations have no idea how much CO₂ or fuel is actually being saved (or wasted).
RideBuddy digitizes the entire intra-org carpooling lifecycle — from vehicle registration and ride matching to live GPS tracking, in-app chat, wallet-based payments, and CO₂/fuel sustainability reporting — scoped per organization with a fully dynamic, runtime-editable permission system.
One platform. Two backend services. Zero manual coordination.
| # | Module | What It Does |
|---|---|---|
| 🏢 | Multi-Tenant Organizations | Each company (org) gets isolated departments, office locations, policies, and users |
| 🔐 | Dynamic RBAC | 55 runtime-editable permissions across roles — change access live, no redeploy |
| 🚘 | Vehicle Registry | Employees register vehicles; admin approves owner-submitted edits before they go live |
| 🧭 | Ride Matching Engine | Explainable route/time-based matching between drivers offering rides and passengers searching for one |
| 📅 | Book → Start → Complete | Full trip lifecycle from booking through live trip to completion, with sustainability metrics computed per trip |
| 📡 | Live Location & ETA | Real-time driver→passenger GPS tracking over a dedicated Socket.IO microservice |
| 💬 | In-Trip Chat & Alerts | Persisted trip chat plus real-time notifications, bridged from the core API via Redis pub/sub |
| 💰 | Wallet & Payments | Razorpay-backed wallet recharge and ride payments, with full transaction history |
| 🌱 | Sustainability Analytics | Per-trip CO₂ saved, fuel saved, and cost/km — rolled up into org-wide reports |
| 🆘 | Safety (SOS) | In-trip SOS event capture for driver/passenger safety |
┌──────────────────────────────────────────────────────────────────┐
│ 🖥️ Client — Next.js 15 (App Router) │
│ Permission-Driven UI · shadcn/ui · Zustand · TanStack Query │
└─────────────┬──────────────────────────────┬───────────────────┘
│ REST (fetch) │ WebSocket
▼ ▼
┌──────────────────────────┐ ┌───────────────────────────────┐
│ ⚙️ apps/api (Express) │ │ 📡 apps/realtime (Socket.IO) │
│ JWT + refresh rotation │◄────►│ Live location · trip chat │
│ Dynamic RBAC middleware │ Redis│ Notification fan-out │
│ Prisma ORM · BullMQ jobs │ pub/ │ @socket.io/redis-adapter │
│ Razorpay · Cloudinary │ sub │ │
│ SMTP · report PDFs │ └───────────────────────────────┘
└─────────────┬─────────────┘
│
┌─────┴─────┐
▼ ▼
┌──────────────┐ ┌──────────┐
│ 💾 PostgreSQL │ │ 🧠 Redis │
│ + PostGIS │ │ cache/ │
│ (Prisma) │ │ queues │
└──────────────┘ └──────────┘
The API stays HTTP-only and pushes events to the realtime service over a Redis pub/sub bridge (
src/realtime/emit.ts) — socket load never touches the core backend, and either service can scale independently.
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Admin │ │ Driver │ │Passenger │ │ Realtime │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │ │
│ Onboard org, │ │ │
│ approve │ │ │
│ vehicles │ │ │
│ │ 1. Register │ │
│ │ vehicle │ │
│ │ │ │
│ │ 2. Offer a │ │
│ │ ride ────►│ │
│ │ │ 3. Find & │
│ │ │ book ─────┤
│ │◄─────────────│ │
│ │ │ │
│ │ 4. Start trip│ │
│ │ │ ├──► live GPS + ETA
│ │ │ │ push to passenger
│ │ │ │
│ │◄─────────────┼──────────────┤ in-trip chat
│ │ │ │
│ │ 5. Complete │ │
│ │ trip │ │
│ │ (CO₂/fuel │ │
│ │ computed) │ │
│ │ │ │
│ │ 6. Wallet │ │
│ │ payment ─►│ │
│ │ │ │
| Entity | States |
|---|---|
| Ride | DRAFT → PUBLISHED → MATCHED → CLOSED (or CANCELLED) |
| Booking | PENDING → CONFIRMED → COMPLETED / REJECTED / CANCELLED |
| Trip | SCHEDULED → ONGOING → COMPLETED (or CANCELLED) |
| Payment | CREATED → AUTHORIZED → CAPTURED (or FAILED / REFUNDED) |
| Vehicle | PENDING → ACTIVE (owner edits require re-approval: PENDING_CHANGES → ACTIVE) |
| User | PENDING → ACTIVE (or SUSPENDED) |
Every runtime dependency below is pulled straight from the workspace package.json files — no aspirational listings.
| Technology | Purpose |
|---|---|
| Next.js 15 | Full-stack React framework (App Router) |
| React 19 | UI library |
| TypeScript | Type safety across the entire codebase |
| Tailwind CSS 4 | Utility-first styling |
| shadcn/ui + Radix primitives | Accessible component library |
| Tabler icons + Hugeicons | Icon sets used across the UI |
| Zustand | Client-side state management (stores/) |
| TanStack Query | Server-state fetching & caching |
Leaflet / react-leaflet + @vis.gl/react-google-maps |
Live trip tracking map, route rendering |
| socket.io-client | Realtime connection to apps/realtime |
| react-hot-toast | Toast notifications |
| Recharts | Sustainability & admin analytics charts |
| Zod | Shared schema validation (via @ridebuddy/types) |
| Technology | Purpose |
|---|---|
| Node.js + Express 4 (TypeScript, ESM) | REST API |
| Prisma 6 | ORM, schema management, migrations |
| PostgreSQL + PostGIS | Primary relational database, geospatial ride matching |
| Redis (ioredis) + BullMQ | Caching, RBAC version invalidation, background jobs |
| argon2 | Password hashing |
| jsonwebtoken | Access + refresh token auth |
Socket.IO + @socket.io/redis-adapter |
Bridges events to the realtime service |
| Razorpay | Order creation, payment verification, webhooks |
| Cloudinary | Media/file storage (vehicle docs, avatars) |
| Nodemailer | Transactional email (SMTP) |
| pdfkit | Server-generated report PDFs |
| pino / pino-http | Structured logging |
| helmet, express-rate-limit + rate-limit-redis | Security headers & rate limiting |
| Zod | Request validation |
| Technology | Purpose |
|---|---|
| Express + Socket.IO | Standalone WebSocket microservice |
@socket.io/redis-adapter |
Multi-instance socket fan-out |
| jsonwebtoken | Socket handshake authentication |
| Prisma client | Read access for trip/chat persistence |
| pino | Structured logging |
| Technology | Purpose |
|---|---|
@ridebuddy/types (packages/types) |
Zod-based schemas shared across api, realtime, and web |
| Turborepo | Monorepo task orchestration (dev, build, lint, typecheck) |
| pnpm workspaces | Package management (pnpm@10.33.0) |
RideBuddy uses a fully relational PostgreSQL schema (with PostGIS geography columns for ride matching) managed by Prisma — see docs/03-data-model.md for the complete spec.
organization ──┬── departments
├── officeLocations
├── roles ── rolePermissions ── permissions
└── users ──┬── userRoles
├── userPermissions (per-user overrides)
├── sessions
├── vehicles
├── rides ── bookings ── trips ──┬── tripLocations
│ ├── tripMetrics
│ └── sosEvents
├── wallet ── walletTransactions
├── payments
├── conversations ── messages
├── notifications
├── reviews
└── savedPlaces
| Model | Description |
|---|---|
Organization |
Multi-tenant root — policies, working hours, holidays, ride/fuel/travel-allowance rules stored as JSON |
Department / OfficeLocation |
Org sub-structures used for scoping and ride-matching context |
User |
Employee/driver/passenger profile with eco points and rating, scoped to one organization |
Session |
Refresh-token sessions for JWT rotation |
Role / Permission / RolePermission / UserRole / UserPermission |
Fully dynamic RBAC graph — per-user allow/deny overrides on top of role-based grants |
AuditLog |
Immutable audit record for permission and admin changes |
Vehicle |
Owner-registered vehicle with pendingChanges awaiting admin approval |
Ride |
Driver-offered ride with PostGIS geography columns for origin/destination/route matching |
Booking |
Passenger's seat request against a Ride |
Trip |
Live trip instance derived from a confirmed booking |
TripLocation |
Live GPS ping stream for an ongoing trip |
TripMetric |
Per-trip fuel/CO₂ saved, cost/km, sustainability data |
Wallet / WalletTransaction |
Per-user balance and ledger |
Payment |
Razorpay order/payment record (order → verify → webhook) |
Conversation / Message |
Persisted in-trip chat |
Notification |
Per-user inbox entries, fanned out in real time |
Review |
Post-trip driver/passenger ratings |
SavedPlace |
User-saved frequent locations (home, office, etc.) |
SosEvent |
In-trip safety alert capture |
RBAC in RideBuddy is dynamic and runtime-editable — 55 permissions across roles, enforced by requirePermission middleware on every route, resolved per-request, and Redis-cached with org-scoped version invalidation (Organization.permVersion). Changing a role's permissions takes effect immediately, no redeploy.
SUPER_ADMIN > COMPANY_ADMIN > EMPLOYEE (DRIVER / PASSENGER)
| Permission | Super Admin | Company Admin | Employee |
|---|---|---|---|
| Manage organizations | ✅ | ❌ | ❌ |
| Manage roles & permission matrix | ✅ | ✅ (own org) | ❌ |
| Manage departments & office locations | ✅ | ✅ | ❌ |
| Approve/reject vehicle registrations | ✅ | ✅ | ❌ |
| Register own vehicle | ❌ | ❌ | ✅ |
| Offer a ride | ❌ | ❌ | ✅ |
| Search & book a ride | ❌ | ❌ | ✅ |
| Start / complete own trip | ❌ | ❌ | ✅ |
| View live trip tracking | ❌ | ❌ | ✅ (participants) |
| Access wallet & make payments | ❌ | ❌ | ✅ |
| View org-wide reports & sustainability data | ✅ | ✅ | ❌ |
| Full audit log access | ✅ | ✅ (own org) | ❌ |
Roles shown are the default seed roles — since RBAC is dynamic, any organization's Company Admin can create additional custom roles and reassign permissions per employee.
Purpose: Platform-level oversight across all tenant organizations.
- Log in with a Super Admin account (seeded, see Database Seeding).
- Manage organizations — create/edit tenant orgs, review org-wide policies.
- Manage the RBAC matrix — edit any organization's roles and permissions live (
/admin/rbac). - View cross-org reports at
/reportsand/admin/reports.
Purpose: Owns one organization — manages employees, departments, vehicles, and access.
- Open
/admin/company— configure working hours, holidays, ride policies, fuel-cost rules, travel allowance. - Open
/admin/employees— invite/manage employees, assign roles. - Open
/admin/vehicles— approve or reject owner-submitted vehicle registrations and edits (pendingChanges). - Open
/admin/rbac— edit the organization's role/permission matrix; changes apply immediately org-wide. - Open
/admin/reports— spend, ride volume, and sustainability (CO₂/fuel saved) analytics for the org.
Purpose: Register a vehicle, offer rides, and run trips.
- Open
/vehicles→ register a vehicle (make, model, plate, fuel type). Status startsPENDINGuntil admin approval. - Open
/offer→ create a ride: route, departure time, available seats, price. Explainable matching surfaces this ride to nearby passengers. - Open
/my-rides→ review incoming bookings, confirm or reject passengers. - Start the trip from
/trips/[tripId]once a booking is confirmed — live location begins streaming to passengers over Socket.IO. - Chat with the passenger in-trip; complete the trip on arrival —
TripMetric(CO₂/fuel saved, cost/km) is computed automatically. - Wallet — view earnings/payments received at
/wallet.
Purpose: Find a ride, book, track it live, and pay.
- Open
/find→ search rides by route/time; results ranked by an explainable match score. - Book a seat — creates a
PENDINGbooking; driver confirms or rejects. - Track live at
/track/[tripId]— Leaflet map with driver's real-time location and ETA once the trip starts. - Chat with the driver in-trip for pickup coordination.
- Pay via wallet (Razorpay-backed recharge) once the trip completes.
- Review the driver and view ride history at
/history.
What an employee cannot do: Approve vehicles, edit the org's RBAC matrix, view another user's trips/wallet, or access org-wide reports (unless separately granted via the dynamic permission system).
| Route | Role Access | Purpose |
|---|---|---|
/login, /signup |
Public | Authentication (JWT + refresh rotation, OTP) |
/dashboard |
All | Role-aware KPI cards and recent activity |
/find |
Employee | Search rides with explainable match scores |
/offer |
Employee (Driver) | Create a new ride offer |
/my-rides |
Employee (Driver) | Manage offered rides and incoming bookings |
/rides |
Employee | Browse/filter available rides |
/trips/[tripId] |
Participants | Trip detail, start/complete actions |
/track/[tripId] |
Participants | Live Leaflet map — driver location + ETA |
/vehicles |
Employee | Register and manage own vehicles |
/wallet |
Employee | Balance, recharge (Razorpay), transaction history |
/history |
Employee | Past trips and payments |
/reports |
Company/Super Admin | Sustainability and ride analytics |
/profile, /settings |
All | Personal profile & preferences |
/admin/company |
Company Admin | Org policy configuration |
/admin/employees |
Company Admin | Employee management |
/admin/organizations |
Super Admin | Tenant org management |
/admin/rbac |
Company/Super Admin | Live role/permission matrix editor |
/admin/reports |
Company/Super Admin | Org-wide analytics |
/admin/vehicles |
Company Admin | Vehicle approval queue |
RideBuddy/
├── apps/
│ ├── api/ # Express REST API
│ │ ├── prisma/
│ │ │ ├── schema.prisma # Full data model (PostGIS-enabled)
│ │ │ └── seed.ts # Demo org, roles, permissions, users
│ │ └── src/
│ │ ├── index.ts # Entry point
│ │ ├── app.ts # Express app setup
│ │ ├── routes.ts # Route aggregator
│ │ ├── config/ # env, feature flags, sustainability formulas
│ │ ├── lib/ # cloudinary, jwt, logger, mailer, maps, prisma, razorpay, redis
│ │ ├── middleware/ # authenticate, requirePermission (RBAC), rateLimit, validate, error
│ │ ├── modules/ # feature modules (routes + service per domain)
│ │ │ ├── auth/
│ │ │ ├── organizations/
│ │ │ ├── companies/
│ │ │ ├── users/
│ │ │ ├── rbac/ # + permissions.catalog.ts
│ │ │ ├── vehicles/
│ │ │ ├── rides/
│ │ │ ├── trips/
│ │ │ ├── payments/
│ │ │ ├── wallet/
│ │ │ ├── reports/ # + report-pdf.service.ts
│ │ │ ├── maps/
│ │ │ └── admin/
│ │ ├── realtime/
│ │ │ └── emit.ts # Bridges API events → realtime service via Redis
│ │ └── types/
│ │ └── express.d.ts # Express type augmentation
│ │
│ ├── realtime/ # Standalone Socket.IO microservice
│ │ └── src/ # live tracking, chat, notification fan-out
│ │
│ └── web/ # Next.js 15 App Router frontend
│ ├── app/
│ │ ├── (auth)/ # login, signup
│ │ ├── (app)/ # authenticated shell
│ │ │ ├── dashboard/
│ │ │ ├── find/ offer/ my-rides/ rides/
│ │ │ ├── trips/[tripId]/ track/[tripId]/
│ │ │ ├── vehicles/ wallet/ history/ reports/
│ │ │ ├── profile/ settings/
│ │ │ └── admin/ # company · employees · organizations · rbac · reports · vehicles
│ │ └── fonts/ # Matter custom font
│ ├── components/ # shadcn/ui + feature components
│ ├── lib/
│ └── stores/ # Zustand state
│
├── packages/
│ └── types/ # @ridebuddy/types — shared Zod schemas
│
├── docs/
│ ├── 00-product-overview.md
│ ├── 01-architecture.md
│ ├── 02-design-system.md
│ ├── 03-data-model.md
│ ├── 04-rbac.md
│ ├── 05-api-spec.md
│ ├── 06-roadmap-phases.md
│ └── 07-ai-and-bonus.md
│
├── docker-compose.yml # postgres (PostGIS) + redis
├── turbo.json
├── tsconfig.base.json
├── pnpm-workspace.yaml
└── .env.example
Get the full platform running locally in under 5 minutes.
- Node.js ≥ 20
- pnpm (
npm install -g pnpm, or usepnpm@10.33.0via corepack) - Docker (for Postgres + PostGIS and Redis)
git clone https://github.com/ridh21/RideBuddy.git
cd RideBuddy
pnpm installdocker compose up -d # postgres (PostGIS) on :5435 · redis on :6379cp .env.example .env # fill in Maps / Razorpay / Cloudinary / SMTP keys as neededPostgres runs on host port 5435 (5432 was taken locally). The API and realtime service load the root
.env; Prisma readsapps/api/.envforDATABASE_URL; the web app readsapps/web/.env.localforNEXT_PUBLIC_*values.
pnpm --filter @ridebuddy/api exec prisma migrate dev
pnpm --filter @ridebuddy/api db:seed # roles, permissions, demo org + userspnpm dev
# → web http://localhost:3000
# → api http://localhost:4000
# → realtime http://localhost:4001Razorpay test payments: pay with UPI ID
success@razorpay.
| Variable | Required | Description |
|---|---|---|
NODE_ENV |
✅ | development / production |
API_PORT |
✅ | Express API port (default 4000) |
REALTIME_PORT |
✅ | Socket.IO service port (default 4001) |
CORS_ORIGIN |
✅ | Allowed frontend origin |
DATABASE_URL |
✅ | PostgreSQL (PostGIS) connection string |
REDIS_URL |
✅ | Redis connection string (cache, BullMQ, socket adapter) |
JWT_ACCESS_SECRET / JWT_REFRESH_SECRET |
✅ | Token signing secrets — generate with openssl rand -base64 48 |
ACCESS_TOKEN_TTL / REFRESH_TOKEN_TTL |
✅ | Token lifetimes (default 15m / 30d) |
GOOGLE_MAPS_API_KEY |
Routing; offline estimate fallback if unset | |
RAZORPAY_KEY_ID / RAZORPAY_KEY_SECRET / RAZORPAY_WEBHOOK_SECRET |
Wallet & ride payments (test mode by default) | |
CLOUDINARY_CLOUD_NAME / CLOUDINARY_API_KEY / CLOUDINARY_API_SECRET |
Vehicle docs / avatar storage | |
SMTP_HOST / SMTP_PORT / SMTP_SECURE / SMTP_USER / SMTP_PASS / SMTP_FROM |
Transactional email | |
NEXT_PUBLIC_API_URL |
✅ | Frontend → API base URL |
NEXT_PUBLIC_SOCKET_URL |
✅ | Frontend → realtime service URL |
NEXT_PUBLIC_GOOGLE_MAPS_KEY |
Client-side map rendering |
Running pnpm --filter @ridebuddy/api db:seed creates a ready-to-use demo workspace for organization odoo (Odoo India, Gandhinagar), password Password123! for all accounts:
| Role | |
|---|---|
| Company Admin | ankit@odoo.com |
| Super Admin | priya@odoo.com |
| Employee | jaanvi@odoo.com |
| Employee | raj@odoo.com |
| Employee | meera@odoo.com |
| Employee | sahil@odoo.com |
The seed also creates the org's roles, the full 55-permission catalog, departments, office locations, and baseline demo data so every screen has data immediately.
1. Login → Company Admin (ankit@odoo.com) → /admin/vehicles (queue empty initially)
2. Employee → /vehicles → register a vehicle → status PENDING
3. Company Admin → /admin/vehicles → approve → vehicle ACTIVE
4. Driver → /offer → create a ride (route, time, seats, price)
5. Passenger → /find → search → see explainable match score → book seat
6. Driver → /my-rides → confirm booking
7. Driver → /trips/[tripId] → Start trip → live GPS begins streaming
8. Passenger → /track/[tripId] → watch live location + ETA on the map
9. Both → in-trip chat panel → coordinate pickup
10. Driver → Complete trip → TripMetric (CO₂/fuel saved) computed
11. Passenger → /wallet → recharge via Razorpay (UPI success@razorpay) → pay for trip
12. Company Admin → /admin/reports → see updated sustainability + ride analytics
13. Company Admin → /admin/rbac → toggle a permission live → employee sees 200 → 403 → 200, no redeploy
requirePermissionmiddleware (apps/api/src/middleware/) resolves a user's effective permissions per-request: role grants +UserPermissionallow/deny overrides.- Resolved permission sets are Redis-cached, keyed by
Organization.permVersion— bumping the org's version instantly invalidates the cache org-wide, so a permission change made in/admin/rbacapplies to the next request with no redeploy. - Every RBAC change writes an
AuditLogrow.
The core API is HTTP-only — it never holds open socket connections. Instead, apps/api/src/realtime/emit.ts publishes events to Redis, and apps/realtime (a separate Socket.IO service, using @socket.io/redis-adapter) subscribes and fans them out to connected clients. This keeps socket load fully decoupled from the REST API and lets either service scale independently.
Rides and searches use PostGIS geography columns (Ride.origin, Ride.destination, route geometry) so matching is computed with real spatial queries rather than naive distance math, and match scores are explainable (surfaced to the user, not a black box).
TripMetric is computed on trip completion using formulas in apps/api/src/config/sustainability.ts — fuel saved, CO₂ saved, and cost/km per trip, rolled up into org-wide reports (/admin/reports) and exportable as PDF via pdfkit.
Razorpay order → checkout → verify + webhook flow covers both wallet recharge and direct ride payment (UPI/Card), with all transactions recorded in WalletTransaction / Payment.
RideBuddy exposes a REST API (apps/api) plus a Socket.IO event contract (apps/realtime). Full endpoint-by-endpoint documentation (~130–150 routes) lives in docs/05-api-spec.md; the summary below covers the module layout and auth model.
Each module follows a consistent *.routes.ts + *.service.ts pattern, validated with Zod and gated by requirePermission.
| Module | Responsibility |
|---|---|
auth |
Signup, login, OTP, JWT access/refresh rotation, logout |
organizations |
Super Admin — tenant org CRUD |
companies |
Company Admin — org policy config (working hours, holidays, ride/fuel/travel rules) |
users |
Employee/user management |
rbac |
Roles, permissions, permissions.catalog.ts, live matrix edits |
vehicles |
Registration, owner edits (pendingChanges), admin approval |
rides |
Ride offer creation, search/matching |
trips |
Trip lifecycle: start, live updates, complete, metrics |
payments |
Razorpay order creation, verification, webhook handling |
wallet |
Balance, recharge, transaction history |
reports |
Analytics aggregation + report-pdf.service.ts PDF export |
maps |
Route/ETA lookups (Google Maps, with offline fallback) |
admin |
Cross-cutting admin utilities |
misc |
Health checks and small shared endpoints |
Auth model: every protected route runs through middleware/authenticate.ts (verifies the JWT access token) then middleware/requirePermission.ts (resolves and checks the caller's effective permission set, Redis-cached and version-invalidated per organization).
The Socket.IO service authenticates each connection via JWT on handshake, then relays:
| Event | Direction | Purpose |
|---|---|---|
trip:location |
Driver → server → passenger | Live GPS ping during an ongoing trip |
trip:eta |
Server → passenger | Recomputed ETA as location updates |
chat:message |
Bidirectional | Persisted in-trip chat |
notification:new |
Server → user | Fan-out of API-originated events (booking confirmed, vehicle approved, etc.) bridged from apps/api/src/realtime/emit.ts via Redis pub/sub |
@ridebuddy/types centralizes Zod schemas consumed by the API (request validation), the realtime service (payload shapes), and the web app (form validation + z.infer types) — a single source of truth across all three services.
Deeper, authoritative specs live in docs/:
| Doc | What's inside |
|---|---|
docs/00-product-overview.md |
Vision, roles, problem-statement workflow, mandatory↔bonus↔differentiator traceability |
docs/01-architecture.md |
Stack, monorepo layout, request pipeline, realtime, jobs, env, local dev |
docs/02-design-system.md |
Evergreen color tokens, Season Mix typography, Tabler icon setup, shadcn inventory |
docs/03-data-model.md |
Full Prisma schema — all entities, enums, tenancy, seed |
docs/04-rbac.md |
Dynamic RBAC — permission catalog, resolver, Redis cache/versioning, admin UI |
docs/05-api-spec.md |
~130–150 REST endpoints grouped, plus the Socket.IO event contract |
docs/06-roadmap-phases.md |
Phase-by-phase execution plan with acceptance criteria & demo checkpoints |
docs/07-ai-and-bonus.md |
Intelligent matching, route optimization, AI layer, sustainability formulas, gamification, SOS |
The foundation and core spine are implemented and verified end-to-end against a live Postgres instance:
- Monorepo — pnpm workspace (
apps/api,apps/web,apps/realtime,packages/types); all apps type-check clean, web production-builds. - Backend — Express + TS, layered modules, full Prisma schema + migration + seed. Auth (JWT + refresh rotation + OTP), dynamic RBAC (55 permissions, live-editable, Redis-cached with version invalidation), companies/admin, vehicles, ride matching engine, bookings, trip lifecycle, wallet, payments, reports, sustainability, Socket.IO bridge (tracking/chat/notifications).
- Frontend — Next.js App Router, Evergreen light theme, shadcn primitives, Tabler icons. Auth screens, permission-driven app shell, dashboard, find/offer/trips/vehicles/wallet/history/reports, admin employees/company/RBAC matrix.
- Realtime microservice —
apps/realtimeverified end-to-end: driver→passenger live location + ETA, persisted trip chat, Redis bridge delivering core-API notifications to sockets. Frontend: Leaflet tracking page (/track/[tripId]), chat panel, notification bell. - Payments — Razorpay order → checkout → verify + webhook (wallet recharge + ride UPI/Card), proven against the live test gateway.
- Proven flow — login → search (explainable match scores) → book → start → complete (CO₂/fuel metrics) → wallet pay →
PAYMENT_COMPLETED; plus a live RBAC permission toggle (200 → 403 → 200, no redeploy, audited).
What's next (see docs/06-roadmap-phases.md): Super Admin org CRUD, dashboard charts, and Phase 8 differentiators — AI matching v2, gamification UI, SOS, PWA.
Source problem statement:
Carpooling Platform (1).pdf. No automated test suite or CI/CD pipeline is configured yet.
# Fork the repo, then:
git checkout -b feature/your-feature-name
git commit -m "feat: describe your change"
git push origin feature/your-feature-name
# Open a Pull RequestPlease follow Conventional Commits for commit messages.
No license file is currently published for this repository. All rights reserved unless a LICENSE is added.
Built with 🔥 by Ridham Patel, Hemant Pande, Hetvi Hinsu & Honey Modha
for the Odoo/KSV Hackathon