Codebase Summary

Project	PTX Channel Manager (ptx-cm)
Version	2.0.0
Last Updated	2026-02-20

---

1. Monorepo Dependency Graph

---

2. Directory Structure & Metrics

Directory	Purpose	LOC	Files
apps/api	NestJS Backend	~12,000	85 TS
apps/web	Next.js Frontend	~8,500	95 TSX
packages/database	Prisma + migrations	~600	8
packages/types	Shared types/enums	~400	4
packages/config	ESLint/TS configs	~100	3
docs	Documentation	~3,000	9 MD
Total	All source	~25,000	200+

---

3. Backend Module Map

15 Feature Modules (apps/api/src/modules)

Auth & Users:

• auth - JWT, login, refresh, password reset, rate limiting
• users - User CRUD, account settings (locale, country, dateFormat)
• roles - Role definitions, permission bitmasks (14 modules × 4 actions)
• activity-logs - HTTP request logging, audit trail via middleware

Inventory & Operations:

• properties - Property CRUD, timezone/currency assignment
• room-types - Room inventory, base rates per property
• room-mappings - OTA ↔ local room type mapping
• suppliers - Supplier/room-owner management
• supplier-room-allocations - M:N supplier ↔ room allocation

OTA Integration:

• ota-accounts - Encrypted credentials (AES-256-GCM)
• ota-connections - Property ↔ OTA account links
• ota-adapters - Factory + 4 adapters (Booking, Agoda, Traveloka, Expedia)

Bookings & Sync:

• bookings - Booking CRUD, upsertFromOta dedup
• booking-status - Configurable status definitions
• sync-engine - Polling scheduler, job tracking, OTA polling/availability sync processors
• sync-jobs - Async job tracking with status

Support:

• alerts - Overbooking detection & notifications
• dashboard - KPI metrics (occupancy, revenue, alerts, sync status)
• settings - App config (sync intervals, notification toggles)
• notifications - Email service (Resend API + Mailpit in dev)
• countries - Reference data for filtering
• health - Liveness probes

Common Patterns (apps/api/src/common)

Guards (applied globally, opt-out via @Public):

• JwtAuthGuard - JWT signature & expiry validation
• PermissionsGuard - Module:action bitmask verification
• CountryScopeGuard - Country filter injection from user context
• ThrottlerGuard - Rate limiting (5/min login, 10/min refresh)

Decorators:

• @Public() - Skip JwtAuthGuard
• @RequirePermission(module, action) - Bitwise permission check
• @CountryScope() - Inject countryScope from user.country

---

4. Frontend Route Map

Route	Layer	Auth	Purpose
/login, /forgot-password, /reset-password	(auth)	Public	Auth flows
/dashboard, /bookings, /properties, /ota-accounts, /alerts, /sync-jobs, /suppliers, /master-data, /logs, /profile, /settings	(main)	Required	Protected pages

Context Provider Chain

AuthProvider → CountryProvider → ReferenceDataProvider → ThemeProvider → I18nProvider → ActivityTrackerProvider

Key Components

• data-table.tsx - TanStack Table wrapper
• booking-history.tsx - Status timeline + metadata
• status-transition-dialog.tsx - State machine UI
• ota-connections-tab.tsx - Room mapping manager
• supplier-allocation-manager.tsx - Allocation editor
• workflow-mermaid-preview.tsx - Booking state visualization

---

5. Critical Files

File	Purpose
packages/database/prisma/schema.prisma	Source of truth for DB schema
packages/types/src/enums.ts	OTA types, role enums, status constants
docs/API_SPEC.md	Backend endpoint contracts
docs/DB_DESIGN.md	Database design rationale & ER

---

6. Cross References

For detailed technical information, see:

• System Architecture — Tech stack, design patterns, sync engine flow, auth/auth flows, ER diagram
• Database Design — Full schema with DDL, indexes, constraints

---

Last Updated: 2026-02-20 | Status: Active