Grand Hotel — Documentation

What is this?

Grand Hotel is a full-stack template that ships two products in one codebase:

Features

Tech Stack

Requirements

Before installing, make sure you have the following available:

• Node.js 18.18+ (Node 20 LTS or newer recommended).
• pnpm — install with npm install -g pnpm.
• MongoDB database — a free MongoDB Atlas cluster or a local mongod instance.
• Cloudinary account (optional, for image uploads) — configured later from the admin panel.
• SMTP credentials (optional, for email) — e.g. Gmail App Password, SendGrid, Mailgun.

Quick Start

1. Unzip & install dependencies

   # from the project root
   pnpm install

2. Create your environment file

   Copy the example and fill in the values (see Environment Variables).

   cp .env.example .env.local

3. Run the development server

   pnpm dev

   Open http://localhost:3000 — the public site loads. The dashboard lives at /super-admin, /admin, /manager and /customer.

4. Build for production

   pnpm build
   pnpm start

Environment Variables

Create .env.local in the project root. Required keys are marked below.

# ── Core ──────────────────────────────────────────────
MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/template-hotel"
NEXTAUTH_SECRET="a-long-random-secret-string"
NEXTAUTH_URL="http://localhost:3000"
AUTH_TRUST_HOST="true"

# ── Public URLs ───────────────────────────────────────
NEXT_PUBLIC_BASE_URL="http://localhost:3000"
NEXT_PUBLIC_SITE_URL="http://localhost:3000"
NEXT_API_URL="http://localhost:3000"

# ── SMTP fallback (optional — preferably set in admin Settings) ──
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_SECURE="false"
SMTP_USER="you@gmail.com"
SMTP_PASS="your-app-password"
FROM_EMAIL="you@gmail.com"

# ── SEO (optional) ────────────────────────────────────
NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION=""

First-Run Setup

The app needs a first Super Admin account before you can access the dashboard and seed demo data. Follow these steps once:

1. Register a normal account

   Start the app and register at /register. New accounts are created with the customer role.

2. Promote it to Super Admin

   In your MongoDB database, open the users collection, find your account by email, and change its role field to super_admin:

   // mongosh
   db.users.updateOne(
     { email: "you@example.com" },
     { $set: { role: "super_admin", status: true } }
   )

3. Log in as staff

   Go to /staff/login and sign in. You will be routed to /super-admin/dashboard.

4. Seed demo data (optional)

   Open Super Admin → Seed and run the seeder to populate room types, rooms, employees, customers, bookings, expenses, salaries, notifications and audit logs.

   Warning: Seeding deletes all existing data except your Super Admin account and replaces it with demo content. Use only on a fresh/dev database.

Demo Accounts

After running the seeder, the following accounts are available. All seeded users share the password Password123!.

Project Structure

The project follows the Next.js App Router convention with route groups for clean separation between public, auth, and dashboard areas.

User Roles & Access

Four primary roles drive access control. Staff roles (Super Admin, Admin, Manager) log in at /staff/login; customers log in at /login.

Additional employee job roles (cleaner, plumber, electrician, carpenter, cook, waiter, guard, assistant manager, etc.) are stored on staff records for HR/salary purposes but do not grant dashboard access.

Routing & Pages

Page URLs are centralised in lib/routes.ts via the ROUTES helper. Middleware (proxy.ts) guards dashboard routes and redirects users to the correct area based on their role.

Public routes

Auth routes

Dashboard roots

Authentication

The template uses a hybrid auth model:

• NextAuth v5 session protects pages via the proxy.ts middleware and stores the access token in the session.
• Bearer JWT protects the REST API. Tokens are signed with NEXTAUTH_SECRET and verified by lib/authenticate.ts.

Login flow

Calling a protected endpoint

fetch("/api/hotel/customer/bookings", {
  headers: { "Authorization": `Bearer ${token}` }
})

Every protected handler is wrapped with asyncHandler, which connects to the database, verifies the Bearer token, enforces an optional allowed-roles list, and validates the request body against a Zod schema before your handler runs.

// Example: super-admin-only route with body validation
export const POST = asyncHandler(roomSchema, handler, true, ["super_admin"]);
//                              schema   fn   auth   allowedRoles

Passwords are hashed with bcrypt. Email verification uses a time-limited OTP stored on the user record, and password reset uses a signed token delivered by email.

Admin Settings

Almost everything is configurable from Super Admin → Settings — no code edits needed. Settings are stored as a single document and cached (revalidated when saved).

Theming & Branding

The design system is driven by CSS variables in app/globals.css and Tailwind v4 tokens. Light and dark modes are handled by next-themes.

Brand colors

Primary and accent (amber) colours are exposed as CSS variables. The public site reads the admin-configured brand colours from the landingPage.branding settings, applied through a scoped wrapper so the admin UI stays neutral.

/* app/globals.css — core tokens */
:root{
  --primary: oklch(0.205 0 0);        /* stone-900 */
  --primary-foreground: oklch(0.985 0 0);
}

Fonts

The UI font is Lato (loaded via next/font/google in the root layout). Swap it by editing the font import in app/layout.tsx.

Logo & favicon

Upload your logo and favicon under Settings → General; they are wired into the header and document <head> automatically.

Landing Page Builder

The homepage is fully data-driven from Settings → Landing Page. Each section can be edited, reordered (where applicable) and populated with images without touching code.

Database Models

All Mongoose schemas live in /model. Every model includes timestamps and a softDelete flag (records are flagged, not physically removed).

Status enums (config/constant.ts)

Booking Lifecycle

Booking status changes are guarded by an explicit transition map (BOOKING_STATUS_TRANSITIONS). Only allowed next-states are accepted by the status endpoint, and each change is appended to the booking's statusHistory.

At any early stage a booking may be cancelled; a pending booking may be rejected.

Date-blocking logic

Dates are considered blocked by any booking except those in non-blocking states (cancelled, rejected, checked_out, cleaning). This is what the availability endpoint checks before accepting a new booking.

Automatic billing

On creation, the system computes roomCost (nightly rate × nights), serviceCharge, vatAmount from vatPercent, any miscCharges, and the final totalAmount. Payments update paidAmount and roll paymentStatus through partial → paid.

API Conventions

All endpoints live under /api. The main API is namespaced under /api/hotel, with a versioned mobile API under /api/v1.

Standard response envelope

{
  "status": true,
  "message": "Operation successful!",
  "data": { /* payload or null */ },
  "pagination": { /* present on list endpoints */ }
}

Authentication header

Authorization: Bearer <jwt-token>

Validation errors (HTTP 400)

{
  "status": false,
  "message": "Request validation failed!",
  "data": { "email": "Valid email is required!" }
}

Public = no token required  ·  Auth = Bearer token + role required

Auth API

Base path: /api/hotel/auth

Public API

Base path: /api/hotel/public — no authentication required.

Customer API

Base path: /api/hotel/customer — requires a customer Bearer token.

Manager & Admin API

Role-scoped dashboard data.

Super Admin API

Base path: /api/hotel/super-admin — requires a Super Admin Bearer token. Full CRUD across every module.

Dashboard & Reports

Rooms & Room Types

Bookings

Guests & Employees

Salaries & Expenses

Reviews, Contact & Newsletter

Settings

Notifications & Seed

Base path: /api/hotel/notifications

Mobile API (v1)

Base path: /api/v1 — a versioned, mobile-friendly surface for native/3rd-party clients.

Deployment

The app deploys anywhere that runs Node.js. Vercel is the simplest path.

Vercel

1. Push to Git

   Push the project to a GitHub/GitLab repo.

2. Import to Vercel

   Create a new project and import the repo.

3. Add environment variables

   Copy every key from your .env.local into the Vercel project settings. Set NEXTAUTH_URL and the public URLs to your production domain.

4. Deploy

   Vercel builds with pnpm build automatically.

Self-hosted / VPS

pnpm install
pnpm build
pnpm start   # serves on port 3000 — put Nginx/PM2 in front

Troubleshooting & FAQ

I can't reach the dashboard after registering

New accounts are customer by default. Promote your account to super_admin in MongoDB (see First-Run Setup), then log in at /staff/login.

Database connection fails

Verify MONGODB_URI and that your IP is whitelisted in MongoDB Atlas (Network Access). The database name should be template-hotel.

Emails aren't sending

Configure SMTP in Settings → SMTP and use the Send test email button. For Gmail, use an App Password, not your account password. SMTP env vars act only as a fallback.

Image uploads fail

Fill in Cloudinary credentials under Settings → Cloudinary. Without them, image upload features are disabled.

Auth redirect loop

Make sure NEXTAUTH_URL matches the URL you're visiting and AUTH_TRUST_HOST=true is set.

Build error: middleware not found

This project uses Next.js 16, where middleware is proxy.ts with a default export — do not rename it to middleware.ts.

Public site shows a maintenance screen

Maintenance Mode is enabled in Settings → General. Turn it off to restore the public site.

Support & Credits

Thank you for choosing Grand Hotel — Hotel Management System. We hope it accelerates your project.

Built with

Next.js · React · TypeScript · MongoDB · Mongoose · Tailwind CSS · Radix UI · NextAuth · Zod · React Hook Form · TanStack Table · Framer Motion · Cloudinary · Nodemailer · TipTap · Zustand.