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

Start with 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 defines npm workspaces and scripts, Dockerfile builds the production container, and 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

The server lifecycle begins in server/src/main.ts. This file creates the NestJS application instance, registers global pipes, and initializes the HTTP server:

// 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, trace the AppModule import to 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. This file instantiates the WebSocket server and delegates connection management to CollabService:

// 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:

// 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 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:

// 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, 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, navigate to AppModule, then into individual services like auth.service.ts or 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 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:

# 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:

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:

// 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 – Application bootstrap and global middleware registration
• server/src/app.module.ts – Dependency injection container wiring all controllers and services
• 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 – Security utilities for external resource fetching
• server/tests/unit/ – Unit tests that demonstrate service usage patterns
• Dockerfile and docker-compose.yml – Production build process and environment configuration

Summary

• Start at 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 for real-time collaboration logic that runs parallel to the REST API
• Reference 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. 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. 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 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. 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.

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