PTX Channel Manager - Project Overview & PDR

Project: PTX Channel Manager (ptx-cm)
Version: 2.6.0
Status: Active — Rate Engine & BPM Sprint
Last Updated: 2026-03-30

---

1. Executive Summary

PTX Channel Manager is a unified OTA channel management platform that prevents overbookings by auto-syncing room availability across Booking.com, Agoda, Traveloka, and Expedia within 60 seconds. Built for 100+ properties across Vietnam, Indonesia, and Malaysia, with multi-country staff access control and encrypted OTA credential management.

Key Achievement: Reduced manual overbooking reconciliation by 95% with real-time alerts and automated inventory synchronization across 4 OTA platforms.

---

2. Problem Statement

Before PTX-CM

• Manual Overbooking Risk: Properties had to manually track inventory across 4 separate OTA dashboards
• Human Error: Staff entry errors caused 5-10% overbooking incidents monthly
• Slow Sync: Changes took 2-4 hours to propagate across all channels
• Limited Visibility: No real-time alert system for overbookings
• Credential Management: OTA credentials stored in spreadsheets without encryption
• Multi-Country Complexity: No built-in country-scoped access control

Solution

Unified dashboard with automated polling, real-time overbooking alerts, encrypted credential storage, and country-scoped staff access.

---

3. Target Users & Use Cases

Primary Users

Role	Use Case	Frequency
Property Manager	Monitor occupancy, view booking timeline, manage OTA connections	Daily
Reservations Staff	Check availability, confirm bookings, resolve overbooking alerts	Hourly
Finance Team	View revenue metrics, export booking data for accounting	Weekly
OTA Operator	Configure OTA accounts, test connections, manage room mappings	Weekly
Customer Service	Audit booking history, view guest info, handle complaints	Daily
Admin/Super Admin	Manage users, roles, permissions, global settings	Weekly

Core Workflows

Workflow 1: New OTA Connection

1. Manager navigates to OTA Accounts → Connect
2. Enters OTA credentials (securely encrypted)
3. Tests connection to verify authentication
4. Maps room types to OTA rate plans
5. Activates sync for property

Workflow 2: Booking Arrival

1. OTA sends new booking via API
2. System polls OTA extranet every 2-3 minutes
3. Pulls booking record → deduplicates by OTA booking ID
4. Recalculates availability per room type
5. If overbooking detected → Creates alert + notifies staff
6. Pushes updated availability to all connected OTAs

Workflow 3: Resolving Overbooking

1. Manager sees alert in dashboard
2. Opens booking detail → views booking timeline + status history
3. Transitions booking status via state machine (e.g., Confirmed → CheckedIn)
4. System automatically recalculates availability
5. Sends updated rates/availability to OTAs

---

4. Functional Requirements (Features)

Phase 1: Authentication & Authorization (COMPLETE)

• JWT-based login with email/password
• Refresh token rotation with database-backed revocation
• Role-based access control with bitmask permissions
• Country-scoped access (staff see only their country, managers can switch)
• Encrypted password storage with bcrypt
• Password reset workflow (forgot-password, reset token, change-password)
• HttpOnly cookie storage for token security
• Rate limiting on login (5/min) and refresh (10/min)

Phase 2: Property & Inventory Management (COMPLETE)

• CRUD operations for properties with timezone/currency assignment
• Room type definitions per property (name, total count, base rate)
• Supplier/room-owner management with bank details
• Supplier ↔ room allocation with per-supplier inventory rules
• Property list with country filtering and pagination

Phase 3: OTA Integration (COMPLETE)

• OTA account management with AES-256-GCM encrypted credentials
• Multi-OTA support: Booking.com, Agoda, Traveloka, Expedia
• OTA adapter factory pattern for pluggable implementations
• OTA connection management (property ↔ OTA account links)
• Room type ↔ OTA rate plan/room ID mapping
• OTA discovery and auto-import of available properties
• Connection testing with error reporting

Phase 4: Booking Sync & Management (COMPLETE)

• Automated polling scheduler (150s interval per property)
• Booking pull service with OTA adapter pattern
• Booking deduplication by OTA booking ID
• Real-time booking storage in PostgreSQL
• Booking list with filters (date range, status, OTA source)
• Booking detail view with complete audit timeline
• Status transition dialog with role-gated workflows
• Booking metadata display (guest name, room type, rate, etc.)

Phase 5: Availability & Alerts (COMPLETE)

• Automatic availability calculation after each booking
• Daily availability tracking per room type
• Overbooking detection (booked ≥ total rooms)
• Alert creation for critical conditions
• Alert list with status tracking (new, resolved, snoozed)
• Real-time notification to staff via email/dashboard
• Alert detail with root cause analysis

Phase 6: Dashboard & Monitoring (COMPLETE)

• KPI cards: Occupancy rate, revenue, avg daily rate, sync success
• Sync status display: Queue size, job count, failure rate
• Recent bookings table
• Active alerts summary
• System health indicator (postgres, redis, OTA connectivity)

Phase 7: Settings & Configuration (COMPLETE)

• Global settings: Booking pull interval, notification toggles, buffer room count
• User management: CRUD staff accounts, role assignment, country scoping
• Role definitions with permission bitmask editor
• Country reference data management
• Booking status customization with color/icon assignment
• Booking status transition state machine editor (visual workflow)
• Notification preferences (email, LINE, Slack)

Phase 8: Audit & Compliance (COMPLETE)

• Activity log tracking all HTTP requests (email, method, path, status)
• Booking history timeline with state change events
• User action audit trail
• Data export: Bookings to CSV, properties to CSV
• Compliance: GDPR-compliant data retention settings

---

5. Non-Functional Requirements

Performance Targets

Metric	Target	Status
Booking sync latency	<60 seconds (poll to OTA push)	Active
Dashboard load time	<2 seconds	Active
API response time (p95)	<500ms	Active
Database query time (p95)	<100ms	Active
Concurrent users	50+	Active
Booking throughput	1000 bookings/hour	Active

Scalability

• Monorepo supports 100+ properties per instance
• Multi-tenant ready (country-scoped isolation)
• Redis-backed BullMQ for async scaling
• PostgreSQL with indexes for fast queries
• Stateless backend for horizontal scaling

Security Standards

• JWT with 15m access token + 7d refresh token
• AES-256-GCM encryption for OTA credentials
• Bcrypt password hashing with salt rounds: 12
• Country-scoped queries prevent data leakage
• Rate limiting on sensitive endpoints
• HTTPS/TLS for all traffic
• HttpOnly cookies for token storage

Availability

• Target: 99.5% uptime
• Database backups: Daily + automated snapshots
• Redis persistence: AOF enabled
• Graceful degradation: Async jobs retry on failure
• Health checks: Liveness probes on /health endpoint

Maintainability

• TypeScript for type safety
• NestJS architectural standards
• Code documentation via JSDoc
• Test coverage: 80% services, 60% controllers
• Semantic versioning for releases
• Changelog maintenance

---

6. Technology Stack (Validated & Production-Ready)

Layer	Technology	Rationale
Frontend	Next.js 16, React 18	Modern SSR, strong ecosystem
State	Context API + SWR	Lightweight, no Redux overhead
Forms	react-hook-form + zod	Performant, typed validation
Tables	TanStack Table (react-table)	Headless, Tailwind compatible
Styling	Tailwind CSS	Utility-first, rapid prototyping
Backend	NestJS 10	Enterprise patterns, TypeScript native
Auth	Passport JWT	Proven, wide adoption
Database	PostgreSQL 16 + Prisma 7	ACID, type-safe ORM
Queue	Redis 7 + BullMQ	Fast, persistent job tracking
Encryption	crypto (Node.js) AES-256-GCM	No external dependency, cryptographically sound
Build	Turborepo + pnpm	Monorepo optimization, fast installs

---

7. Architecture & Design Patterns

Sync Engine (Core Feature)

Architecture: Three-tier async processing

• Polling Layer: BullMQ scheduler creates repeating jobs every 150s
• Pulling Layer: OtaPollingProcessor runs concurrency:3, invokes BookingPullService
• Calculation Layer: AvailabilitySyncProcessor runs concurrency:2, recalculates inventory, detects overbooking
• Push Layer: OTA adapters push updated availability back to channels

Benefits: Decoupled, scalable, auditable via SyncJob tracking

OTA Adapter Pattern

Design: Factory + Strategy

• OtaAdapterFactory.create(otaType) returns adapter instance
• Each adapter implements IOtaAdapter interface: fetchBookings(), pushAvailability()
• Pluggable: Easy to add new OTA channels (Vrbo, Airbnb, etc.)

Authentication Flow

JWT + Refresh Token Model

• Access token (15m) in HttpOnly cookie for API calls
• Refresh token (7d) in HttpOnly cookie, DB-backed for revocation
• Token refresh on 401 via next-auth pattern
• Logout revokes refresh token immediately

Country Scoping

Guardian: CountryScopeGuard applies WHERE clause automatically

• Staff accounts: Locked to single country (user.country)
• Manager accounts: Can filter by ?country=VN parameter
• All list queries automatically scoped
• Foreign key constraints prevent cross-country access

---

8. Data Model Overview

39 PostgreSQL Tables:

• Auth (6): users, roles, refresh_tokens, password_reset_tokens, countries, activity_logs
• Inventory (4): properties, room_types, suppliers, supplier_room_allocations
• OTA (4): ota_accounts, ota_connections, ota_room_mappings, sync_jobs
• Bookings & CRM (6): bookings, booking_status_def, booking_status_transition, availability, customers, ota_status_def
• BPM (2): process_types, process_instances
• Rates (7): rates, rate_rules, rate_plans, rate_plan_adjustments, ota_formula_templates, ota_rate_configs, ota_rate_lines
• Operations (4): alerts, audit_logs, settings, property_formula_configs

Key Constraints:

• Unique: users(email), refresh_tokens(jti), ota_accounts(account_name)
• Foreign keys: properties(country_id), bookings(room_type_id), ota_connections(property_id, ota_account_id)
• Indexes: idx_bookings_ota_id (dedup), idx_availability_overbooked (alert detection)

---

9. Development Roadmap

Completed (v2.6.0)

• [x] JWT authentication with refresh tokens
• [x] Role-based access control (6 preset roles)
• [x] Country-scoped data isolation
• [x] OTA adapter framework (4 adapters)
• [x] Automated booking sync pipeline
• [x] Availability calculation & overbooking alerts
• [x] Availability calendar with date-range blocking & multi-room selection
• [x] Dashboard KPI metrics
• [x] Booking timeline & audit history
• [x] User & role management
• [x] Encrypted OTA credential storage
• [x] Rate limiting & security hardening
• [x] Rate management — OTA formula-based rate engine, rate rules, rate plans
• [x] Bulk rate operations across properties/room types
• [x] BPM workflow engine (process types, instances, transitions)
• [x] Customer CRM module (guest profiles, booking consolidation, merge)
• [x] Price calendar with per-OTA rate visualization

In Progress / Planned

• [ ] Webhook Support — Receive real-time booking events from OTA partners instead of polling
• [ ] Mobile App — React Native companion for field staff notifications
• [ ] Advanced Analytics — Revenue forecasting, occupancy trends, competitor rate analysis
• [ ] 2FA Support — TOTP/SMS two-factor authentication for user accounts
• [ ] API Keys — Enable external integrations (PMS, channel manager, revenue mgmt)
• [ ] Airbnb/Vrbo Adapters — Extend to additional OTA platforms
• [ ] Notification Channels — Slack, LINE, Telegram integrations beyond email
• [ ] Multi-Language — Expand i18n beyond English/Vietnamese

---

10. Success Metrics

Business Metrics

Metric	Baseline	Target (6 months)	Current
Overbooking incidents	50/month	<5/month	Tracking
Manual sync time	4 hours/day	0 hours	95% reduced
Property coverage	0%	100% (100+ properties)	85%
Staff adoption	0%	90%	70%
System availability	N/A	99.5%	99.8%

Technical Metrics

Metric	Target	Status
Test coverage (services)	80%	In progress
Deployment frequency	Weekly	Active
Incident response time	<15 min	<10 min
Database backup frequency	Daily	Automated

---

11. Risk Assessment

Risk	Impact	Likelihood	Mitigation
OTA API changes break integration	High	Medium	Adapter versioning, backward compatibility tests
Credential exposure (AES-256 key leak)	Critical	Low	Rotate encryption key annually, audit logs
Database overload (high booking volume)	High	Low	Connection pooling, query optimization, read replicas
Staff misuse of country-scope bypass	Medium	Low	Role separation, activity logging, audit review
Redis failure (queue loss)	Medium	Low	AOF persistence, monitoring alerts

---

12. Constraints & Dependencies

External Dependencies

• Booking.com API - Availability, rate stability critical for sync
• Agoda Extranet - Parsing stability for web scraping fallback
• PostgreSQL 16 - ACID guarantees required for booking consistency
• Redis 7 - Queue persistence for async job tracking

Internal Dependencies

• packages/database (Prisma schema) must be in sync with all services
• packages/types (enums) shared across frontend and backend
• OTA adapter implementations must conform to IOtaAdapter interface

Constraints

• Max 150s polling interval (OTA API rate limits)
• Encryption key must be ≥256 bits (AES-256)
• JWT tokens must expire: access=15m, refresh=7d
• Country scope limited to: VN, ID, MY (extensible)

---

13. Success Criteria & Acceptance

MVP Acceptance (v1.0.0 - COMPLETE)

• [x] Users can login with email/password
• [x] Properties can connect to OTA accounts securely
• [x] Bookings auto-sync every 2-3 minutes
• [x] Availability recalculates in real-time
• [x] Overbooking alerts trigger when inventory exceeds capacity
• [x] Staff see only their assigned country
• [x] Managers can switch between countries

Production Readiness (v2.0.0 - COMPLETE)

• [x] All endpoints secured behind JWT auth
• [x] Country-scoped queries prevent data leakage
• [x] OTA credentials encrypted with AES-256-GCM
• [x] Rate limiting prevents brute-force attacks
• [x] Activity logs audit all user actions
• [x] 99.5% uptime in staging environment
• [x] Database backups automated daily
• [x] Security audit completed

Future Release Criteria

• Rate management module with seasonal rules
• Webhook support for real-time OTA events
• Mobile app for on-the-go notifications
• Advanced analytics dashboard

---

14. Related Documentation

• system-architecture.md - Architecture diagrams, module dependencies, auth flows
• code-standards.md - Coding patterns, naming conventions, security guidelines
• codebase-summary.md - Project structure, file counts, tech stack
• API_SPEC.md - REST endpoint reference
• DB_DESIGN.md - Database schema, ER diagram, indexes
• UI_SPEC.md - Design system, component library, screen mockups
• development-roadmap.md - Feature status, milestones, progress tracking

---

Last Updated: 2026-03-15 | Maintained By: Development Team