Hotel Management Module - Technology Stack and Architecture¶

Overview¶

This document describes the technology stack and system architecture for the Local Hotel Management module in TQPro. The module manages contracted hotel inventory including hotel properties, room types, rate calendars, and meal plans.

System Architecture¶

Three-Tier Architecture¶

The Hotel Management module follows a classic three-tier architecture pattern:

┌─────────────────────────────────────────────────────────┐
│                    PRESENTATION LAYER                    │
│                                                          │
│  ┌────────────────────────────────────────────────┐    │
│  │         tqweb-adm (Web Application)            │    │
│  │                                                 │    │
│  │  • hotelmgmt.html (1452 lines)                 │    │
│  │  • js/modules/hotelmgmt.js (1428 lines)        │    │
│  │  • Foundation 6.x CSS Framework                │    │
│  │  • jQuery 3.x                                  │    │
│  └────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
                            ↕ AJAX/JSON
┌─────────────────────────────────────────────────────────┐
│                      API LAYER                           │
│                                                          │
│  ┌────────────────────────────────────────────────┐    │
│  │         tqapi (REST API Server)                │    │
│  │                                                 │    │
│  │  • HotelApi.java (1247 lines)                  │    │
│  │  • Jakarta EE / JAX-RS                         │    │
│  │  • Session-based Authentication                │    │
│  │  • JSON Serialization/Deserialization          │    │
│  └────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
                            ↕ Entity Operations
┌─────────────────────────────────────────────────────────┐
│                   BUSINESS LOGIC LAYER                   │
│                                                          │
│  ┌────────────────────────────────────────────────┐    │
│  │         tqapp (Business Entities)              │    │
│  │                                                 │    │
│  │  • CHotel.java (231 lines)                     │    │
│  │  • CHotelRoom.java (120 lines)                 │    │
│  │  • CRoomCalendarEntry.java (463 lines)         │    │
│  │  • CMealPlan.java (77 lines)                   │    │
│  │  • EntityFacade (ORM Layer)                    │    │
│  │  • TlinqEntityFactory                          │    │
│  └────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
                            ↕ JDBC
┌─────────────────────────────────────────────────────────┐
│                     DATA LAYER                           │
│                                                          │
│  • Relational Database (PostgreSQL/MySQL)               │
│  • Tables: HOTEL, HOTEL_ROOM, ROOM_CALENDAR_ENTRY,      │
│           MEAL_PLAN                                      │
└─────────────────────────────────────────────────────────┘

Layer Responsibilities¶

1. Presentation Layer (tqweb-adm)¶

Purpose: User interface and client-side logic

Technologies: - HTML5 for page structure - JavaScript ES6 Modules for business logic - jQuery 3.x for DOM manipulation and AJAX - Foundation 6.x CSS framework for responsive UI - Custom CSS for hotel management specific styling

Key Files: - hotelmgmt.html - Main page structure with accordion navigation and dialogs - js/modules/hotelmgmt.js - Module containing all client-side logic

Responsibilities: - Render user interface components - Handle user interactions and events - Validate form inputs before submission - Make AJAX calls to REST API - Display data received from API - Manage client-side state (selected hotel, room, calendar data) - Calculate and display price breakdowns

2. API Layer (tqapi)¶

Purpose: RESTful API endpoints for hotel management operations

Technologies: - Java 17 - Jakarta EE (formerly Java EE) - JAX-RS for REST API implementation - JSON for data interchange - Custom session management

Key Files: - HotelApi.java - All REST endpoints for hotel management

Responsibilities: - Expose REST API endpoints - Authenticate requests using session tokens - Validate request parameters - Delegate business operations to entity layer - Serialize/deserialize JSON requests and responses - Handle errors and return appropriate HTTP status codes - Enforce authorization rules (employee-only operations)

API Patterns: - All endpoints use POST method - Request format: { "session": "...", "data": {...} } - Response format: { "success": true/false, "data": {...}, "error": {...} } - Session token passed in request body or Authorization header - Consistent error handling with error codes and messages

3. Business Logic Layer (tqapp)¶

Purpose: Business entities and data persistence

Technologies: - Java 17 - Custom ORM (EntityFacade) - Entity factory pattern (TlinqEntityFactory) - JDBC for database access

Key Files: - CHotel.java - Hotel master entity - CHotelRoom.java - Room type entity - CRoomCalendarEntry.java - Daily pricing entry entity - CMealPlan.java - Meal plan entity

Responsibilities: - Define data models (entities) - Implement entity validation rules - Provide build() methods for JSON deserialization - Maintain entity relationships - Encapsulate business rules - Provide data access through EntityFacade - Handle entity lifecycle (create, read, update, delete)

4. Data Layer¶

Purpose: Persistent data storage

Technologies: - Relational database (PostgreSQL or MySQL inferred) - JDBC connections - SQL queries (managed by EntityFacade)

Responsibilities: - Store and retrieve entity data - Maintain referential integrity - Provide transactional support - Index data for performance

Technology Stack Details¶

Frontend Technologies¶

HTML5¶

Semantic markup for structure
Data attributes for state management
Accordion containers for navigation
Dialog overlays for forms

JavaScript ES6 Modules¶

Key Features Used: - import/export syntax for module boundaries - Arrow functions for concise callbacks - Template literals for string interpolation - Destructuring assignments - let/const for block-scoped variables - Map objects for efficient lookups - Spread operator for array/object manipulation - Promises for asynchronous operations

Module Pattern:

// hotelmgmt.js
import { Foundation } from 'foundation-sites';
import jQuery from 'jquery';

// Module-level state
let selectedHotel = null;
let roomMap = new Map();
let roomCalendar = [];

// Exported functions (public API)
export function listHotels(namepart, area) { ... }
export function saveRoom(event) { ... }

// Private functions (internal use only)
function showHotelRooms(selRoomId) { ... }
function buildCalendarTable(cal) { ... }

jQuery 3.x¶

Usage Patterns: - DOM selection: $('#elementId'), $('.className') - Event handling: $('#btn').on('click', handler) - AJAX requests: $.ajax({ url, method, data, success, error }) - DOM manipulation: .html(), .val(), .attr(), .addClass(), .removeClass() - Form serialization: .serializeArray() - Animation: .fadeIn(), .slideDown()

Foundation 6.x CSS Framework¶

Components Used: - Grid System: Responsive layout with rows and columns - Accordion: Collapsible hotel list navigation - Tabs: Content organization (Hotel Info, Rooms Info, Promotions) - Forms: Input styling and validation - Buttons: Primary, secondary, success, alert button styles - Reveal Modals: Dialog overlays for calendar, meal plans, booking - Callout: Alert/info message boxes - Dropdown: Select menus with custom styling - Switch: Toggle controls - Table: Data grid styling

Foundation Initialization:

$(document).foundation();  // Initialize all Foundation components

Backend Technologies¶

Java 17¶

Language Features Used: - Records (potentially for DTOs) - Text blocks for multi-line strings - Pattern matching (if used) - Enhanced switch expressions - Strong typing with generics: List<CHotelRoom>, Map<String, Object> - Annotations for configuration: @POST, @Path, @Consumes, @Produces - Lambda expressions for functional programming - Streams API for data processing - Try-with-resources for resource management

Jakarta EE (JAX-RS)¶

Annotations Used:

@Path("/hotel")  // Base path for all endpoints
public class HotelApi extends HttpServlet {

    @POST                    // HTTP method
    @Path("/listHotels")     // Endpoint path
    @Consumes("application/json")  // Input format
    @Produces("application/json")  // Output format
    public Response listHotels(Map reqData) { ... }
}

Key JAX-RS Features: - Declarative REST endpoint configuration - Automatic JSON serialization/deserialization - Path parameters and query parameters support - Response object for HTTP status control - Exception mapping for error handling

Custom ORM (EntityFacade)¶

Key Features: - Session-based entity operations - CRUD operations: write(), read(), list(), delete() - Query building with criteria - Transaction management - Entity lifecycle management - Lazy loading support

Usage Pattern:

EntityFacade ef = new EntityFacade(session);

// Create/Update
CHotel hotel = TlinqEntityFactory.instance()
    .newEntity(CHotel.class, null)
    .build(hotelData);
CHotel savedHotel = (CHotel) ef.write(hotel);

// Read
CHotel hotel = (CHotel) ef.read(CHotel.class, hotelId);

// List with criteria
List<CHotelRoom> rooms = ef.list(CHotelRoom.class,
    Map.of("hotelId", hotelId));

// Delete
ef.delete(CHotelRoom.class, roomId);

Data Flow Architecture¶

Request Flow Example: Create Hotel¶

User fills hotel form
         ↓
[hotelmgmt.js] saveHotel(event)
         ↓
Validates form data
         ↓
Makes AJAX POST to /hotel/saveHotel
         ↓ JSON: { session: "...", hotel: {...} }
         ↓
[HotelApi.java] saveHotel(Map reqData)
         ↓
Validates session (checkIfEmployee)
         ↓
Extracts hotel data from request
         ↓
[CHotel.java] Creates entity via factory
         ↓
Calls build(hotelInfo) to populate fields
         ↓
[EntityFacade] write(hotel)
         ↓
Inserts into HOTEL table
         ↓
Returns saved entity with generated ID
         ↓
[HotelApi.java] Wraps in TlinqApiResponse
         ↓ JSON: { success: true, data: {...} }
         ↓
[hotelmgmt.js] Success handler
         ↓
Updates UI with new hotel
         ↓
Adds hotel to accordion list

Complex Query Flow: Search Accommodation¶

User enters search criteria (dates, occupancy)
         ↓
[hotelmgmt.js] searchAllHotels()
         ↓
POST to /hotel/searchAccommodation
         ↓ JSON: { session, checkIn, checkOut, adults, children, market }
         ↓
[HotelApi.java] searchAccommodation(Map reqData)
         ↓
Validates session and parameters
         ↓
Queries ROOM_CALENDAR_ENTRY table
  • WHERE stayDate BETWEEN checkIn AND checkOut
  • AND market = selectedMarket
  • AND available = true
  • AND stopSale = false
         ↓
Groups results by hotel and room
         ↓
For each room, calculates total cost:
  1. Loop through each night
  2. Get calendar entry for (roomId, market, stayDate)
  3. Determine if special day (weekend)
  4. Get base rate (specDayRate if special, else baseRate)
  5. Calculate extra adults/children supplements
  6. Apply rate calculation types (ABS/ADD/PCT/PCO)
  7. Add extra bed charges
  8. Add meal supplements from JSON field
  9. Sum all nights
 10. Apply margin for sell price
         ↓
Sorts rooms by price (ascending)
         ↓
Returns list of available rooms with pricing
         ↓ JSON: { success: true, data: [{hotel, room, cost, price, breakdown}] }
         ↓
[hotelmgmt.js] Renders search results
         ↓
Displays hotel cards with room options
         ↓
User can click to see price breakdown or book

Module Dependencies¶

Frontend Dependencies¶

hotelmgmt.js
    ├─ jquery (3.x)
    ├─ foundation-sites (6.x)
    ├─ modules/util.js (likely)
    ├─ modules/common.js (session management)
    └─ modules/lookup.js (partner/hotel lookups)

hotelmgmt.html
    ├─ css/foundation.min.css
    ├─ css/custom.css
    ├─ js/vendor/jquery.js
    ├─ js/vendor/foundation.js
    └─ js/modules/hotelmgmt.js

Backend Dependencies¶

HotelApi.java
    ├─ jakarta.ws.rs.* (JAX-RS annotations)
    ├─ com.perun.tlinq.entity.hotel.*
    ├─ com.perun.tlinq.util.EntityFacade
    ├─ com.perun.tlinq.util.ApiUtil
    ├─ com.perun.tlinq.api.TlinqApiResponse
    └─ com.perun.tlinq.exception.TlinqClientException

CHotel.java
    ├─ com.perun.tlinq.entity.TlinqEntity (base class)
    ├─ java.io.Serializable
    └─ java.util.Map (for build() method)

CRoomCalendarEntry.java
    ├─ com.perun.tlinq.entity.TlinqEntity
    ├─ java.util.Date
    ├─ java.io.Serializable
    └─ JSON parsing library (for mealSupplements field)

Deployment Architecture¶

Development Environment¶

Development Machine
    ├─ Source code: /home/nino/src/tqpro/
    ├─ Web files: tqweb-adm/
    ├─ Java source: tqapp/src/, tqapi/src/
    ├─ Build tool: Maven (assumed)
    └─ IDE: IntelliJ IDEA or Eclipse

Build Artifacts¶

Compiled Output
    ├─ tqapi.jar (API server)
    ├─ lib/*.jar (dependencies)
    └─ tqweb-adm/ (static web files)

Runtime Environment¶

Production Server
    ├─ Java Runtime: JRE 17
    ├─ Application Server: Standalone (jsvc) or Tomcat/Jetty
    ├─ Web Server: Apache/Nginx (reverse proxy to API)
    ├─ Database: PostgreSQL or MySQL
    └─ Logs: /var/log/tqpro/

Service Configuration¶

Based on the jsvc setup documentation found in the codebase:

# Service managed by jsvc
/home/nino/src/tqpro/config/tlinq-service.sh

# Log locations
/var/log/tqpro/tlinq-stdout.log
/var/log/tqpro/tlinq-stderr.log
/var/log/tqpro/tlinqserver-*.log

# PID file
/home/nino/src/tqpro/config/tlinq.pid

# Classpath
/home/nino/src/tqpro/config/tqapi.jar
/home/nino/src/tqpro/config/lib/*.jar

Security Architecture¶

Authentication¶

Session-based authentication: User logs in, receives session token
Session token: Passed in every API request (body or header)
Session validation: checkIfEmployee(session, true) validates session and user role
Employee-only operations: All write operations require employee role

Authorization¶

Role-based access: Employee role required for hotel management
Read operations: May allow broader access (depends on configuration)
Write operations: Restricted to employees only

Data Protection¶

No client-side storage of sensitive data: Session token stored securely (SessionStorage or Cookie)
HTTPS: All production traffic encrypted (assumed)
SQL injection prevention: EntityFacade uses parameterized queries
XSS prevention: jQuery automatically escapes HTML content

Performance Considerations¶

Frontend Optimization¶

Module loading: ES6 modules loaded on demand
Client-side caching: Selected hotel/room data cached in Maps
Minimal DOM manipulation: Batch updates to reduce reflows
Debouncing: Search inputs likely debounced (not visible in current code)

Backend Optimization¶

Database indexing: Indexes on hotelId, roomId, stayDate, market (assumed)
Query optimization: EntityFacade likely generates optimized SQL
Session pooling: Database connection pooling
Stateless API: Horizontal scaling possible

Database Optimization¶

Indexed foreign keys: hotelId, roomId for fast joins
Composite indexes: (roomId, market, stayDate) for calendar queries
Date range queries: Indexed stayDate for efficient range searches

Scalability¶

Current Architecture Scalability¶

Stateless API: Can run multiple API instances behind load balancer
Shared database: Single database (potential bottleneck)
Static web files: Can be served from CDN

Scalability Bottlenecks¶

Database: Single point of contention for all operations
Calendar search: Full table scans for date ranges (potential optimization needed)
Price calculation: Done at API level (could be pre-computed or cached)

Future Scalability Improvements¶

Read replicas: Offload read operations to database replicas
Caching layer: Redis/Memcached for frequently accessed data
Materialized views: Pre-computed availability summaries
Message queues: Async processing for bulk calendar operations
Microservices: Split into separate services (Hotel, Calendar, Search, Booking)

Integration Points¶

Internal Module Integration¶

Group Management Module (/groups/*)
Hotel selection for group accommodations
Room assignments for group passengers
Pricing retrieval for group quotes
Quotation Module (/quote/*)
Hotel costs included in quotations
Margin calculation between cost and price
CRM Module (partner agencies)
Hotel preferences by partner
Special rates for specific partners
Product Catalog (/product/*)
Hotels can be linked to products (productId field)
Activity packages may include hotel stays

External System Integration¶

None currently: System is self-contained
Future: Payment gateways, channel managers, GDS systems

Configuration¶

Application Configuration Files¶

Based on the codebase structure:

config/
    ├─ tqapi.jar              # Main API application
    ├─ lib/                   # Dependency JARs
    ├─ log.properties         # Logging configuration
    ├─ tlinq-service.sh       # Service control script
    ├─ logrotate-tlinq.conf   # Log rotation config
    └─ database.properties    # Database connection (assumed)

Environment-Specific Configuration¶

Development: localhost database, verbose logging
Staging: Test database, info-level logging
Production: Production database, error-level logging, log rotation

Technology Selection Rationale¶

Why Jakarta EE / JAX-RS?¶

Standard: Industry-standard Java REST framework
Annotations: Declarative configuration reduces boilerplate
Portability: Can run on any Jakarta EE server
JSON support: Built-in serialization/deserialization

Why jQuery?¶

Mature: Stable, well-documented library
Browser compatibility: Handles cross-browser inconsistencies
AJAX: Simplified asynchronous requests
DOM manipulation: Concise syntax for common operations
Large ecosystem: Plugins available for extended functionality

Why Foundation CSS?¶

Responsive: Mobile-first design out of the box
Components: Rich set of UI components (accordion, tabs, modal)
Customizable: SASS-based customization
Accessibility: Built-in ARIA support

Why Custom ORM (EntityFacade)?¶

Lightweight: No heavy ORM framework overhead
Control: Full control over SQL generation
Integration: Tight integration with existing Tlinq framework
Simplicity: Easier to debug and maintain than Hibernate/JPA

Version Control and Build¶

Version Control¶

Git: Source code management (inferred from git status)
Branches: Feature branches for development
Main branch: master for production-ready code
Current branch: codev (development)

Build Process¶

Build tool: Maven or Gradle (likely Maven based on Java ecosystem)
Compilation: mvn clean package or gradle build
Output: JAR files for deployment
Dependencies: Managed via pom.xml or build.gradle

Monitoring and Logging¶

Logging Framework¶

Based on JSVC setup documentation: - Java Util Logging: java.util.logging.FileHandler - Log files: /var/log/tqpro/tlinqserver-*.log - Rotation: Automatic at 10MB per file - Retention: Configurable in log.properties

Log Levels¶

SEVERE: Critical errors requiring immediate attention
WARNING: Potential issues that should be reviewed
INFO: General informational messages (startup, shutdown, key operations)
FINE/FINER/FINEST: Debug-level logging (disabled in production)

Monitoring Points¶

API response times: Monitor endpoint latency
Error rates: Track failed requests by endpoint
Database query times: Identify slow queries
Session count: Active user sessions
Memory usage: JVM heap utilization
Disk usage: Log file growth

Summary¶

The Hotel Management module uses a classic three-tier architecture with clear separation of concerns:

Frontend: Modern JavaScript (ES6 modules) with jQuery for DOM manipulation and Foundation for UI components
API: Jakarta EE JAX-RS REST services providing JSON endpoints
Backend: Java entities with custom ORM for data persistence
Database: Relational database for persistent storage

This architecture provides: - ✅ Maintainability: Clear layer boundaries - ✅ Scalability: Stateless API allows horizontal scaling - ✅ Testability: Each layer can be tested independently - ✅ Security: Session-based authentication with role authorization - ✅ Performance: Efficient data access with caching opportunities

The technology choices balance modern practices with proven stability, making the system suitable for production use in a travel agency environment.