# Main Entry Point for the TREK Server Application: Startup Flow Explained

> Discover the TREK server application's main entry point at server/src/index.ts. Learn how it bootstraps the NestJS application for core functionality.

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

---

**The TREK server application boots from [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts), which delegates to the `bootstrap()` function in [`server/src/bootstrap.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/bootstrap.ts) to instantiate the NestJS application and attach it to the native HTTP server.**

The TREK repository (`mauriceboe/TREK`) implements a dedicated server package that requires precise initialization steps. Understanding the main entry point is essential for debugging startup issues, customizing runtime configuration, and deploying the service in production environments.

## Entry Point Configuration and Bootstrap Flow

The startup sequence follows a clear chain of responsibility from the package definition to the running HTTP server.

### Package Declaration

In **[`server/package.json`](https://github.com/mauriceboe/TREK/blob/main/server/package.json)**, the `main` field explicitly declares the entry point:

```json
"main": "src/index.ts"

```

This declaration tells Node.js and npm which file to execute when the package starts.

### Startup Sequence

When the server initializes, execution flows through three distinct layers:

1. **[`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts)** – The primary entry file defines the `bootstrap()` function and immediately invokes it to begin server creation.
2. **[`server/src/bootstrap.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/bootstrap.ts)** – Contains the `buildApp()` helper that constructs the NestJS application, wires middleware, and configures platform routes.
3. **HTTP Server Attachment** – The resulting `INestApplication` is attached to a native Node.js `http.Server`, which begins listening on `process.env.PORT` (defaulting to 3001).

## Running the TREK Server

Depending on your environment, you launch the application using different npm scripts defined in [`server/package.json`](https://github.com/mauriceboe/TREK/blob/main/server/package.json).

### Development Mode

For local development with hot-reloading, execute:

```bash
npm run dev --workspace=server

```

This invokes the development helper script (`server/scripts/dev.mjs`) that transpiles and executes [`src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/src/index.ts) automatically.

### Production Mode

Production deployment requires a build step followed by the start command:

```bash

# Compile TypeScript to dist/

npm run build --workspace=server

# Start the compiled bundle

npm start --workspace=server

```

The production start command executes:

```bash
node --require tsconfig-paths/register dist/index.js

```

This loads the compiled version of [`src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/src/index.ts) from the `dist/` directory.

## Configuration and Environment Variables

The entry point reads runtime configuration from environment variables before binding to the network interface.

### Port and Host Settings

Override the default port (3001) and host interface using:

```bash
PORT=8080 HOST=0.0.0.0 npm start --workspace=server

```

In [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts), these values are parsed as:

```typescript
const PORT = Number(process.env.PORT) || 3001;
const HOST = process.env.HOST;

```

## Graceful Shutdown Implementation

The entry point registers signal handlers for `SIGTERM` and `SIGINT` to ensure clean termination. When a shutdown signal is received, the `shutdown()` function defined in [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) orchestrates the following sequence:

- Stops scheduled background jobs.
- Closes active MCP sessions.
- Shuts down the NestJS application and HTTP server.
- Flushes the SQLite database buffer.

This prevents data loss and ensures that ongoing requests complete before the process exits.

## Key Source Files

Understanding the server architecture requires familiarity with these specific files:

- **[`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts)** – Primary entry point that initializes the bootstrap process and manages the server lifecycle.
- **[`server/src/bootstrap.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/bootstrap.ts)** – Factory function `buildApp()` that constructs the NestJS application instance and configures middleware.
- **[`server/package.json`](https://github.com/mauriceboe/TREK/blob/main/server/package.json)** – Defines the `main` entry field and npm scripts for development and production.
- **`server/scripts/build.mjs`** – Compilation script for production builds.
- **`server/scripts/dev.mjs`** – Development server with hot-reload capabilities.

## Summary

- The TREK server entry point is **[`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts)**, declared in [`server/package.json`](https://github.com/mauriceboe/TREK/blob/main/server/package.json).
- The `bootstrap()` function delegates to `buildApp()` in [`server/src/bootstrap.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/bootstrap.ts) to construct the NestJS application.
- The server listens on `process.env.PORT` (default 3001) and supports `HOST` configuration.
- Production deployments use the compiled [`dist/index.js`](https://github.com/mauriceboe/TREK/blob/main/dist/index.js) output, while development uses the TypeScript source directly.
- Graceful shutdown handlers ensure clean termination of database connections and background jobs.

## Frequently Asked Questions

### What file should I run to start the TREK server manually?

You should execute [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) in development or [`dist/index.js`](https://github.com/mauriceboe/TREK/blob/main/dist/index.js) in production. The preferred method is using the npm scripts: `npm run dev --workspace=server` for development or `npm start --workspace=server` after building.

### How does the TREK server handle environment configuration?

The entry point reads `process.env.PORT` and `process.env.HOST` directly in [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts). If `PORT` is not set, it defaults to 3001. These variables must be set before the Node.js process starts, as they are evaluated during the bootstrap phase.

### Where is the NestJS application actually created?

The NestJS application instance is created in [`server/src/bootstrap.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/bootstrap.ts) by the `buildApp()` function. This file handles all framework initialization, including middleware registration and route wiring, before returning the `INestApplication` to the entry point.

### What happens when the TREK server receives a shutdown signal?

When the process receives `SIGTERM` or `SIGINT`, the `shutdown()` function in [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) triggers a graceful shutdown sequence. This stops scheduled jobs, closes MCP sessions, shuts down the HTTP server, and flushes the SQLite database to prevent data corruption.