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

> Discover the TREK backend stack featuring NestJS Nodejs and real-time architecture Explore its database authentication and WebSocket gateway implementation

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

---

**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](https://github.com/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](https://github.com/mauriceboe/TREK/blob/main/README.md#L96)) and is built with **NestJS 11** ([source](https://github.com/mauriceboe/TREK/blob/main/README.md#L97)), a progressive Node.js framework that uses TypeScript ([source](https://github.com/mauriceboe/TREK/blob/main/README.md#L101)) and dependency injection. The entry point [`src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/package.json).

## Database Layer

Data persistence uses **SQLite** ([source](https://github.com/mauriceboe/TREK/blob/main/README.md#L98)), 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](https://github.com/mauriceboe/TREK/blob/main/README.md#L107)) to enable real-time synchronization. The gateway, implemented in [`src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/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](https://github.com/mauriceboe/TREK/blob/main/README.md#L110)):

- **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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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](https://github.com/mauriceboe/TREK/blob/main/README.md#L104)). 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

```bash
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

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

```

### Create a JWT Token (Illustrative)

```ts
import { sign } from 'jsonwebtoken';

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

```

### WebSocket Client Connection

```ts
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`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts) | NestJS bootstrap and server initialization | [View](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts) |
| [`server/src/app.module.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/app.module.ts) | Root module configuration | [View](https://github.com/mauriceboe/TREK/blob/main/server/src/app.module.ts) |
| [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) | WebSocket gateway for real-time updates | [View](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) |
| [`server/src/auth/jwt.strategy.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/auth/jwt.strategy.ts) | JWT validation and authentication logic | [View](https://github.com/mauriceboe/TREK/blob/main/server/src/auth/jwt.strategy.ts) |
| [`server/src/mcp/tools.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/mcp/tools.ts) | MCP AI tooling endpoints | [View](https://github.com/mauriceboe/TREK/blob/main/server/src/mcp/tools.ts) |
| [`server/package.json`](https://github.com/mauriceboe/TREK/blob/main/server/package.json) | Backend dependencies and scripts | [View](https://github.com/mauriceboe/TREK/blob/main/server/package.json) |
| `Dockerfile` | Container build instructions | [View](https://github.com/mauriceboe/TREK/blob/main/Dockerfile) |
| [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) | Production compose configuration | [View](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) |

## 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](https://github.com/mauriceboe/TREK/blob/main/README.md#L98)), 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](https://github.com/mauriceboe/TREK/blob/main/README.md#L107)) 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](https://github.com/mauriceboe/TREK/blob/main/README.md#L110)), 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](https://github.com/mauriceboe/TREK/blob/main/README.md#L104)), you can run the server directly using Node.js 22 by installing dependencies from [`server/package.json`](https://github.com/mauriceboe/TREK/blob/main/server/package.json) and executing `npm run start:dev`.