# How to Contribute to the TREK Server Project: A Complete Developer's Guide

> Contribute to the TREK server project easily. Fork the repository, branch from dev, and submit PRs with clear guidelines. Learn how to add your code to mauriceboe/TREK.

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

---

**Contribute to the TREK server project by discussing changes in the Discord `#github-pr` channel, forking the repository, branching from `dev`, and submitting PRs with conventional commits, comprehensive tests, and adherence to the NestJS architecture patterns.**

The TREK server is a self-contained NestJS application powering REST API endpoints, real-time WebSocket synchronization, and the Machine-Control-Protocol (MCP) layer for AI assistants. Understanding its modular architecture and contribution workflow is essential for developers who want to add features or fix bugs effectively.

## Understanding the TREK Server Architecture

Before contributing, familiarize yourself with how the server components interact. The codebase follows NestJS conventions with clear separation between entry points, business logic, and infrastructure layers.

### Core Components

- **Entry Point** ([`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts)): Sets up data and upload directories, initializes the Nest application, creates the HTTP server, and registers the WebSocket layer.

- **Bootstrap Logic** ([`server/src/bootstrap.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/bootstrap.ts)): Builds the Nest application, registers global pipes, CORS configuration, Swagger documentation, and custom add-on modules.

- **Main Module** ([`server/src/nest/app.module.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/nest/app.module.ts)): Aggregates all feature modules including `TripModule`, `PlaceModule`, and `McpModule`. Any new module must be imported here to be instantiated.

- **WebSocket Layer** ([`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts)): Implements real-time synchronization channels that broadcast changes instantly to connected front-end clients.

- **Authentication** ([`server/src/middleware/auth.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/middleware/auth.ts)): Handles JWT-based login, password hashing, TOTP MFA, OIDC SSO, and WebAuthn (Passkeys) passwordless authentication.

- **Core Services** ([`server/src/services/tripService.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/services/tripService.ts), [`placeService.ts`](https://github.com/mauriceboe/TREK/blob/main/placeService.ts), etc.): Contains business logic injected into controllers and accessed by the MCP layer.

- **MCP Layer** ([`server/src/mcp/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/mcp/index.ts)): Exposes an OAuth 2.1-protected API at `/mcp/trips` that AI assistants can invoke securely.

- **Scheduler** ([`server/src/scheduler.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/scheduler.ts)): Manages background jobs including email reminders, demo data resets, and cache cleanup.

- **Configuration** ([`server/src/config.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/config.ts)): Reads environment variables, validates them, and provides encryption keys and URL helpers.

## Contribution Workflow

According to the [`CONTRIBUTING.md`](https://github.com/mauriceboe/TREK/blob/main/CONTRIBUTING.md) and wiki documentation, follow this standardized process to contribute to the TREK server project:

1. **Discuss First**: Open a conversation on the Discord `#github-pr` channel to align your approach with maintainers.

2. **Fork and Clone**: Fork the repository on GitHub, then clone your fork locally.

3. **Create a Dev Branch**: All pull requests must target the `dev` branch, not `main`.

4. **Set Up Environment**: Install Node.js 22, run `npm install` in the project root, and start the development server with `npm run dev`. Detailed instructions are available in the wiki page *Development-environment*.

5. **Write Isolated Code**: Implement a single feature or fix per PR. Maintain existing coding style without reformatting unrelated files.

6. **Add Tests**: The project maintains greater than 80% code coverage. Include unit or integration tests for every change and verify them with `npm test`.

7. **Lint and Format**: Ensure `npm run lint` and `npm run format:check` pass locally before submitting, as these run in CI.

8. **Use Conventional Commits**: Format commit messages as `feat(trip): add export to CSV` or `fix(auth): correct OIDC URL handling`.

9. **Submit PR**: Push your branch and open a pull request referencing the related issue, including a concise summary, and linking to the Discord discussion.

## Practical Code Examples

When adding new functionality, you typically need to modify controllers, services, and potentially the MCP layer.

### Adding a Health Check Endpoint

Create a controller in the nest structure:

```typescript
// server/src/nest/health/health.controller.ts
import { Controller, Get } from '@nestjs/common';
import { ApiOperation, ApiResponse } from '@nestjs/swagger';

@Controller('health')
export class HealthController {
  @Get()
  @ApiOperation({ summary: 'Health check' })
  @ApiResponse({ status: 200, description: 'OK' })
  getHealth(): string {
    return 'OK';
  }
}

```

Register it in the main module:

```typescript
// server/src/nest/app.module.ts (excerpt)
import { HealthController } from './health/health.controller';

@Module({
  imports: [ /* existing modules */ ],
  controllers: [HealthController, /* other controllers */],
  providers: [/* existing providers */],
})
export class AppModule {}

```

### Extending the MCP Layer

To make functionality available to AI assistants, add a tool definition:

```typescript
// server/src/mcp/tools/status.ts
import { McpTool } from '../tools';
export const statusTool: McpTool = {
  name: 'status',
  description: 'Returns server health information',
  execute: async () => ({ status: 'healthy', timestamp: new Date().toISOString() }),
};

```

Register this tool in [`server/src/mcp/tools/_shared.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/mcp/tools/_shared.ts) to include it in the `/mcp/tools` manifest.

### Writing Integration Tests

Test your endpoints using the NestJS testing harness:

```typescript
// server/tests/integration/health.test.ts
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from '../../server/src/nest/app.module';

describe('HealthController (e2e)', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
  });

  it('/health (GET)', () => {
    return request(app.getHttpServer())
      .get('/health')
      .expect(200)
      .expect('OK');
  });

  afterAll(async () => {
    await app.close();
  });
});

```

Execute integration tests with `npm run test:e2e`.

## Testing and Quality Standards

Every contribution to the TREK server project must include comprehensive testing. The codebase maintains strict quality gates:

- **Coverage Requirements**: All changes must include unit or integration tests, maintaining the project's >80% coverage threshold.
- **CI Checks**: Pull requests trigger automated linting, formatting checks, and the full test suite.
- **Test Commands**: Use `npm test` for unit tests and `npm run test:e2e` for end-to-end integration testing against the in-memory Nest server.

## Summary

- **Discussion Required**: Always start by discussing your contribution in the Discord `#github-pr` channel before coding.
- **Branch from Dev**: Target the `dev` branch for all pull requests, never `main`.
- **Architecture Pattern**: New features require controllers in `server/src/nest/`, services in `server/src/services/`, and registration in [`server/src/nest/app.module.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/nest/app.module.ts).
- **MCP Integration**: Expose APIs to AI assistants by adding tools in `server/src/mcp/tools/` and registering them in the barrel file.
- **Quality Gates**: Maintain >80% test coverage, pass `npm run lint` and `npm run format:check`, and use conventional commit messages.

## Frequently Asked Questions

### Do I need to discuss my contribution before opening a pull request?

Yes. The contribution guidelines require opening a conversation on the Discord `#github-pr` channel before submitting code. This prevents wasted effort on features that may not align with the project's roadmap or architectural decisions.

### Which branch should I target for pull requests?

All pull requests must target the `dev` branch. The `main` branch represents stable releases, while `dev` contains active development. This workflow is documented in [`CONTRIBUTING.md`](https://github.com/mauriceboe/TREK/blob/main/CONTRIBUTING.md) and ensures stable release cycles.

### How do I expose new API endpoints to AI assistants?

Register your functionality in the MCP layer by creating a tool in `server/src/mcp/tools/` following the `McpTool` interface pattern, then export it through the appropriate barrel file (such as [`_shared.ts`](https://github.com/mauriceboe/TREK/blob/main/_shared.ts)). This makes the endpoint available at `/mcp/tools` with OAuth 2.1 protection.

### What are the testing requirements for contributions?

Every code change requires accompanying unit or integration tests. The project maintains >80% code coverage, and the CI pipeline will fail if your contribution reduces coverage or if tests do not pass. Run `npm test` locally to verify your changes before submitting.