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

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): 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): Builds the Nest application, registers global pipes, CORS configuration, Swagger documentation, and custom add-on modules.

• Main Module (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): Implements real-time synchronization channels that broadcast changes instantly to connected front-end clients.

• Authentication (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, placeService.ts, etc.): Contains business logic injected into controllers and accessed by the MCP layer.

• MCP Layer (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): Manages background jobs including email reminders, demo data resets, and cache cleanup.

• Configuration (server/src/config.ts): Reads environment variables, validates them, and provides encryption keys and URL helpers.

Contribution Workflow

According to the 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:

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

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

// 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 to include it in the /mcp/tools manifest.

Writing Integration Tests

Test your endpoints using the NestJS testing harness:

// 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.
• 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 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). 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.

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