CRM-Hotel/docs/plans/2026-02-15-hotel-front-office-design.md

Hotel Front-Office System Design

Date: 2026-02-15 Status: Approved Approach: Module-by-module sequential build (Approach A)

Decisions

Decision	Choice
Scope	All front-office modules
UI Style	Dark theme with gold accents (#d4a574)
Bookings	Channel manager ready (data model supports it, APIs deferred)
Multi-tenant	Deferred - single-hotel system first
Auth	Upgrade to JWT with route protection
Language	Bilingual Spanish/English (react-i18next)

Build Order

1. Foundation (JWT, i18n, dark theme, DB schema)
2. Room Dashboard & Status Management
3. Reservations Module
4. Guest Management
5. Housekeeping
6. Room Service
7. Events & Venues
8. Employee Scheduling
9. Reports & Analytics

---

1. Foundation Layer

1.1 JWT Authentication

• Add jsonwebtoken and bcryptjs packages to backend
• Create authMiddleware.js verifying JWT on all /api/* routes except /api/auth/login and /api/auth/refresh
• Access token: 15min expiry, stored in memory (frontend)
• Refresh token: 7 days, httpOnly cookie
• POST /api/auth/refresh endpoint
• Frontend Axios interceptor: attach token, auto-refresh on 401
• Update AuthContext for token lifecycle
• DB: refresh_tokens table (token, user_id, expires_at, revoked)

1.2 Internationalization

• Packages: react-i18next, i18next, i18next-browser-languagedetector
• Locale files: /frontend/src/locales/es.json, /frontend/src/locales/en.json
• Replace LenguageContext with i18next provider
• Language switcher component in navbar
• New modules use translation keys from start
• Existing modules migrated incrementally

1.3 Dark Theme Design System

CSS custom properties in theme.css:

• Background: #0a0a0a (main), #1a1a1a (cards), #2a2a2a (elevated)
• Accent: #d4a574 (gold) for primary actions
• Text: #ffffff (primary), #a0a0a0 (secondary)
• Status: green (available), blue (occupied), yellow (cleaning), red (maintenance)
• Success: #22c55e, Warning: #eab308, Error: #ef4444, Info: #3b82f6
• All new components built with these tokens via Tailwind

1.4 Database Schema

-- Guest Management
CREATE TABLE guests (
    id SERIAL PRIMARY KEY,
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    email VARCHAR(255),
    phone VARCHAR(50),
    id_type VARCHAR(50),
    id_number VARCHAR(100),
    nationality VARCHAR(100),
    address TEXT,
    notes TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Reservations
CREATE TABLE reservations (
    id SERIAL PRIMARY KEY,
    room_id INTEGER REFERENCES rooms(id),
    guest_id INTEGER REFERENCES guests(id),
    check_in DATE NOT NULL,
    check_out DATE NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    channel VARCHAR(50),
    total_amount DECIMAL(12,2),
    adults INTEGER DEFAULT 1,
    children INTEGER DEFAULT 0,
    notes TEXT,
    created_by INTEGER REFERENCES users(id),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
-- status: pending, confirmed, checked_in, checked_out, cancelled
-- channel: direct, booking, expedia, airbnb, other

-- Guest Stay History
CREATE TABLE guest_stays (
    id SERIAL PRIMARY KEY,
    guest_id INTEGER REFERENCES guests(id),
    reservation_id INTEGER REFERENCES reservations(id),
    room_id INTEGER REFERENCES rooms(id),
    check_in TIMESTAMP,
    check_out TIMESTAMP,
    total_charged DECIMAL(12,2),
    rating INTEGER,
    feedback TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Room Status Audit Log
CREATE TABLE room_status_log (
    id SERIAL PRIMARY KEY,
    room_id INTEGER REFERENCES rooms(id),
    previous_status VARCHAR(20),
    new_status VARCHAR(20),
    changed_by INTEGER REFERENCES users(id),
    changed_at TIMESTAMP DEFAULT NOW()
);

-- Housekeeping Tasks
CREATE TABLE housekeeping_tasks (
    id SERIAL PRIMARY KEY,
    room_id INTEGER REFERENCES rooms(id),
    assigned_to INTEGER REFERENCES employees(id),
    priority VARCHAR(10) DEFAULT 'normal',
    type VARCHAR(20) NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    notes TEXT,
    started_at TIMESTAMP,
    completed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);
-- priority: high, normal, low
-- type: checkout, maintenance, deep_clean, turndown
-- status: pending, in_progress, completed

-- Menu Items (Room Service)
CREATE TABLE menu_items (
    id SERIAL PRIMARY KEY,
    name VARCHAR(200) NOT NULL,
    description TEXT,
    price DECIMAL(10,2) NOT NULL,
    category VARCHAR(50),
    available BOOLEAN DEFAULT TRUE,
    image_url VARCHAR(500),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Room Service Orders
CREATE TABLE room_service_orders (
    id SERIAL PRIMARY KEY,
    room_id INTEGER REFERENCES rooms(id),
    guest_id INTEGER REFERENCES guests(id),
    status VARCHAR(20) DEFAULT 'pending',
    total DECIMAL(10,2),
    notes TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
-- status: pending, preparing, delivering, delivered, cancelled

-- Order Items
CREATE TABLE order_items (
    id SERIAL PRIMARY KEY,
    order_id INTEGER REFERENCES room_service_orders(id),
    menu_item_id INTEGER REFERENCES menu_items(id),
    quantity INTEGER NOT NULL DEFAULT 1,
    price DECIMAL(10,2) NOT NULL,
    notes TEXT
);

-- Venues
CREATE TABLE venues (
    id SERIAL PRIMARY KEY,
    name VARCHAR(200) NOT NULL,
    capacity INTEGER,
    area_sqm DECIMAL(8,2),
    price_per_hour DECIMAL(10,2),
    amenities JSONB DEFAULT '[]',
    description TEXT,
    status VARCHAR(20) DEFAULT 'available',
    created_at TIMESTAMP DEFAULT NOW()
);

-- Events
CREATE TABLE events (
    id SERIAL PRIMARY KEY,
    venue_id INTEGER REFERENCES venues(id),
    name VARCHAR(200) NOT NULL,
    organizer VARCHAR(200),
    event_date DATE NOT NULL,
    start_time TIME NOT NULL,
    end_time TIME NOT NULL,
    guest_count INTEGER,
    status VARCHAR(20) DEFAULT 'confirmed',
    notes TEXT,
    total_amount DECIMAL(12,2),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Employee Schedules
CREATE TABLE employee_schedules (
    id SERIAL PRIMARY KEY,
    employee_id INTEGER REFERENCES employees(id),
    schedule_date DATE NOT NULL,
    shift_type VARCHAR(20) NOT NULL,
    start_time TIME,
    end_time TIME,
    notes TEXT,
    UNIQUE(employee_id, schedule_date)
);
-- shift_type: morning (7-15), afternoon (15-23), night (23-7), off

-- Refresh Tokens (JWT Auth)
CREATE TABLE refresh_tokens (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    token VARCHAR(500) NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    revoked BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT NOW()
);

Add status column to existing rooms table:

ALTER TABLE rooms ADD COLUMN status VARCHAR(20) DEFAULT 'available';
-- status: available, occupied, cleaning, maintenance

---

2. Room Dashboard & Status Management

API Endpoints

• GET /api/rooms/status - All rooms with current status, guest info, floor
• PUT /api/rooms/:id/status - Update room status (cascading side effects)
• GET /api/dashboard/kpis - Occupancy %, available count, check-ins, check-outs, revenue (today)
• GET /api/dashboard/weekly-revenue - Last 7 days revenue data

UI Components

• RoomDashboard.jsx - Main page with KPI bar and floor grid
• RoomGrid.jsx - Color-coded room cards organized by floor
• RoomDetailModal.jsx - Room detail popup (guest, amenities, reservation)
• KPIBar.jsx - Top bar with 4-5 metric cards
• WeeklyRevenueChart.jsx - Bar chart component
• ArrivalsDepaturesList.jsx - Today's arrivals/departures

Business Logic

• Room status cascade: check-out -> "cleaning", housekeeping done -> "available", check-in -> "occupied"
• KPIs calculated from rooms and reservations tables
• Floor data derived from room properties

---

3. Reservations Module

API Endpoints

• GET /api/reservations - List with filters (status, dates, search)
• POST /api/reservations - Create (validates room availability)
• PUT /api/reservations/:id - Update details
• PUT /api/reservations/:id/status - Status transition with validation
• GET /api/reservations/availability - Room availability for date range

UI Components

• Reservations.jsx - Main page with card grid
• ReservationCard.jsx - Individual reservation card
• NewReservation.jsx - Creation form
• ReservationFilters.jsx - Status/date/search filters

State Machine

pending -> confirmed -> checked_in -> checked_out
pending -> cancelled
confirmed -> cancelled

Business Rules

• No double-booking (check availability before creating)
• Check-in: updates room status to "occupied", creates guest_stay record
• Check-out: updates room status to "cleaning", creates housekeeping task, closes guest_stay
• Channel field: direct, booking, expedia, airbnb, other (for future integration)

---

4. Guest Management

API Endpoints

• GET /api/guests - List with search and pagination
• POST /api/guests - Create guest profile
• PUT /api/guests/:id - Update guest
• GET /api/guests/:id - Guest details with current stay
• GET /api/guests/:id/stays - Stay history

UI Components

• Guests.jsx - Guest directory with search
• GuestCard.jsx - Guest card (avatar, contact, current room)
• GuestDetail.jsx - Full profile with stay history
• NewGuest.jsx - Guest creation form (also embedded in reservation form)

---

5. Housekeeping

API Endpoints

• GET /api/housekeeping/tasks - Tasks with filters (status, priority, staff)
• POST /api/housekeeping/tasks - Create task
• PUT /api/housekeeping/tasks/:id - Update (assign, start, complete)
• GET /api/housekeeping/staff - Available housekeeping employees with status

UI Components

• Housekeeping.jsx - Two-column layout (pending + in-progress)
• TaskCard.jsx - Task card (room, type, priority, staff, actions)
• StaffPanel.jsx - Staff availability sidebar

Automation

• Auto-create task on room check-out (type: "checkout", priority: "high")
• Task completion sets room to "available"
• Staff filtered from employees table by housekeeping department

---

6. Room Service

API Endpoints

• GET /api/room-service/orders - Active and recent orders
• POST /api/room-service/orders - Create order
• PUT /api/room-service/orders/:id/status - Update order status
• GET /api/room-service/menu - Menu items
• POST /api/room-service/menu - Add menu item
• PUT /api/room-service/menu/:id - Update/toggle availability

UI Components

• RoomServiceOrders.jsx - Active orders panel
• OrderCard.jsx - Order details (room, items, status, total, time)
• MenuManager.jsx - Menu item management
• NewOrder.jsx - Create order form

Order Flow

pending -> preparing -> delivering -> delivered
pending -> cancelled

---

7. Events & Venues

API Endpoints

• GET /api/venues - List all venues
• POST /api/venues - Create venue
• PUT /api/venues/:id - Update venue
• GET /api/events - List events (date filters)
• POST /api/events - Create event (validate venue availability)
• PUT /api/events/:id - Update event

UI Components

• Venues.jsx - Venue cards with availability
• VenueCard.jsx - Venue details (capacity, area, price, amenities)
• Events.jsx - Event listing and calendar
• NewEvent.jsx - Event creation form

---

8. Employee Scheduling

API Endpoints

• GET /api/schedules - Schedules by date range and department
• POST /api/schedules - Create/update bulk schedule entries
• GET /api/schedules/employee/:id - Individual schedule

UI Components

• Schedules.jsx - Weekly grid view
• ShiftCell.jsx - Individual cell (click to edit)
• ScheduleFilters.jsx - Department/employee filter

Shift Types

• Morning: 7:00 - 15:00 (yellow)
• Afternoon: 15:00 - 23:00 (blue)
• Night: 23:00 - 7:00 (purple)
• Off: (gray)

---

9. Reports & Analytics

API Endpoints

• GET /api/reports/occupancy - Occupancy rate by period
• GET /api/reports/revenue - Revenue by room type and period
• GET /api/reports/booking-sources - Distribution by channel
• GET /api/reports/satisfaction - Guest satisfaction (from guest_stays ratings)

UI Components

• OperationalReports.jsx - Main reports page
• PeriodSelector.jsx - Week/Month/Quarter/Year toggle
• OccupancyChart.jsx - Trend line chart
• RevenueByTypeChart.jsx - Bar chart by room type
• BookingSourcesPie.jsx - Pie chart of booking channels
• SatisfactionCard.jsx - Rating display

---

Frontend Route Structure (New)

All under /app:

/app/room-dashboard        - Room status dashboard
/app/reservations          - Reservations list
/app/reservations/new      - New reservation
/app/reservations/:id      - Reservation detail
/app/guests                - Guest directory
/app/guests/:id            - Guest detail
/app/housekeeping          - Housekeeping tasks
/app/room-service          - Room service orders
/app/room-service/menu     - Menu management
/app/venues                - Venues list
/app/events                - Events list
/app/events/new            - New event
/app/schedules             - Employee scheduling
/app/operational-reports   - Reports & analytics

Sidebar Navigation Update

Add new section to sidebar:

Operations (existing)
  ├── Dashboard (existing)
  ├── Room Dashboard (NEW)
  ├── Reservations (NEW)
  ├── Guests (NEW)

Services (NEW section)
  ├── Housekeeping (NEW)
  ├── Room Service (NEW)
  ├── Events & Venues (NEW)

Staff (existing section, renamed)
  ├── Employees (existing)
  ├── Contracts (existing)
  ├── Schedules (NEW)
  ├── Payroll (existing)

Reports (existing)
  ├── Financial Reports (existing)
  ├── Operational Reports (NEW)