HOSTLR

HOSTLR is a full-stack hostel discovery and reservation platform built with a role-based architecture for Finder, Owner, and Admin users.

Platform Overview

• Finder users can browse hostels, reserve seats, and chat with hostel owners.
• Owner users can manage hostels, rooms, seats, reservations, and conversations.
• Admin users can moderate the platform and monitor high-level metrics.
• Real-time communication is powered by Socket.IO.
• Reservation lifecycle includes automatic expiration handling.

Monorepo Structure

hostlr/
├── api.hostlr.com/         # Production backend API (Express + MongoDB + Socket.IO)
├── web.hostlr.com/         # Frontend application (React + Vite + Tailwind)
├── PLAN.md                 # Build/migration planning notes
├── PROMPT.md               # Product and scope prompt
└── TEST.md                 # Test strategy notes

Technology Stack

Frontend (web.hostlr.com)

• React 18
• Vite
• Tailwind CSS
• MUI
• TanStack Query
• Socket.IO Client

Backend (api.hostlr.com)

• Node.js (ES Modules)
• Express
• MongoDB + Mongoose
• Socket.IO
• Swagger (OpenAPI)
• Mocha + Supertest

Core Features

Authentication and Access

• JWT-based authentication
• Role-based authorization (admin, owner, finder)
• Separate Admin Panel and User Panel route organization

Hostel and Reservation Domain

• Hostel, room, and seat management for owners
• Public and role-aware browse endpoints
• Reservation creation, completion, cancellation, and expiry flows
• Scheduled expiry job for pending reservations

Realtime Chat

• Participant-scoped conversations
• Message persistence with real-time delivery
• Typing and read-state events

Admin Operations

• User moderation and role/status management
• Hostel and reservation oversight
• Dashboard aggregate metrics endpoints

Local Development Setup

1) Prerequisites

• Node.js 18+
• npm 9+
• MongoDB (local instance)

2) Install dependencies

cd api.hostlr.com && npm install
cd ../web.hostlr.com && npm install

3) Configure backend environment

Create api.hostlr.com/.env.dev with values similar to:

PORT=4000
MONGODB_URI=mongodb://127.0.0.1:27017/hostlr
ACCESS_TOKEN_SECRET=change-me
ACCESS_TOKEN_EXPIRES_IN=7d
CORS_ORIGIN=http://localhost:5173
RESERVATION_TTL_HOURS=48

4) Seed demo data

cd api.hostlr.com
npm run seed

5) Run backend and frontend

# Terminal 1
cd api.hostlr.com
npm run start

# Terminal 2
cd web.hostlr.com
npm run dev

Access Points

• Frontend: http://localhost:5173
• API base: http://localhost:4000/api
• Health (HTML): http://localhost:4000/api/health
• Health (JSON): http://localhost:4000/api/health/json
• API Docs: http://localhost:4000/hostlr-api-docs

Backend Scripts (api.hostlr.com)

• npm run start — start API server via nodemon
• npm run seed — seed database with demo data
• npm run test — run backend test suite

Frontend Scripts (web.hostlr.com)

• npm run dev — start Vite dev server
• npm run build — production build
• npm run preview — preview production build

Demo Accounts

• Admin: admin@hostlr.test / Admin@123
• Owner: owner1@hostlr.test / Owner@123
• Finder: finder1@hostlr.test / Finder@123

API Domains at a Glance

• ap/* — Admin Panel APIs
• up/* — User Panel APIs (owner and finder)

License

This project is licensed under the Attribution 4.0 International (CC BY 4.0) license. You are free to use, modify, and distribute this code for any purpose, provided you give appropriate credit to the original author(s).

For details, see Creative Commons BY 4.0.