API Server

Architecture Overview

The API server is the data backbone of the Travel Tamers platform. It manages the primary tt_fresh_db PostgreSQL database (52 tables) and exposes REST endpoints for all CRUD operations across contacts, companies, deals, bookings, trips, payments, analytics, and more.

The server follows a layered architecture: Hono routes handle HTTP, Zod schemas validate all inputs, Drizzle ORM provides type-safe database queries, and custom error classes ensure consistent JSON error responses. External service integrations (Slack, Gmail, Claude AI, Buffer, Unsplash) are all optional and gracefully degrade to console logging when API keys are absent.

Key Principle: All external services are optional in development. When API keys are not configured, the server logs what it would have done instead of failing. This means you can run the full API locally with just a PostgreSQL connection.

• Internal service auth — new /api/internal/contacts and /api/internal/deals endpoints use x-internal-service header with timing-safe comparison instead of JWT. Replaces the broken Bearer token auth from TT-API to Nexus.
• All 48 as any casts eliminated — across 21 API files. New isValidEnum() helper in src/utils/type-helpers.ts, Drizzle insert/update patterns use $inferInsert types, enum checks use proper type narrowing.
• Webhook form-submit updated — /webhooks/form-submit now receives honeypot field and a different payload shape (name instead of firstName+lastName). Both /webhooks/form-submit and /webhooks/page-view are now PUBLIC (skip requireServiceKey via PUBLIC_WEBHOOK_PATHS).
• Nexus sync rewritten — nexus/client.ts uses x-internal-service header instead of Bearer token. nexus/sync.ts calls /api/internal/contacts and /api/internal/deals.

• Hono upgraded to 4.12.7 — 5 CVEs patched (serveStatic path traversal, setCookie injection, and others).
• Webhook Zod validation — all 4 webhook endpoints (/webhooks/booking-update, /payment, /page-view, /miles-intent) now validate payloads with Zod schemas and return 400 on invalid input.
• Booking payment Zod — POST /bookings/:id/payments validates with createBookingPaymentSchema.
• Commission /calculate Zod — POST /commissions/calculate validates with calculateCommissionSchema (requires bookingId, vendorId, bookingValueCents).
• Commission pagination — GET /commissions now supports page/limit query params with pagination metadata in response.
• Dockerfile production fix — CMD uses node dist/index.js instead of tsx src/index.ts for faster startup and lower memory.
• Health check hardened — /health now verifies DB connectivity (SELECT 1) and Redis ping, returns 503 on failure.
• Error middleware — stack traces stripped in production, only shown in development mode.

Request Flow

Request enters through Traefik

Traefik handles SSL termination and routes api.traveltamers.com to the Hono container on port 3100.

Middleware pipeline runs

Request ID, CORS, request logging, and global rate limiting are applied to every request.

Authentication checked

Routes under /api/* require a valid API key. Public routes (miles-chat, page-views, onboarding) skip auth.

Input validated with Zod

Request body and query parameters are parsed through Zod schemas. Invalid input returns 400 with details.

Database query via Drizzle

Type-safe queries are built with Drizzle ORM, supporting pagination, filtering, search, and soft deletes.

Tech Stack

Directory Structure

integrations/
├── src/
│   ├── index.ts              # Entry point: app setup, middleware, route mounting
│   ├── api/                  # 32 Hono route modules
│   │   ├── companies.ts
│   │   ├── contacts.ts
│   │   ├── deals.ts
│   │   ├── bookings.ts
│   │   ├── miles-chat.ts
│   │   └── ... (28 more)
│   ├── db/
│   │   ├── client.ts         # PostgreSQL connection (pg + drizzle)
│   │   ├── redis.ts          # Redis connection (ioredis)
│   │   ├── seed.ts           # Database seed script
│   │   └── schema/           # 12 Drizzle schema modules
│   │       ├── index.ts      # Re-exports all schemas
│   │       ├── enums.ts      # 27 pgEnum definitions
│   │       ├── companies.ts  # companies, contacts, deals, interactions
│   │       ├── bookings.ts   # bookings, travelers, documents, preferences
│   │       ├── trips.ts      # destinations, offerings, itineraries, client trips
│   │       ├── clients.ts    # clients, family groups, loyalty programs
│   │       ├── vendors.ts    # vendors, commission rules/entries
│   │       ├── financial.ts  # payments, invoices, schedules, touchpoints
│   │       ├── analytics.ts  # events, KPIs, automation runs, tasks
│   │       ├── marketing.ts  # proposals, emails, social media, assets
│   │       ├── groups.ts     # groups, members, milestones
│   │       └── content-management.ts
│   ├── middleware/
│   │   ├── auth.ts           # API key + service key auth
│   │   ├── rate-limit.ts     # Redis + in-memory rate limiting
│   │   ├── idempotency.ts    # Webhook deduplication
│   │   ├── request-id.ts     # Unique request ID header
│   │   └── slack-signature.ts # Slack HMAC-SHA256 verification
│   ├── utils/
│   │   ├── errors.ts         # Custom error classes
│   │   ├── logger.ts         # Structured logger
│   │   ├── validation.ts     # Shared Zod schemas
│   │   ├── type-helpers.ts   # isValidEnum() helper, type narrowing utilities (R11)
│   │   ├── cache.ts          # Redis cache helpers
│   │   ├── date.ts           # Date utilities
│   │   └── env.ts            # Environment helpers
│   ├── nexus/
│   │   ├── client.ts         # Nexus HTTP client (x-internal-service header, R11)
│   │   └── sync.ts           # Sync contacts/deals to Nexus via /api/internal/* (R11)
│   ├── webhooks/             # Webhook handler implementations
│   ├── slack/                # Slack command handlers
│   ├── email/                # Email sending utilities
│   ├── ai/                   # AI provider integrations
│   └── tasks/                # Background task runner
├── drizzle.config.ts
├── tsconfig.json
└── package.json

Database Schema

The tt_fresh_db database contains 52 tables organized into domain modules. All tables use UUIDs for primary keys, soft deletes via a deletedAt timestamp, and store monetary values in cents (integer) to avoid floating-point precision issues.

CRM & Sales

Clients & Travelers

Trips & Bookings

Financial

Groups & Marketing

Analytics & Operations

Enum Types

The schema uses PostgreSQL pgEnum types for constrained fields. These enforce valid values at the database level and provide TypeScript type safety through Drizzle.

Authenticated API Routes

All routes under /api/* require a valid API key (via X-API-Key header or Authorization: Bearer). Each route module follows a standard CRUD pattern with pagination, search, UUID validation on :id parameters, and Zod validation on request bodies.

Public & Internal Routes

Some routes are public-facing (no API key required) and others are reserved for internal service-to-service communication.

Public Routes (No Auth)

Internal Service Routes

Idempotency: All /webhooks/* routes enforce idempotency via the X-Idempotency-Key header or an auto-generated SHA-256 hash of the request path + body. Duplicate deliveries within 24 hours return 409 Conflict. This prevents double-processing when n8n or external services retry webhook calls.

Authentication

The API uses a multi-layer authentication system depending on the route type. All secret comparisons use timing-safe equality checks to prevent timing attacks.

API Key Authentication

Routes under /api/* require a valid key sent via X-API-Key header or Authorization: Bearer <key>. Valid keys are configured in the API_KEYS environment variable (comma-separated list).

# Example request
curl -H "X-API-Key: your-key-here" \
  https://api.traveltamers.com/api/companies

Authentication Modes

Dev Mode: When API_KEYS is not set and NODE_ENV is not production, the auth middleware logs a warning but allows requests through. In production, missing keys always return 401 Unauthorized.

Rate Limiting

Rate limiting uses Redis INCR + EXPIRE for distributed counting across server instances. When Redis is unavailable, an in-memory Map provides fallback protection. Every response includes rate limit headers.

Response Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1710280320
Retry-After: 45        # Only when 429 is returned

Input Validation

Every endpoint validates inputs using Zod schemas. Query parameters, path parameters (UUID format), and request bodies are all parsed through Zod before reaching handler logic. Invalid input throws a ValidationError which returns a 400 response with details.

Shared Validation Schemas

Common schemas in src/utils/validation.ts are reused across all route modules:

Pattern: Each route module imports shared schemas and may extend them with domain-specific fields. The sortBy parameter uses an allowlist of valid column names to prevent SQL injection through sort field manipulation.

Type Safety (R11)

All 48 as any type casts have been eliminated across 21 API files. The codebase now uses proper TypeScript patterns throughout:

Error Handling

The API uses a hierarchy of custom error classes that extend AppError. The global error handler in app.onError() catches all exceptions and returns consistent JSON responses. Unhandled errors are reported to Sentry in production.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "path": ["email"], "message": "Invalid email format" }
    ],
    "requestId": "req_abc123"
  }
}

Production Sanitization: In production, ValidationError details are stripped to avoid leaking schema information. Server errors (500+) return a generic message instead of the actual error. Stack traces are completely stripped in production and only included in development mode. Full details are always logged server-side and sent to Sentry.

Middleware Stack

Middleware runs in declaration order. The stack is designed so that request tracking and security layers run first, before any route-specific logic.

Request ID

Generates or forwards a unique X-Request-Id header for request tracing across services.

CORS

Configurable via CORS_ORIGINS env var. Allows GET, POST, PATCH, DELETE. Exposes X-Request-Id. Max age 3600s.

Request Logging

Logs method, path, status, and duration for every request at DEBUG level.

Global Rate Limit

100 req/min per IP baseline on all routes. Uses Redis with in-memory fallback.

Route-Specific Middleware

Additional rate limits, authentication (requireAuth / requireServiceKey), idempotency, and Slack signature verification.

Development

Commands

# From the integrations/ directory:

npm run dev          # tsx watch src/index.ts (hot-reload on file changes)
npm run build        # tsc (compile TypeScript to dist/)
npm run start        # node dist/index.js (run compiled output)
npm run test         # vitest run (execute test suite)
npm run test:watch   # vitest (watch mode)
npm run lint         # eslint src/
npm run typecheck    # tsc --noEmit (type checking without emit)

Database Commands

npm run db:push      # Apply schema directly to database (dev)
npm run db:generate  # Generate migration files from schema changes
npm run db:migrate   # Run pending migrations
npm run db:seed      # Seed the database with sample data
npm run db:studio    # Open Drizzle Studio (visual DB browser)

Environment Variables

Key Files

Deployment

The API server runs as a Docker container (tt-api) behind the Traefik reverse proxy. Deployment is automated through GitHub Actions with rollback support.

Deployment Pipeline

GitHub Actions triggered

Push to main branch or manual dispatch starts the deploy workflow.

TypeScript build + tests

npm run typecheck, npm run lint, npm run test, then npm run build compiles to dist/.

Archive transferred to VPS

Built code is sent to the VPS via git archive or tar over SSH.

Docker container rebuilt

The tt-api container is rebuilt and restarted using docker-compose.production.yml.

Health check verification

A request to /health verifies database and Redis connectivity. On failure, the previous container image is restored.

Production Infrastructure

# Docker container: tt-api
# Host: api.traveltamers.com
# Port: 3100 (internal)
# Database: tt_fresh_db (PostgreSQL 16)
# Cache: Redis 7 (shared with other services)
#
# Traefik handles:
#   - SSL termination (Let's Encrypt)
#   - HTTP → HTTPS redirect
#   - Routing api.traveltamers.com → tt-api:3100
#
# Health monitoring:
#   - /health endpoint checked every 5 minutes
#   - Failures reported to Slack #monitoring channel

Graceful Shutdown

The server listens for SIGINT and SIGTERM signals. On shutdown, it stops the background task runner, closes the Redis connection, closes the PostgreSQL connection pool, and then exits. This ensures in-flight requests complete and connections are properly released.

Rollback Safety: Each deployment tags the current Docker image before rebuilding. If the health check fails, the deploy script automatically rolls back to the previous image. The previous dist/ directory is also preserved as dist-old/ for manual recovery.

Production Dockerfile: The production image uses a multi-stage build (Node 20 Alpine). The final CMD runs node dist/index.js (compiled JavaScript) instead of tsx src/index.ts for faster startup and lower memory usage. Source files are still included for migrations and seeding via tsx. The container runs as the node user (non-root) with a built-in HEALTHCHECK every 30 seconds.