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

The TREK server application boots from server/src/index.ts, which delegates to the bootstrap() function in 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, the main field explicitly declares the entry point:

"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 – The primary entry file defines the bootstrap() function and immediately invokes it to begin server creation.
2. 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.

Development Mode

For local development with hot-reloading, execute:

npm run dev --workspace=server

This invokes the development helper script (server/scripts/dev.mjs) that transpiles and executes src/index.ts automatically.

Production Mode

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

# Compile TypeScript to dist/

npm run build --workspace=server

# Start the compiled bundle

npm start --workspace=server

The production start command executes:

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

This loads the compiled version of 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:

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

In server/src/index.ts, these values are parsed as:

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 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 – Primary entry point that initializes the bootstrap process and manages the server lifecycle.
• server/src/bootstrap.ts – Factory function buildApp() that constructs the NestJS application instance and configures middleware.
• 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, declared in server/package.json.
• The bootstrap() function delegates to buildApp() in 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 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 in development or 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. 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 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 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.

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