"We are not just building Uber for college. We are building the operating system for campus mobility."

Campus Mobility Hub is an enterprise-grade, comprehensive monolithic application architecture built to unify the fragmented digital experience of university students across the Campuses of Bangalore.

It is a verified, closed network engineered to help you securely commute, rent assets, and exchange essentials. The platform fuses high-density logistics with real-time social networking—featuring anonymous feeds, live proximity radar, and department-specific chat rooms.

Driven by an obsession with performance and modern aesthetics, the platform utilizes a "dark-mode first," frosted-glass UI heavily inspired by industry leaders, creating a digital ecosystem where logistics and social interaction seamlessly collide.

graph TD
    %% Frontend Subsystem
    subgraph Frontend [Client Layer: Next.js App Router]
        UI[UI Components & Layouts]
        State[React Context & State Management]
        Polling[Real-time Polling Interval Engine]
        Route[Client-Side Router]
        
        UI --> State
        UI --> Route
        State --> Polling
    end

    %% Network Boundary
    subgraph Network [API Gateway & Auth]
        Protect[JWT Protect Middleware]
        RateLimiter[Rate Limiting / CORS]
    end

    %% Backend Subsystem
    subgraph Backend [Backend Layer: Node.js / Express]
        AuthCtrl[Auth Controller]
        PulseCtrl[Pulse Social Controller]
        RadarCtrl[Radar Real-time Controller]
        RouteEngine[Carpool Route Matching Engine]
        
        Protect --> AuthCtrl
        Protect --> PulseCtrl
        Protect --> RadarCtrl
        Protect --> RouteEngine
    end

    %% Database Subsystem
    subgraph Database [Data Layer: MongoDB Atlas]
        UserDB[(Users & Profiles)]
        OTPDB[(Ephemeral OTPs)]
        PostDB[(Pulse Posts & Comments)]
        RadarDB[(Active Radar Pings)]
        MarketDB[(Marketplace & Carpool)]
    end

    %% External Services
    subgraph External [External Services]
        SMTP[Gmail SMTP Server]
        Avatars[Dicebear API]
    end

    %% Connections
    Polling -- REST over HTTPS --> RateLimiter
    RateLimiter --> Protect
    
    AuthCtrl --> UserDB
    AuthCtrl --> OTPDB
    AuthCtrl -- Sends Email --> SMTP
    
    PulseCtrl --> PostDB
    PulseCtrl --> UserDB
    PulseCtrl -- Fetches Images --> Avatars
    
    RadarCtrl --> RadarDB
    RouteEngine --> MarketDB

This section breaks down every single capability, button, and underlying logic pipeline present within the ecosystem.

The system implements a rigid security perimeter to ensure only verified college students in Bangalore can access the platform.

• .edu Domain Whitelisting: The registration gateway strictly rejects common domains (gmail, yahoo) and enforces the usage of institutional college emails.
• Automated Data Extraction Regex: When a student enters their university roll number/email (e.g., 1ms24is075@...), the backend regex engine slices the string to mathematically deduce the student's Batch Year (2024 -> 1st Year) and Department Branch (IS -> Information Science). This data is injected into the database, bypassing manual data entry.
• OTP Pipeline: Upon registration or password reset, the Node server generates a highly secure 6-digit OTP, saves it to a transient MongoDB collection with a strict 10-minute TTL (Time To Live) index, and dispatches it via Nodemailer (SMTP).
• JWT State Management: Following a successful OTP verification, the server issues a signed JSON Web Token (JWT), which the client stores locally to authenticate all future requests instantly without secondary database lookups.

Campus Pulse is the central nervous system for social interaction, divided into specialized functional tabs.

• The Global Feed (Real-Time Polling):
  • Silent Auto-Fetching: A background setInterval silently requests new posts every 15 seconds, rendering new content seamlessly without refreshing the browser.
  • Post Types: Users can filter the feed via Segmented Controls: General, Hangout, Question, and Poll.
  • Upvote & Share Logic: Every post features a real-time stateful upvote counter (toggling red upon click) and a native Share API button to copy the post text directly to the clipboard.
• Anonymous Mode & Confessions:
  • Persona Generator: By clicking the "Post Anonymously" mask toggle, the backend completely detaches the user's real identity from the database write. Instead, it assigns a dynamic, fun persona (e.g., "Library Ninja 🥷" or "Coding Wizard 🧙‍♂️") mapped to a distinct Dicebear avatar.
  • Untraceable Badging: Anonymous posts overwrite standard timestamp subtext with an "Untraceable" badge, giving students a safe space for campus discourse.
• Advanced Chat Bubble Comments:
  • iMessage Aesthetic: The comment section uses mathematical conditional rendering (isMyComment ? "flex-row-reverse" : "flex-row") to display responses exactly like a modern texting app (blue bubbles on the right for the user, dark gray on the left for peers).
  • Height Constraints: Lengthy debate threads are wrapped in a max-h-72 viewport with a custom scrollbar (overflow-y-auto). This prevents massive comment threads from expanding the post card infinitely and ruining the main feed layout.

Radar is a hyper-local, real-time presence system allowing students to see who is active on campus and initiate ephemeral chats.

• Interactive Radar UI: Built using Framer Motion, absolute-positioned translucent rings pulse endlessly in the background. The foreground hosts active peer avatars rendered as absolute coordinates over a frosted-glass canvas.
• High-Frequency State Polling: The system runs a rapid 2.5s polling loop. When a user clicks "Start Broadcast", their GPS/Location state is pushed to the server, and the server simultaneously responds with a matrix of other currently broadcasting students.
• Database State Machine Terminations: To eliminate the bug of "ghost chats" remaining open after a user leaves, the RadarPing database schema employs a strict state machine (pending -> accepted -> ended).
• Stop Broadcast Z-Index Fix: The "Stop Broadcast" button features elevated z-index and native onClick propagation to ensure it perfectly pierces through the pulsing radar animations, instantly terminating the session and wiping local state arrays.

Dedicated, high-velocity chat rooms for specific engineering departments.

• Role-Based Access Control (RBAC): Before serving chat history, the backend mathematically compares the requester's branch (fetched from their JWT/User document) against the requested URL parameter (e.g., /rooms/cse). If a Mechanical student attempts to fetch the CSE room, the API intercepts and throws a 403 Forbidden error.
• Alias Resolution Mapping: To account for user input discrepancies ("CS", "CSE", "Computer Science"), the backend maps incoming requests against an exhaustive multidimensional array of aliases, ensuring everyone lands in the correct hub.

A logistical powerhouse designed to eliminate campus transport friction.

• Dynamic Route Matching (AI Engine): A geometric/string-based calculation engine (calculateRouteMatchRadar) intercepts the driver's route nodes (e.g., "Main Gate -> 80ft Road") and cross-references them against the rider's query.
• Glowing UI Badging: The output of the route engine is immediately printed onto the ride card as a highly visible, glowing percentage badge (e.g., ⚡ 96% Match), dictating exactly how much walking distance is saved.
• Capacity State Disablement: Once a ride hits its passenger limit, the backend locks the document. The UI reflects this by graying out the card and disabling the "Join Ride" CTA button.

A unified commerce pipeline for campus goods (textbooks, calculators, lab coats).

• Integrated E-Commerce Schema: All goods share a unified NoSQL schema featuring image arrays, condition tracking ("Like New", "Used"), and pricing.
• Verified Trust Badges: Sellers who have completed institutional verification feature distinct checkmarks on their listings, preventing scams.

The user profile is a massive aggregation engine summarizing the student's platform authority.

• Dynamic Identity Fallbacks: Feed items intelligently parse the profile. If a user hasn't set their branch, the system drops the string gracefully to avoid redundant UI bugs (e.g., preventing Student • Student and gracefully falling back to just Student).
• Historical Aggregation: The backend runs $sum pipeline aggregations to display total completedRides and totalRatings in a sleek horizontal scroll view.

• email: Unique institutional identifier.
• password: Secured via Bcrypt (select: false prevents accidental query exposure).
• branch, year: The extracted department metrics.
• Aggregates: completedRides, rating (0-5 float).

• type: Enum locking behavior (post, confession, poll, hangout).
• owner: ObjectId Ref to User (conditionally wiped if isAnonymous is triggered).
• comments: Sub-document array. Embedded for O(1) read efficiency to populate chat bubbles instantly.
• poll: Complex sub-document tracking string options and an array of ObjectId votes for real-time percentage rendering.

• sender, receiver: User ObjectIds.
• status: Enforced enum (pending, accepted, rejected, ended) handling connection lifecycles.

• POST /api/v1/auth/register-otp - Validates .edu domain and fires SMTP node.
• POST /api/v1/auth/register - Completes validation, parses regex, issues JWT.

• GET /api/v1/pulse - Fetches global timeline (supports ?type= queries).
• POST /api/v1/pulse/:id/comments - Pushes a new embedded comment to a post.
• POST /api/v1/pulse/rooms/:branch/messages - Dispatches message into isolated RBAC branch hub.

• POST /api/v1/radar/ping - Master synchronization endpoint. Pushes location, pulls active peers.
• POST /api/v1/radar/end - Forces status: ended on all active documents linked to user.

The application requires strict environment mapping to function correctly.

PORT=5001
MONGO_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/cmh
JWT_SECRET=a_cryptographically_secure_random_string
JWT_EXPIRES_IN=30d
# Nodemailer SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASS=google_app_specific_password

# Maps client-side fetching to the backend API gateway
NEXT_PUBLIC_API_URL=http://localhost:5001

1. Initialize the Monorepo:

   git clone https://github.com/letsjoyn/campus.git
   cd campus

2. Boot the Data Layer (Backend):

   cd backend
   npm install
   # Ensure .env is created and MongoDB is running locally or via Atlas
   npm run dev

   The server will boot on localhost:5001 and connect to Mongoose.

3. Boot the Client Layer (Frontend):

   # Open a new terminal instance
   cd frontend
   npm install
   # Ensure .env.local points to the backend
   npm run dev

   The Next.js router will compile and serve the application on localhost:3000.

4. Typescript Strictness: Always verify UI modifications against the Next.js compiler before pushing:

   npx tsc --noEmit

Engineered for massive concurrency and peer-to-peer execution across Bangalore.

CMHub is fully open-source and maintained by students, for students. We welcome contributions from the community to help expand features, improve algorithms, and launch the platform at new universities.

Please read our Contributing Guidelines to get started with setting up your local environment, issuing pull requests, and following our UI/UX design language.

If you find this project helpful or want to support campus mobility, please consider giving it a ⭐ on GitHub!