# How to Explore the TREK Server Source Files: A Complete Monorepo Guide

> Easily explore TREK server source files with this monorepo guide. Start with main.ts, trace module imports, and use tests to navigate the architecture. Learn more about the TREK repository.

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

---

**Start with [`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts) to understand the NestJS bootstrap process, then trace module imports through `shared/src` for Zod schemas, and use the test suites under `server/tests/` and `client/tests/` as interactive maps to navigate the full architecture.**

The TREK repository is a TypeScript monorepo containing a NestJS backend, React frontend, and shared validation logic. To effectively explore the TREK server source files, you must understand the relationship between the three main directories—`server/`, `client/`, and `shared/`—and how their entry points connect through dependency injection and shared schemas.

## Understanding the Monorepo Layout

The TREK project organizes code into three distinct parts that share a root-level configuration:

- **`/server/src`** – NestJS backend containing REST controllers, WebSocket handlers, authentication logic, and MCP integrations
- **`/client/src`** – Vite-powered React application with the dashboard, planner, and collaboration UI
- **`/shared/src`** – TypeScript schemas, internationalization files, and utility functions consumed by both frontend and backend

The root directory contains the orchestration files: [`package.json`](https://github.com/mauriceboe/TREK/blob/main/package.json) defines npm workspaces and scripts, `Dockerfile` builds the production container, and [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) provides development orchestration. This structure means server-side logic lives entirely within `server/src/` while maintaining strict contracts with the client through the `shared/` directory.

## Critical Server Entry Points

### Backend Bootstrap in [`main.ts`](https://github.com/mauriceboe/TREK/blob/main/main.ts)

The server lifecycle begins in [`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts). This file creates the NestJS application instance, registers global pipes, and initializes the HTTP server:

```typescript
// server/src/main.ts
const app = await NestFactory.create(AppModule, { logger: ['error', 'warn', 'log', 'debug', 'verbose'] });
await app.listen(process.env.PORT ?? 3000);

```

From [`main.ts`](https://github.com/mauriceboe/TREK/blob/main/main.ts), trace the `AppModule` import to [`server/src/app.module.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/app.module.ts), which wires together services like `AuthService`, `CollabService`, and their respective controllers. This is your roadmap to understanding server-side business logic.

### WebSocket Real-Time Layer

Real-time collaboration features live in [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts). This file instantiates the WebSocket server and delegates connection management to `CollabService`:

```typescript
// server/src/websocket.ts
const wss = new WebSocket.Server({ noServer: true });
wss.on('connection', (ws) => {
  // delegate to CollabService for broadcasting
});

```

The WebSocket handler runs alongside the HTTP server, allowing you to inspect how real-time updates flow between the client and server-side services.

### Frontend Root and API Integration

While exploring the server, you will need to understand how the client consumes it. The React application mounts in [`client/src/main.tsx`](https://github.com/mauriceboe/TREK/blob/main/client/src/main.tsx):

```tsx
// client/src/main.tsx
import { createRoot } from 'react-dom/client';
import { createRoot } from 'react-dom/client';
import { App } from './App';
createRoot(document.getElementById('root')!).render(<App />);

```

API calls originate from [`client/src/api/places.ts`](https://github.com/mauriceboe/TREK/blob/main/client/src/api/places.ts) and similar files, which perform standard `fetch` requests to the server's REST endpoints.

## Navigating Shared Schemas and Types

All domain objects are defined as Zod schemas in `shared/src`, ensuring type safety across the network boundary. For example, the place validation schema resides in [`shared/src/place/place.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/place/place.schema.ts):

```typescript
// shared/src/place/place.schema.ts
export const placeSchema = z.object({
  id: z.string(),
  name: z.string(),
  latitude: z.number(),
  longitude: z.number(),
  // …more fields
});

```

These schemas are exported from [`shared/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/index.ts), allowing both server and client to import them using the workspace alias `@shared/place`. When you see a server service importing from `@shared`, you are looking at the shared schema layer that prevents type drift between frontend and backend.

## Effective Navigation Strategies

To explore the TREK server source files efficiently, follow this workflow:

1. **Start at the README** – Review the high-level architecture and feature list to identify which server modules handle specific domain areas (authentication, trip planning, collaboration)

2. **Follow the import graph** – From [`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts), navigate to `AppModule`, then into individual services like [`auth.service.ts`](https://github.com/mauriceboe/TREK/blob/main/auth.service.ts) or [`collab.service.ts`](https://github.com/mauriceboe/TREK/blob/main/collab.service.ts). These services import helpers from `shared/src`, showing you the data contracts

3. **Use tests as navigation maps** – The test suites in `server/tests/unit/services/` and `client/tests/unit/` demonstrate exactly how modules are instantiated and exercised. For example, [`server/tests/unit/services/authService.test.ts`](https://github.com/mauriceboe/TREK/blob/main/server/tests/unit/services/authService.test.ts) reveals the dependencies and methods available on the authentication service

4. **Trace shared imports** – When you encounter imports from `@shared/place` or similar aliases in server code, jump to the corresponding file in `shared/src/` to see the validation rules and TypeScript interfaces governing API payloads

## Local Setup for Source Exploration

Clone the repository and prepare your environment for static analysis:

```bash

# Clone the monorepo

git clone https://github.com/mauriceboe/TREK.git
cd TREK

# Install dependencies (populates node_modules for IDE intellisense)

npm ci

# Open in TypeScript-aware editor

code .

```

With dependencies installed, your IDE can resolve imports across the workspace boundary, allowing "Go to Definition" to work seamlessly between `server/src`, `client/src`, and `shared/src`.

### Essential Development Scripts

Run these commands to verify your understanding of the codebase:

| Script | Purpose |
|--------|---------|
| `npm run dev` | Starts server (`nest start --watch`) and client (`vite`) simultaneously for interactive debugging |
| `npm test` | Executes Jest/Vitest suites, revealing code paths and service interactions |
| `npm run build` | Generates production assets via the root `Dockerfile`, showing the deployment packaging |

## Practical Code Examples

### Validating Data with Shared Schemas

Server services use shared Zod schemas to validate incoming DTOs before persistence:

```typescript
import { placeSchema } from '@shared/place';

@Injectable()
export class PlaceService {
  async create(dto: any) {
    // Validate input using the shared schema
    const data = placeSchema.parse(dto);
    // Persist to SQLite (via Prisma or direct query)
    await this.db.place.create({ data });
    return data;
  }
}

```

This pattern appears throughout `server/src/services/`, ensuring that any data entering the database matches the contract expected by the client.

### Extending WebSocket Message Types

To add new real-time functionality, modify [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts):

```typescript
// server/src/websocket.ts
wss.on('message', (msg) => {
  const payload = JSON.parse(msg as string);
  if (payload.type === 'PING') {
    ws.send(JSON.stringify({ type: 'PONG' }));
  }
  // existing handling delegated to CollabService
});

```

## Key Files for Deep Exploration

When auditing or extending the server, prioritize these locations:

- **[`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts)** – Application bootstrap and global middleware registration
- **[`server/src/app.module.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/app.module.ts)** – Dependency injection container wiring all controllers and services
- **[`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts)** – Real-time connection handling and message routing
- **`shared/src/**/*.schema.ts`** – Zod validation schemas defining all API contracts
- **[`server/src/utils/ssrfGuard.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/ssrfGuard.ts)** – Security utilities for external resource fetching
- **`server/tests/unit/`** – Unit tests that demonstrate service usage patterns
- **`Dockerfile`** and **[`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml)** – Production build process and environment configuration

## Summary

- **Start at [`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts)** to understand how the NestJS application initializes and which modules load at startup
- **Trace imports through `shared/src/`** to discover Zod schemas that validate data flowing between client and server
- **Use test files** in `server/tests/unit/` as executable documentation showing how services interact with repositories and external APIs
- **Check [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts)** for real-time collaboration logic that runs parallel to the REST API
- **Reference [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml)** to understand runtime dependencies and volume mounts for persistent data

## Frequently Asked Questions

### Where is the TREK server entry point located?

The server entry point is [`server/src/main.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts). This file bootstraps the NestJS application, configures the logger with verbose output levels, and starts the HTTP server on the port specified by `process.env.PORT` (defaulting to 3000).

### How does the TREK server share types with the client?

The server shares types through the `shared/src` directory, which contains Zod schemas exported via [`shared/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/index.ts). Both server and client import these using the workspace alias `@shared/place` (or similar), ensuring that validation logic and TypeScript definitions remain synchronized across the API boundary.

### What is the best way to understand how a specific service works?

Locate the corresponding unit test in `server/tests/unit/services/`. For example, [`authService.test.ts`](https://github.com/mauriceboe/TREK/blob/main/authService.test.ts) demonstrates how `AuthService` is instantiated, what dependencies it requires, and how its methods behave under various inputs. Tests serve as executable documentation that remains current with the implementation.

### How do I find the WebSocket implementation in the TREK server?

The WebSocket server is defined in [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts). This file creates a `WebSocket.Server` instance that listens on the `/ws` path and delegates incoming connections to `CollabService` for message broadcasting and room management.