HostelOS/Almanik PMS Development

Stack

Backend:  Node.js + Express.js
Database: SQLite3 (server/almanik.db)
Frontend: Vanilla JS + HTML (SPA-like)
Auth:     Session-based + CASL RBAC
Charts:   Chart.js

Critical Authentication Pattern

// requireAuth middleware sets req.user, NOT req.session
// CORRECT:
req.user?.role
req.user?.id

// WRONG - causes undefined bugs:
req.session?.user?.role  // BUG!
req.session?.role        // BUG!

Booking State Machine

pending   -> [confirmed, cancelled]
confirmed -> [active, cancelled, no_show]
active    -> [completed]
completed, cancelled, no_show -> [] (terminal states)

Validate transitions with validateBookingStatusTransition(current, new) in server/validations/business-rules.js.

Financial Formulas

// ADR - Average Daily Rate (uses NIGHTS, not beds)
ADR = revenue.total / bed_nights_sold

// Occupancy Rate
occupancy = (bed_nights_sold / bed_nights_available) * 100

// RevPAB - Revenue Per Available Bed-night
RevPAB = revenue.total / bed_nights_available

// LOS - Length of Stay
LOS = total_nights / total_bookings

// calculateNights (DRY pattern)
// Location: server/utils/date-utils.js
nights = Math.max(1, daysDiff(checkIn, checkOut))

Key Files Map

File	Purpose	Lines
server/server-simple.js	Main backend	~6000
public/index.html	Main SPA	~9000
server/modules/unified-metrics.js	Metrics endpoint	611
server/validations/business-rules.js	State machine	~100
server/utils/date-utils.js	calculateNights	29
server/utils/retry.js	Exponential backoff	67
public/finanzas.html	Finance module	1411
public/js/finanzas.js	Finance JS	1353

API Pattern

// All requests require session-id header
fetch('/api/endpoint', {
  headers: {
    'Content-Type': 'application/json',
    'session-id': sessionId
  }
});

// Login returns sessionId
POST /api/login -> { sessionId, user: { id, role, permissions } }

Common Bugs & Fixes

SQLite Missing Column

-- Error: SQLITE_ERROR: no such column: X
-- Fix: Migration
ALTER TABLE tablename ADD COLUMN newcol TYPE DEFAULT value;

API Response Format Mismatch

// API returns object, frontend expects array
// Fix in frontend:
const data = response?.sources || response || [];

Session Path Bug

// WRONG: req.session?.user?.role
// RIGHT: req.user?.role

Testing Commands

# Syntax check
node --check server/server-simple.js

# Health check
curl http://localhost:3000/health

# Login
curl -X POST http://localhost:3000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Almanik2025!"}'

# Test with session
curl http://localhost:3000/api/endpoint \
  -H "session-id: YOUR_SESSION_ID"

Test Users

Username	Password	Role
admin	Almanik2025!	administrador
recepcion	Recep123!	recepcionista
voluntario1	Vol123!	voluntario

References

• Database Schema: See references/database.md
• API Endpoints: See references/api.md
• Business Rules: See references/business-rules.md
• Roles & Permissions: See references/rbac.md