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

> Understand the TREK server structure: NestJS, SQLite, WebSockets, and OAuth 2.1 MCP server. Deploy easily with Docker for real-time collaboration and AI assistants.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: architecture
- Published: 2026-06-27

---

**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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/src/main.ts))

The entry point at [`src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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:

```bash

# 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`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) implements security hardening with read-only containers, dropped capabilities, and tmpfs mounts:

```yaml
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:

```bash
docker compose up -d

```

### Reverse Proxy Configuration

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

```nginx
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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/src/ws.gateway.ts) enabling real-time collaboration features
- **Docker-first deployment** with security-hardened [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/src/main.ts) for the application bootstrap and [`src/app.module.ts`](https://github.com/mauriceboe/TREK/blob/main/src/app.module.ts) for module organization. Deployment-specific documentation appears in the `Dockerfile`, [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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.