TREK Server Structure Explained: Architecture, Components, and Deployment Guide

The TREK server structure is a self-hosted NestJS 11 application that uses SQLite for persistence, WebSocket gateways for real-time collaboration, and exposes an OAuth 2.1-protected MCP server for AI assistants, all deployable via Docker.

The TREK server structure is documented across the repository's configuration files and TypeScript source code in the mauriceboe/TREK repository. This architecture powers a real-time collaborative travel planner built on Node.js, combining a React 19 frontend with a modular backend that handles JWT authentication, file uploads, and AI tool integration.

Architectural Overview

TREK implements a modern Node.js stack centered on a NestJS 11 backend. The server persists travel data in an SQLite database, synchronizes users via WebSocket, and serves static assets through Express middleware. The repository ships with production-ready containerization, including a multi-stage Dockerfile and a security-hardened docker-compose.yml.

Core Server Components

The TREK server structure consists of distinct architectural layers, each with specific responsibilities and source file locations.

NestJS Backend (src/main.ts)

The entry point at src/main.ts bootstraps the NestJS application, applying global pipes and starting the HTTP server on the configured port. This layer handles REST API endpoints, authentication flows (JWT, OAuth 2.1, OIDC, WebAuthn, and TOTP), and serves the React frontend. The src/app.module.ts file serves as the central module, importing all feature modules including trip management, bookings, and the MCP integration.

SQLite Database (data/travel.db)

All travel data persists in travel.db stored in the data/ volume. This file-based approach eliminates external database dependencies while ensuring data survives container rebuilds through volume mounts. The database schema is managed through NestJS repositories defined in the source modules.

WebSocket Layer (src/ws.gateway.ts)

Real-time collaboration features—including chat, shared notes, polls, and day-by-day check-ins—flow through the WsGateway defined in src/ws.gateway.ts. This gateway upgrades HTTP connections at the /ws endpoint to persistent WebSocket connections, pushing live updates to all connected clients.

MCP AI Server (src/mcp/mcp.module.ts)

The Model Context Protocol (MCP) server exposes over 150 tools to AI assistants through an OAuth 2.1 protected endpoint. Implemented in src/mcp/mcp.module.ts, this component allows automated trip creation, packing-list generation, and budget management via AI agents.

Static Assets and Uploads (uploads/)

User-uploaded photos, PDFs, and documents are stored in the uploads/ volume, served directly by Express static middleware. This separation ensures uploaded content persists independently of container lifecycle.

How the TREK Server Components Work Together

The server architecture follows a specific initialization and request flow:

1. Startup: The container executes node dist/main.js, reading environment variables (PORT, ENCRYPTION_KEY, OIDC_*) to configure the NestJS application.
2. Authentication: Clients authenticate via JWT tokens, with optional OIDC SSO or WebAuthn passkeys, managed by the authentication controllers under src/*.
3. Real-time Sync: WebSocket connections at /ws enable bidirectional communication for collaborative features, requiring proper upgrade headers in the reverse proxy.
4. Data Persistence: All state changes write to the SQLite file in the mounted data/ directory, ensuring durability across deployments.
5. AI Integration: The MCP module accepts authenticated requests from AI assistants, executing travel-related tools against the same database used by the REST API.
6. Static Serving: Uploaded files in uploads/ are served directly without hitting the NestJS controllers, optimizing performance for large assets.

Deployment Configuration

Docker Quick Start

Run the TREK server structure locally with a single command, persisting data and uploads on the host:

# Generate required encryption key

ENCRYPTION_KEY=$(openssl rand -hex 32)

# Run container with volume mounts

docker run -d -p 3000:3000 \
  -e ENCRYPTION_KEY=$ENCRYPTION_KEY \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  mauriceboe/trek

On first boot, the server creates an admin account. If ADMIN_EMAIL and ADMIN_PASSWORD are omitted, the system generates a random password printed to the container logs accessible via docker logs <container>.

Production Docker Compose Setup

The docker-compose.yml implements security hardening with read-only containers, dropped capabilities, and tmpfs mounts:

services:
  app:
    image: mauriceboe/trek:latest
    container_name: trek
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    tmpfs:
      - /tmp:noexec,nosuid,size=64m
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - TZ=UTC
    volumes:
      - ./data:/app/data
      - ./uploads:/app/uploads
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/api/health"]

Deploy with:

docker compose up -d

Reverse Proxy Configuration

For WebSocket support behind Nginx, configure the /ws location with upgrade headers:

location /ws {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

The complete Nginx and Caddy configuration examples are documented in the repository's Reverse Proxy Wiki page.

Environment Variables and Configuration

The TREK server structure relies on centralized environment variables for configuration:

• ENCRYPTION_KEY: 32-byte hex string for database encryption (required)
• PORT: HTTP server port (default: 3000)
• OIDC_*: OpenID Connect configuration for SSO
• ADMIN_EMAIL / ADMIN_PASSWORD: Initial admin credentials
• NODE_ENV: Runtime environment (production/development)

These variables are processed at startup in src/main.ts and control everything from database encryption to authentication provider endpoints.

Summary

The TREK server structure combines a NestJS 11 backend with SQLite persistence and WebSocket real-time communication to power a self-hosted travel planner. Key architectural decisions include:

• File-based storage via SQLite in the data/ volume eliminates external database dependencies
• Modular NestJS architecture with clear separation between API, authentication, and MCP AI components
• WebSocket gateway at src/ws.gateway.ts enabling real-time collaboration features
• Docker-first deployment with security-hardened docker-compose.yml featuring read-only containers and capability dropping
• OAuth 2.1 protected MCP server exposing 150+ tools for AI assistant integration

Frequently Asked Questions

Where is the TREK server documentation located?

The primary documentation resides in the repository's README.md file, which covers the tech stack, quick-start instructions, and environment variable reference. Detailed architectural information is embedded in the TypeScript source files, particularly src/main.ts for the application bootstrap and src/app.module.ts for module organization. Deployment-specific documentation appears in the Dockerfile, docker-compose.yml, and the Reverse Proxy Wiki page.

What database does TREK use and where is it stored?

TREK uses SQLite as its database engine, storing all data in a single file named travel.db within the data/ directory. This file is created automatically on first run and must be persisted using a Docker volume mount (-v ./data:/app/data) to survive container restarts. The SQLite approach eliminates the need for external database servers while maintaining ACID compliance for travel data.

How does TREK handle real-time collaboration between users?

Real-time features are implemented through a WebSocket gateway defined in src/ws.gateway.ts. When clients connect to the /ws endpoint, the gateway upgrades the connection to WebSocket protocol and maintains persistent connections for broadcasting chat messages, shared notes, polls, and check-in updates. This requires proper reverse proxy configuration to handle the Upgrade and Connection headers for WebSocket support.

What is the MCP server in TREK and how is it secured?

The Model Context Protocol (MCP) server is an AI assistant integration exposed through src/mcp/mcp.module.ts. It provides over 150 tools that allow AI agents to create trips, generate packing lists, and manage budgets programmatically. The MCP endpoint is protected by OAuth 2.1, requiring valid authentication tokens before executing AI-triggered operations, ensuring that automated actions run with the same security context as human users.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}