v7 Hotel — Property Management System & Landing Page

A modern, open-source web application designed for boutique hotels. This project comprises a high-conversion, SEO-optimized public landing page for guest bookings, and a real-time, role-gated internal Property Management System (PMS) dashboard for hotel operations.

🚀 Tech Stack

Core:

• Framework: Next.js 16 (App Router) with React 19
• Language: TypeScript
• Styling: Tailwind CSS v4

Backend & Database:

• Database: Supabase (PostgreSQL) — Realtime, RLS, Storage
• Auth: Supabase Auth (JWT-based, Session Management)
• ORM: Drizzle ORM + drizzle-kit

State Management & Data Fetching:

• Server State: TanStack Query (React Query)
• Tables: TanStack Table (Headless UI)
• Forms: react-hook-form + zod schema validation

UI & Assets:

• Primitives: Base UI (@base-ui/react)
• Icons: Iconoir (iconoir-react)
• Animations: Framer Motion

Infrastructure & Tooling:

• Emails: Resend (via Supabase Edge Functions)
• Security: Cloudflare Turnstile (CAPTCHA)
• Monitoring: Sentry & Pino (structured logging)
• Testing: Vitest + React Testing Library + Playwright (E2E)
• Package Manager: pnpm

📦 Installation & Setup

1. Clone the repository and install dependencies:

   git clone <repo-url>
   cd v7-hotel
   pnpm install

2. Set up Environment Variables: Copy the .env.example to .env.local and fill in your Supabase, Resend, and Cloudflare credentials.

   cp .env.example .env.local

3. Database Setup: Ensure you have a Supabase project created. Run the Drizzle migrations to scaffold the database schema:

   pnpm run db:generate
   pnpm run db:migrate

   Apply the SQL Editor files found in supabase/sql-editor/ directly in your Supabase SQL console to configure Row Level Security (RLS) policies, triggers, and Vault.

4. Run the Development Server:

   pnpm dev

   The application will be available at http://localhost:3000.

5. Web-Based Installer: Once the application is running, navigate to http://localhost:3000/install to run the interactive setup wizard. This will securely bootstrap your initial Admin account, hotel branding, and core settings directly into the database.

💎 Key Features

• Public Landing Page: SSR optimized, stunning dynamic designs with Framer Motion, and a seamless booking wizard.
• Role-Based Access Control (RBAC): Distinct dashboards for Admins, Receptionists, and Housekeeping staff enforcing strictly gated routes.
• Real-Time Synchronization: Supabase Realtime automatically syncs room statuses and booking updates across devices.
• Dynamic Hotel Settings: Fully configurable pricing rules, dynamic taxes, and customized branding managed dynamically via the database.
• Data Export: PDF invoice generation and Excel/CSV analytics exports.

📖 Architecture & Developer Documentation

For a deep dive into the system's codebase, data models, state machines, and coding guidelines, check out the Project Architecture & Developer Guide.

⚖️ Advantages vs. Disadvantages

Advantages:

• Real-Time Operational Synchronicity: Receptionists, housekeepers, and managers view room statuses (Available, Occupied, Dirty) updated instantly across devices without page reloads, thanks to automated database sync.
• High-Conversion Guest Booking Flow: A seamless, multi-step public reservation wizard optimized for guest UX, featuring interactive maps and secure anti-spam protection.
• Flexible & Global Operations Setup: Full operational configurability—such as regional tax rules (VAT, GST, PPN), currency locales, custom timezones, late checkout check times, and night-deposit rules—managed directly from the Admin UI without code updates.
• Secure Guest Document Storage & Ledger Tracking: Encrypted storage of guest identity numbers (PII protection) and signed download links for uploaded document copies, combined with comprehensive ledger tracking for extra charges (room service, laundry) and automated PDF invoice generation.

Disadvantages:

• No Integrated Offline Guest Registration: The PMS requires an active internet connection to authenticate staff and synchronize room bookings; it lacks a native offline-first local cache for check-ins during network outages.
• No Native Payment Gateway Integration (Simulation Only): The current version features a simulated checkout payment ledger, requiring manual payment validation until direct payment processors are configured.
• Basic Housekeeping Checklist: Housekeeping flows are limited to simple room cleanliness status updates (dirty ➔ available) rather than itemized task-checklists (linens, towels, toiletries) or granular staff cleaning assignments.