BunkBuddies

Web application for finding roomates during VIT hostel counselling


Visit · Report Bug · Request Feature

About The Project

BunkBuddies is a web application developed by VinnovateIT that helps in selecting roommate for VIT hostel counseling. It leverages Natural Language Processing to generate compatibility scores and rank potential roommates. It features private and public chats to facilitate seamless communication between VIT students.

Screenshots

Dashboard	Create Room
Explore Rooms	Chat

Core Features

• Google sign-in flow through /api/login and /api/auth/callback/google
• Session-aware routing with onboarding redirects
• Personality quiz for hostel type, hostel group, rank, sleep schedule, cleanliness, social habits, languages, and personal description
• Profile creation and editing with VIT student details
• Room group creation, editing, deletion, joining by room code, and leaving
• Room exploration with search, filters, sorting, pagination, vacancy details, and join requests
• Group dashboard with squad details, compatibility badges, request approval/rejection, invite code generation, and member removal
• Real-time hostel chat and direct messages through WebSockets
• Custom 404 page, toast notifications, contributor showcase, and responsive VinnovateIT-themed UI

Built With

Project Structure

BunkBuddies-Frontend/
|-- public/                         # Logos, icons, contributor images, decorative assets
|-- src/
|   |-- app/
|   |   |-- api/                    # Frontend auth/session/backend proxy routes
|   |   |-- chat/                   # Hostel chat and direct messaging
|   |   |-- create-room/            # Room create/edit flow
|   |   |-- explore-rooms/          # Room discovery, search, filters, requests
|   |   |-- find-buddies/           # Main post-login action dashboard
|   |   |-- my-groups/              # Current group, join requests, invite codes
|   |   |-- personality-quiz/       # Onboarding quiz
|   |   |-- profile/                # Student profile form
|   |   |-- signin/                 # Google sign-in screen
|   |   |-- thankyou/               # Thank-you/sign-off page
|   |   |-- components/             # Shared UI components
|   |   |-- utils/                  # Backend client and data helpers
|   |   |-- globals.css
|   |   |-- layout.js
|   |   `-- page.js
|-- open-next.config.ts             # OpenNext Cloudflare config
|-- wrangler.jsonc                  # Cloudflare Workers deployment config
|-- next.config.mjs
|-- package.json
`-- .env.example

Routes

Route	Purpose
/	Landing page with product pitch, how-it-works section, contributors, and footer
/signin	Google sign-in entry page
/thankyou	Thank-you/sign-off page shown from the landing CTA
/personality-quiz	Student onboarding quiz
/profile	Student profile creation/editing
/find-buddies	Main dashboard for creating, exploring, joining rooms, and opening chat
/create-room	Create or edit a room group
/explore-rooms	Browse available room groups and send join requests
/my-groups	Manage the user's current group, invite code, members, and join requests
/chat	Hostel-wide chat and direct messages

Frontend API Routes

Route	Method	Description
/api/login	GET	Starts backend Google OAuth and redirects to Google
/api/auth/callback/google	GET	Completes OAuth, stores bb_access_token, and redirects based on user state
/api/auth/session	GET	Checks current auth/profile/quiz/group state
/api/logout	POST	Clears the auth cookie
/api/backend/[...path]	GET, POST, PUT, PATCH, DELETE	Authenticated proxy to backend endpoints

Getting Started

Follow these steps to run the frontend locally.

Prerequisites

• Node.js 18.18 or newer recommended for Next.js 15
• npm
• A running BunkBuddies backend service
• Backend Google OAuth configured with this frontend callback URL:

http://localhost:3000/api/auth/callback/google

Installation

1. Clone the repository

   git clone https://github.com/Rishi-Heda/BunkBuddies-Frontend.git
   cd BunkBuddies-Frontend

2. Install dependencies

   npm install

3. Create a local environment file

   cp .env.example .env.local

4. Configure environment variables

   BACKEND_API_URL=http://localhost:8000
   NEXT_PUBLIC_BACKEND_API_URL=http://localhost:8000
   NEXT_PUBLIC_WS_URL=ws://localhost:8000

5. Start the development server

   npm run dev

6. Open the app

   http://localhost:3000
   

Environment Variables

Variable	Required	Used By	Description
BACKEND_API_URL	Yes	Server/API routes	Backend HTTP base URL used by auth, session, and proxy routes
NEXT_PUBLIC_BACKEND_API_URL	Yes	Fallback/client-visible config	Public fallback for backend HTTP base URL
NEXT_PUBLIC_WS_URL	Yes for chat	/chat	WebSocket base URL for hostel chat and direct messages

The app falls back to http://localhost:8000 for backend HTTP requests and ws://localhost:8000 for WebSockets when variables are not set.

Available Scripts

Command	Description
npm run dev	Runs the Next.js development server with Turbopack
npm run build	Creates a production Next.js build
npm run start	Starts the production Next.js server
npm run lint	Runs the configured Next.js lint command
npm run preview	Builds with OpenNext and previews on Cloudflare locally
npm run deploy	Builds with OpenNext and deploys to Cloudflare
npm run cf-typegen	Generates Cloudflare environment TypeScript bindings

Deployment

This project is configured for Cloudflare Workers through OpenNext.

• open-next.config.ts defines the OpenNext Cloudflare adapter configuration.
• wrangler.jsonc points Cloudflare to .open-next/worker.js.
• Static assets are served from .open-next/assets.
• nodejs_compat is enabled for the Worker runtime.

To preview or deploy:

npm run preview
npm run deploy

Backend Integration

The frontend expects the backend to expose endpoints for:

• Google OAuth login and callback
• Student profile fetch/update
• Group create/update/delete/leave/join-code flows
• Group listing, filtering, and join requests
• Direct message contacts and history
• General chat history
• WebSocket endpoints for /generalChat/ws/:regNo and /dm/ws/:regNo

Authenticated frontend calls should use backendFetch() from src/app/utils/backendClient.js, which sends requests through /api/backend so the HTTP-only bb_access_token cookie can be attached server-side.

Contributors

Acknowledgments

• VinnovateIT Family for mentoring and resources
• A huge thank you to the open-source community behind the core stack: Next.js, React, Tailwind CSS, Cloudflare Workers, ESLint & OpenNext.

Made with ❤️ by VinnovateIT