Skip to main content

Microservices Architecture

This document details the microservices architecture of HMP.

Service Overview​

HMP is composed of several microservices, each handling a specific business domain.

Service Specifications​

Auth Service​

Purpose: Handle authentication and authorization

Endpoints:

  • POST /auth/login - User login
  • POST /auth/refresh - Refresh access token
  • POST /auth/logout - User logout
  • GET /auth/me - Get current user

Events Published:

  • user.logged_in
  • user.logged_out
  • password.changed

Reservation Service​

Purpose: Manage reservations and availability

Endpoints:

  • GET /reservations - List reservations
  • POST /reservations - Create reservation
  • PUT /reservations/:id - Update reservation
  • DELETE /reservations/:id - Cancel reservation
  • GET /availability - Check availability

Events Published:

  • reservation.created
  • reservation.modified
  • reservation.cancelled

Events Consumed:

  • room.status_changed
  • rate.updated

Front Desk Service​

Purpose: Handle check-in/out and room operations

Endpoints:

  • POST /checkin/:reservationId - Check in guest
  • POST /checkout/:roomId - Check out guest
  • POST /room-move - Move guest to another room
  • GET /arrivals - List today's arrivals
  • GET /departures - List today's departures

Events Published:

  • guest.checked_in
  • guest.checked_out
  • room.assigned

Housekeeping Service​

Purpose: Manage room cleaning and status

Endpoints:

  • GET /rooms/status - Get all room statuses
  • PUT /rooms/:id/status - Update room status
  • GET /tasks - List housekeeping tasks
  • POST /tasks - Create cleaning task

Events Published:

  • room.cleaned
  • room.inspected
  • room.out_of_order

Events Consumed:

  • guest.checked_out

POS Service​

Purpose: Restaurant and outlet operations

Endpoints:

  • GET /orders - List orders
  • POST /orders - Create order
  • PUT /orders/:id - Update order
  • POST /orders/:id/settle - Settle bill
  • POST /orders/:id/transfer - Transfer to room

Events Published:

  • order.created
  • order.settled
  • charge.posted

Inter-Service Communication​

Synchronous (HTTP/REST)​

Used for real-time operations requiring immediate response:

// Example: Front Desk calling Reservation Service
const reservation = await axios.get(
  `${RESERVATION_SERVICE}/reservations/${id}`
);

Asynchronous (Message Queue)​

Used for event-driven operations:

// Publishing an event
await messageQueue.publish('reservation.created', {
  reservationId: 'res_123',
  guestId: 'guest_456',
  arrival: '2026-02-15'
});

// Subscribing to events
messageQueue.subscribe('guest.checked_out', async (event) => {
  await createCleaningTask(event.roomId);
});

Service Discovery​

Services register with a service registry and discover each other dynamically:

services:
  reservation:
    host: reservation-service
    port: 3001
  frontdesk:
    host: frontdesk-service
    port: 3002
  housekeeping:
    host: housekeeping-service
    port: 3003

Circuit Breaker Pattern​

Services implement circuit breakers to handle failures gracefully:

const breaker = new CircuitBreaker(callReservationService, {
  timeout: 3000,
  errorThresholdPercentage: 50,
  resetTimeout: 30000
});

Data Ownership​

Each service owns its data and exposes it via APIs:

ServiceOwned Data
ReservationReservations, Availability
GuestGuest profiles, Preferences
HousekeepingRoom status, Tasks
POSOrders, Menu items

Deployment​

Each service is deployed as a container:

# docker-compose.yml
services:
  reservation-service:
    image: hmp/reservation-service:latest
    ports:
      - "3001:3000"
    environment:
      - DATABASE_URL=postgresql://...

  frontdesk-service:
    image: hmp/frontdesk-service:latest
    ports:
      - "3002:3000"