Code Standards & Guidelines

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

---

1. Project Principles

YAGNI - You Aren't Gonna Need It Don't build features before they're required. Avoid over-engineering.

KISS - Keep It Simple, Stupid Prefer straightforward solutions over clever abstractions.

DRY - Don't Repeat Yourself Extract common logic into helpers, services, or utilities.

---

2. Naming Conventions

Files & Directories

Context	Pattern	Example
TypeScript/JavaScript	kebab-case	country-scope.guard.ts, api-client.ts
Directories	kebab-case	ota-accounts/, room-mappings/
Test files	name.spec.ts	auth.service.spec.ts
DTOs	PascalCase + Dto suffix	CreatePropertyDto, ListBookingsDto
Interfaces	PascalCase + optional I prefix	OtaAdapter or IOtaAdapter
Classes	PascalCase	AuthService, PropertyController
Enums	PascalCase	UserRole, AlertSeverity
Constants	UPPER_SNAKE_CASE	ALLOWED_COUNTRIES, JWT_EXPIRY
Database tables	snake_case (Prisma)	ota_accounts, refresh_tokens
Database columns	snake_case	password_hash, is_active

Functions & Methods

// ✓ Good: Verb + noun, descriptive
async fetchBookingsFromOta(otaType: string): Promise<Booking[]>
function assertPropertyAccess(prisma, propertyId, countryScope?): Property
function validateSortByField(field: string, allowedFields: string[]): void

// ✗ Bad: Abbreviations, unclear purpose
async getB(type: string): Promise<any>
function checkProp(id: string): void

Variables

// ✓ Good: Descriptive, no unnecessary abbreviations
const refreshTokenExpiry = '7d';
const MAX_RETRY_ATTEMPTS = 3;
let availableRooms = totalRooms - bookedRooms;

// ✗ Bad: Single letter, abbreviations
const rt = '7d';
const max_retries = 3;
let avail = total - booked;

---

3. File Organization & Size Limits

Code Files: Max 200 Lines

Goal: Keep files focused and easy to navigate.

Split Strategy:

• 200-400 lines: Consider splitting into 2-3 focused files
• 400+ lines: MUST split immediately

Example split for a large service:

ota-accounts/
├── ota-accounts.service.ts         # CRUD (150 lines)
├── ota-accounts.controller.ts      # Endpoints
├── ota-account-discovery.service.ts # Discovery & import logic (120 lines)
├── ota-credential.helper.ts        # Encryption/decryption (80 lines)
├── dto/
│   ├── create-ota-account.dto.ts
│   └── list-ota-accounts.dto.ts
└── ota-accounts.module.ts

Documentation Files: Max 800 Lines

Goal: Keep docs maintainable and readable.

Split Strategy:

• 800-1200 lines: Create topic directory with index + parts
• 1200+ lines: MUST split

---

4. Related Documentation

Document	Contents
code-standards-backend.md	NestJS patterns, security, error handling, DB/Prisma, testing
code-standards-frontend.md	Next.js/React patterns, API client, Git commits, performance
system-architecture.md	Architecture diagrams and flows
codebase-summary.md	Project structure and dependencies
API_SPEC.md	REST API endpoint reference
DB_DESIGN.md	Database schema and indexes