# What Does the Main Entry Point File in TREK Server Do?

> Discover the function of the TREK server main entry point file. Learn how it initializes the backend, bootstraps NestJS, launches schedulers, and manages shutdowns.

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

---

**The [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) file serves as the primary startup script that initializes the TREK backend by preparing the environment, bootstrapping the NestJS application, launching background schedulers, and managing graceful shutdowns.**

The main entry point in the TREK repository orchestrates the complete lifecycle of the backend server. Located at [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts), this TypeScript file coordinates filesystem preparation, application bootstrapping, real-time WebSocket initialization, and signal-based shutdown procedures to ensure the application starts cleanly and exits safely.

## Environment and Filesystem Preparation

Before the HTTP server begins accepting connections, the entry point prepares the runtime environment. During the initial phase (lines 1‑8), it loads environment variables via `import 'dotenv/config'` and initializes the NestJS reflection API.

The script then creates necessary directories for file operations. Between lines 10‑16, it defines paths for `uploads`, `photos`, `files`, `covers`, `avatars`, `data/backups`, and `data/tmp`. A `forEach` loop (lines 18‑20) ensures these directories exist by calling `fs` methods, preventing runtime errors when the application attempts to store uploads or backups.

## NestJS Application Bootstrapping

The core application construction happens in the `bootstrap()` function (lines 94‑104). This async function imports `buildApp` from [`./bootstrap.ts`](https://github.com/mauriceboe/TREK/blob/main/./bootstrap.ts) (line 7), which configures the NestJS modules, middleware, and global pipes.

The entry point wraps the NestJS HTTP adapter in a native Node.js `http.Server` instance. This hybrid approach allows the application to leverage NestJS's dependency injection while maintaining direct access to the underlying server for WebSocket integration and graceful shutdown handling.

## Runtime Banner and Background Jobs

Once the server begins listening, the `onListen` function (lines 29‑88) executes. It renders a colorful startup banner to the console displaying critical runtime information: version number, port, host, `APP_URL`, environment name, timezone, allowed CORS origins, log level, process ID, and user IDs.

Simultaneously, the entry point initiates background maintenance tasks. It calls `scheduler.start*()` methods (lines 75‑83) to begin:

- Email reminder dispatch
- Version checking routines
- Demo environment resets
- Cache cleanup operations

Finally, it initializes the WebSocket layer by invoking `setupWebSocket` (lines 86‑88), enabling real-time collaboration features for the frontend.

## Graceful Shutdown Sequence

The entry point registers signal handlers for `SIGTERM` and `SIGINT` (lines 132‑133) to ensure zero-downtime deployments and safe exits. When triggered, the `shutdown()` function (lines 111‑130) executes a coordinated teardown sequence:

1. Logs the shutdown event using `logInfo` from the audit service
2. Stops all background schedulers to prevent orphaned jobs
3. Closes active MCP (Model Context Protocol) sessions
4. Shuts down the NestJS application and underlying HTTP server
5. Flushes the SQLite database buffers
6. Exits the process, with a forced timeout fallback if cleanup stalls

This systematic approach prevents data loss and ensures active requests complete before the process terminates.

## Practical Startup Examples

### Starting the Server Locally

To launch the TREK backend in development mode, run the following from the repository root:

```bash
npm run dev

```

This command executes the compiled [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) entry point, which invokes the `bootstrap()` function and begins listening on the port defined by `process.env.PORT` (defaulting to **3001**).

### Verifying Health Status

Once running, verify the server is accepting connections:

```bash
curl http://localhost:3001/api/health

```

Because the entry point creates the HTTP server that forwards all routes to the NestJS application, this endpoint returns a JSON payload confirming the server status.

### Customizing the Startup Banner

To display additional environment variables in the startup banner, modify the `banner` array inside the `onListen` function:

```typescript
const banner = [
  // ...existing lines
  `  Custom Config: ${process.env.MY_CUSTOM_VAR || 'not set'}`,
];

```

After restarting the server, the new line appears in the console output alongside the standard runtime information.

## Summary

- **[`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts)** is the **main entry point file in TREK server** that orchestrates the entire backend lifecycle.
- It **creates required directories** (`uploads`, `photos`, `backups`, etc.) before the application starts serving traffic.
- It **bootstraps the NestJS application** via `buildApp()` and wraps it in a native Node.js HTTP server.
- It **prints a diagnostic banner** and starts background schedulers for maintenance tasks, WebSocket services, and email reminders.
- It implements **graceful shutdown handling** for `SIGTERM` and `SIGINT` signals to ensure clean database flushing and connection termination.

## Frequently Asked Questions

### What port does the TREK server use by default?

The TREK server defaults to port **3001** when the `PORT` environment variable is not specified. This value is read from `process.env.PORT` during the bootstrap phase in [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts).

### Which directories does the TREK server create on startup?

According to the source code in [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) (lines 10‑20), the server automatically creates the following directories if they do not exist: `uploads`, `photos`, `files`, `covers`, `avatars`, `data/backups`, and `data/tmp`. These paths support file uploads, avatar storage, cover images, and database backup operations.

### How does TREK handle graceful shutdowns?

The entry point registers listeners for `SIGTERM` and `SIGINT` signals (lines 132‑133) that trigger the `shutdown()` function. This function stops background schedulers, closes MCP sessions, shuts down the NestJS application and HTTP server, flushes the SQLite database, and exits the process cleanly to prevent data corruption.

### What background tasks does the TREK scheduler run?

The `scheduler` initialized in [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) (lines 75‑83) manages several background jobs including email reminder dispatch, version checking, demo environment resets, and cache cleanup. These tasks run asynchronously to keep the application state synchronized without blocking HTTP requests.