# TREK Backend Stack: NestJS, Node.js 22, SQLite, and Real-Time WebSockets Explained

> Explore the TREK backend stack: NestJS, Node.js 22, SQLite, and WebSockets for real-time sync. Learn about its Dockerized architecture and authentication options.

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

---

**The TREK backend stack runs on Node.js 22 and NestJS 11, persists data to SQLite, and uses WebSocket gateways for real-time synchronization, all packaged in a Docker container with support for JWT, OIDC, and passkey authentication.**

The TREK travel planning application by mauriceboe demonstrates a modern, self-hosted architecture that requires no external database server. Understanding the backend stack for TREK reveals how it combines the NestJS framework with file-based storage and advanced authentication protocols to deliver a lightweight yet feature-rich server suitable for personal or small-team deployments.

## Core Backend Technologies

### Node.js 22 and NestJS 11 Framework

The server executes on **Node.js 22** as indicated by the repository badge, providing the latest JavaScript features and long-term support security patches. The application framework is **NestJS 11**, a progressive Node.js framework for building efficient, scalable server-side applications. According to the source code, the entry point in [`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts) creates the Nest application instance, applies global pipes and CORS configuration, and initializes both the HTTP and WebSocket servers.

### SQLite Database Architecture

Rather than requiring a separate database container, TREK uses **SQLite** for zero-configuration persistence. The database file resides at `data/travel.db` within the container, mounted as a Docker volume for durability between restarts. This architecture choice eliminates the need for PostgreSQL or MySQL setup while maintaining ACID compliance for all travel data, reservations, and user profiles.

### TypeScript Implementation

The entire backend is written in **TypeScript**, ensuring type safety across API contracts and database queries. The [`server/package.json`](https://github.com/mauriceboe/TREK/blob/main/server/package.json) defines the TypeScript compiler configuration, build scripts, and dependency manifest that includes NestJS core libraries, validation pipes, and cryptography packages necessary for production deployment.

## Real-Time Communication and API Design

### WebSocket Gateway Implementation

TREK implements real-time collaboration through a **WebSocket gateway** defined in [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts). This gateway maintains persistent connections with clients and broadcasts trip updates, packing list modifications, and reservation changes to all connected browsers instantly. The WebSocket server mounts on the same port as the HTTP API but handles bidirectional event streaming for live collaboration features.

### REST API Structure

Standard REST endpoints follow NestJS controller conventions, organizing routes into domain modules including **Auth**, **Trips**, **Reservations**, **MCP** (AI tooling), and **Admin**. Each module encapsulates its controllers, services, and providers following the modular architecture pattern implemented in [`server/src/app.module.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/app.module.ts).

## Authentication and Security Architecture

### JWT and OIDC Integration

The backend supports multiple authentication mechanisms. **JSON Web Tokens (JWT)** handle session state after initial authentication, with validation logic implemented in [`server/src/auth/jwt.strategy.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/auth/jwt.strategy.ts). **OpenID Connect (OIDC)** enables integration with external identity providers such as Google or Azure AD through environment variables like `OIDC_ISSUER` and `OIDC_CLIENT_ID`.

### Passkeys and TOTP Support

Beyond traditional passwords, the stack supports modern **WebAuthn passkeys** for passwordless authentication and **Time-based One-Time Password (TOTP)** for two-factor authentication. These methods are enforced through guards applied to sensitive routes in the Trips and Admin modules.

## Deployment and Containerization

### Docker Configuration

The production deployment uses a Docker container built from the official image `mauriceboe/trek`. The `Dockerfile` compiles the TypeScript source and configures the container to expose port 3000. The container runs with a read-only filesystem for security, with only the `data/` and `uploads/` directories mounted as writable volumes for persistence.

### Volume Mounts and Persistence

Critical environment variables include `ENCRYPTION_KEY` for database field encryption and `JWT_SECRET` for token signing. The Docker Compose configuration mounts host directories to container paths, ensuring the SQLite database and file uploads survive container updates and restarts.

## Key Source Files and Module Organization

Understanding the repository structure helps developers extend the backend:

- [`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts) – Application bootstrap and server initialization
- [`server/src/app.module.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/app.module.ts) – Root module importing feature modules (Auth, Trips, MCP, etc.)
- [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) – WebSocket gateway implementation for real-time updates
- [`server/src/auth/jwt.strategy.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/auth/jwt.strategy.ts) – JWT validation strategy and token extraction logic
- [`server/src/mcp/tools.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/mcp/tools.ts) – Machine-Client Protocol endpoints for AI tooling integration
- [`server/package.json`](https://github.com/mauriceboe/TREK/blob/main/server/package.json) – Dependency manifest and build scripts
- `Dockerfile` – Container image definition and build steps

## Summary

- **TREK** runs on **Node.js 22** with the **NestJS 11** framework, compiled from TypeScript source for type-safe API development
- Data persists to a **SQLite** database file requiring no external database server, stored in a mounted Docker volume
- Real-time features rely on **WebSocket** gateways broadcasting updates to connected clients for instant collaboration
- Authentication supports **JWT**, **OIDC**, **WebAuthn passkeys**, and **TOTP 2FA** for flexible security options
- Deployment occurs via **Docker** with read-only filesystems and mounted volumes for data persistence

## Frequently Asked Questions

### What database does TREK use for the backend?

TREK uses **SQLite** for all data persistence, storing the database file at `data/travel.db` inside the container. This design eliminates the need for a separate PostgreSQL or MySQL server, simplifying self-hosting deployments while maintaining transactional integrity through SQLite's ACID-compliant engine.

### How does TREK handle real-time collaboration between users?

The backend implements a **WebSocket gateway** in [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) that maintains persistent TCP connections with browsers. When a user modifies a trip itinerary or packing list, the NestJS gateway broadcasts the event to all connected clients, ensuring immediate synchronization across all active sessions without requiring polling.

### What authentication methods are supported by the TREK backend?

The stack supports **JWT-based sessions** for API security, **OpenID Connect (OIDC)** for SSO integration with providers like Google, **WebAuthn passkeys** for modern passwordless authentication, and **TOTP** for two-factor authentication. These methods are configured via environment variables and enforced through NestJS guards on protected routes.

### Can TREK run without Docker?

While Docker is the recommended deployment method, you can run the backend directly by installing **Node.js 22**, executing `npm install` in the `server` directory, and starting the application with `npm run start`. However, you must manually create the `data/` and `uploads/` directories and ensure the `ENCRYPTION_KEY` and `JWT_SECRET` environment variables are set before starting the server.