What Is the Backend Stack for TREK? NestJS, Node.js & Real-Time Architecture Explained

The TREK backend is built as a NestJS 11 application running on Node.js 22, using SQLite for file-based data persistence, WebSocket gateways for real-time collaboration, and supporting JWT, OIDC, Passkeys, and TOTP 2FA for authentication.

TREK is a self-hosted travel planning platform with a modular, TypeScript-first server architecture. According to the mauriceboe/TREK repository, the backend implementation relies on the NestJS framework to provide a structured API layer with real-time capabilities. This article breaks down the complete server-side stack, from the Node.js runtime and SQLite database to the WebSocket gateways and Docker deployment strategy.

Core Runtime and Framework

The backend executes on Node.js 22 (source) and is built with NestJS 11 (source), a progressive Node.js framework that uses TypeScript (source) and dependency injection. The entry point src/main.ts bootstraps the application, applies global pipes, configures CORS, and mounts the WebSocket server.

Application Structure

The root module in src/app.module.ts imports feature modules including Auth, Trips, Reservations, and MCP (AI tooling). Each module follows NestJS conventions with controllers, services, and providers. The server code is located in the server/ directory, with package definitions in server/package.json.

Database Layer

Data persistence uses SQLite (source), a file-based relational database. The database file resides at data/travel.db and is automatically migrated on startup. This architecture eliminates the need for external database servers, simplifying self-hosting deployments.

Real-Time Communication

The backend implements a WebSocket gateway (source) to enable real-time synchronization. The gateway, implemented in src/websocket.ts, broadcasts changes to all connected clients, supporting instant collaboration on trips, notes, packing lists, and itinerary updates.

Authentication and Security

The repository supports multiple authentication strategies as detailed in the README (source):

• JWT – Stateless token-based sessions
• OIDC – OpenID Connect for external identity providers
• Passkeys – WebAuthn-based passwordless authentication
• TOTP – Time-based One-Time Password for two-factor authentication

The JWT validation logic resides in src/auth/jwt.strategy.ts, used by JwtAuthGuard to protect API routes.

Machine-Client Protocol (MCP)

An internal OAuth 2.1 server exposes AI-driven tooling through the MCP module. The implementation in src/mcp/tools.ts provides programmatic endpoints for AI agents to interact with travel data.

Deployment and Containerization

The backend is containerized with Docker (source). The official image mauriceboe/trek exposes port 3000 and runs in a read-only configuration, mounting only the data/ and uploads/ directories for persistence.

Code Examples

Start the Server with Docker

ENCRYPTION_KEY=$(openssl rand -hex 32) \
docker run -d -p 3000:3000 \
  -e ENCRYPTION_KEY=$ENCRYPTION_KEY \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  mauriceboe/trek

Initialize NestJS in Development Mode

docker exec -it trek /bin/sh
npm install
npm run start:dev

Create a JWT Token (Illustrative)

import { sign } from 'jsonwebtoken';

const token = sign(
  { sub: userId, role: 'admin' },
  process.env.JWT_SECRET!,
  { expiresIn: '30d' }
);

WebSocket Client Connection

import { io } from 'socket.io-client';

const socket = io('http://localhost:3000', { path: '/ws' });
socket.on('trip:update', (payload) => {
  console.log('Trip changed:', payload);
});

Key Files

File	Purpose	Link
server/src/main.ts	NestJS bootstrap and server initialization	View
server/src/app.module.ts	Root module configuration	View
server/src/websocket.ts	WebSocket gateway for real-time updates	View
server/src/auth/jwt.strategy.ts	JWT validation and authentication logic	View
server/src/mcp/tools.ts	MCP AI tooling endpoints	View
server/package.json	Backend dependencies and scripts	View
Dockerfile	Container build instructions	View
docker-compose.yml	Production compose configuration	View

Summary

• NestJS 11 on Node.js 22 provides the API framework, written entirely in TypeScript.
• SQLite handles file-based data storage without requiring external database infrastructure.
• WebSocket enables real-time, bidirectional communication for collaborative features.
• Authentication supports JWT, OIDC, Passkeys, and TOTP for flexible security.
• Docker containerization with read-only filesystem semantics ensures portable, secure deployments.

Frequently Asked Questions

What database does TREK use?

TREK uses SQLite (source), storing all data in a local file (data/travel.db). This design choice eliminates the need for a separate database server and simplifies self-hosting.

How does TREK handle real-time collaboration?

The backend implements a WebSocket gateway (source) that broadcasts state changes to all connected clients, enabling instant synchronization of trips, notes, and packing lists across devices.

What authentication methods are supported?

According to the source code documentation (source), the backend supports JWT tokens, OIDC (OpenID Connect), Passkeys (WebAuthn), and TOTP two-factor authentication.

Can I run the TREK backend without Docker?

While Docker is the recommended deployment method (source), you can run the server directly using Node.js 22 by installing dependencies from server/package.json and executing npm run start:dev.

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