# Core Components of TREK: Architecture of a Self-Hosted Travel Planning Platform

> Explore the core components of TREK, a self-hosted travel planning platform. Discover its architecture, including React, Node.js, PostgreSQL, and real-time collaboration features.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: architecture
- Published: 2026-07-10

---

**TREK is a full-stack, self-hosted travel planning platform built with React and TypeScript on the frontend, Node.js and Express on the backend, utilizing PostgreSQL for data persistence, Socket.io for real-time collaboration, and a plugin SDK for extensibility.**

TREK is an open-source travel planning application designed for collaborative itinerary management. The codebase at `mauriceboe/TREK` implements a modern web architecture that separates concerns between a responsive single-page interface and a robust API layer. Understanding the core components of TREK reveals how the platform handles everything from OIDC authentication to real-time map collaboration.

## Frontend UI

The frontend is a single-page application that enables users to create trips, manage itineraries, view maps, and collaborate in real time.

Built with **React** and **TypeScript**, the UI entry point resides in [`src/index.tsx`](https://github.com/mauriceboe/TREK/blob/main/src/index.tsx). Styling and layout utilize **TailwindCSS**, while API interactions are abstracted through modules in `src/api/*.ts`.

```tsx
import { createTrip } from '@/api/trips';

const handleCreate = async () => {
  const newTrip = await createTrip({
    name: 'Summer Europe Tour',
    startDate: '2024-07-01',
    endDate: '2024-07-15',
  });
  // Redirect to the newly created trip view
  navigate(`/trip/${newTrip.id}`);
};

```

*(source: [`src/api/trips.ts`](https://github.com/mauriceboe/TREK/blob/main/src/api/trips.ts))*

## Backend API

The backend handles authentication, data persistence, business logic, and exposes a REST API for the frontend and plugins.

Implemented with **Node.js** and **Express** (see [`src/server.ts`](https://github.com/mauriceboe/TREK/blob/main/src/server.ts)), the API organizes core models such as Trip, DayPlan, and PackingList in `src/models/*.ts`. All endpoints are versioned under `/api/v1/`.

```ts
// src/routes/dayPlan.ts
router.post(
  '/:dayId/places',
  authGuard,
  async (req, res) => {
    const { dayId } = req.params;
    const { placeId } = req.body;
    const day = await DayPlan.findById(dayId);
    await day.addPlace(placeId);
    res.json(day);
  },
);

```

*(source: [`src/routes/dayPlan.ts`](https://github.com/mauriceboe/TREK/blob/main/src/routes/dayPlan.ts))*

## Database Layer

Data persistence relies on **PostgreSQL** with **Prisma** as the ORM.

The schema definition in `prisma/schema.prisma` structures user accounts, trips, itineraries, budgets, and plugin data. Migrations are managed via the Prisma CLI.

## Authentication and Authorization

Security is enforced through multiple mechanisms including **OIDC** SSO, two-factor authentication, and granular permission scopes.

- **OIDC implementation**: Located in [`src/auth/oidc.ts`](https://github.com/mauriceboe/TREK/blob/main/src/auth/oidc.ts)
- **2FA handling**: Defined in [`src/auth/2fa.ts`](https://github.com/mauriceboe/TREK/blob/main/src/auth/2fa.ts)
- **Plugin permissions**: Configured in [`src/auth/permissions.ts`](https://github.com/mauriceboe/TREK/blob/main/src/auth/permissions.ts)

## Real-Time Collaboration

Multiple users can edit trips simultaneously via **WebSocket** connections powered by **Socket.io**.

The implementation in [`src/realtime/socket.ts`](https://github.com/mauriceboe/TREK/blob/main/src/realtime/socket.ts) broadcasts events such as "place added" or "budget updated" to all active participants.

## Map and Place Integration

Map visualization and route optimization integrate **Google Maps** APIs.

- **Google Maps service**: [`src/maps/googleMaps.ts`](https://github.com/mauriceboe/TREK/blob/main/src/maps/googleMaps.ts)
- **Route optimizer**: Custom service in [`src/maps/optimizer.ts`](https://github.com/mauriceboe/TREK/blob/main/src/maps/optimizer.ts)

## PDF Export Engine

The platform generates printable PDFs for trips and packing lists using **pdf-lib**.

The server-side generation logic resides in [`src/export/pdfGenerator.ts`](https://github.com/mauriceboe/TREK/blob/main/src/export/pdfGenerator.ts), with endpoints exposed under `/api/v1/export`.

## Plugin System

Extensibility is provided through the **TREK Plugin SDK**, allowing third-party packages to add features.

Plugins conform to the SDK specification in `plugins/sdk/` and can register UI components, API routes, and permission scopes.

```ts
// plugins/travel-tips/index.ts
import { registerWidget } from '@trek/plugin-sdk';

registerWidget('TravelTips', {
  render: () => <TravelTipsWidget />,
  permissions: ['read:trip'],
});

```

*(source: [`plugins/travel-tips/index.ts`](https://github.com/mauriceboe/TREK/blob/main/plugins/travel-tips/index.ts))*

## DevOps and Configuration

Deployment is containerized using **Docker** with `Dockerfile` and [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) templates.

Environment configuration is centralized via **dotenv** (see [`src/config.ts`](https://github.com/mauriceboe/TREK/blob/main/src/config.ts)), with secrets defined in `.env.example`. GitHub Actions in `.github/workflows/` handle CI/CD pipelines including linting, testing, and SDK publishing.

## TREK Core Module

All components are orchestrated by the **TREK core** module in `src/core/`, which manages request handling, data validation, and permission enforcement across the stack.

## Summary

- **Frontend**: React/TypeScript SPA with TailwindCSS, entry at [`src/index.tsx`](https://github.com/mauriceboe/TREK/blob/main/src/index.tsx)
- **Backend**: Node.js/Express API with models in `src/models/*.ts` and routing in `src/routes/`
- **Database**: PostgreSQL with Prisma ORM, schema defined in `prisma/schema.prisma`
- **Authentication**: OIDC and 2FA support via [`src/auth/oidc.ts`](https://github.com/mauriceboe/TREK/blob/main/src/auth/oidc.ts) and [`src/auth/2fa.ts`](https://github.com/mauriceboe/TREK/blob/main/src/auth/2fa.ts)
- **Real-time**: Socket.io implementation in [`src/realtime/socket.ts`](https://github.com/mauriceboe/TREK/blob/main/src/realtime/socket.ts) for live collaboration
- **Maps**: Google Maps integration via [`src/maps/googleMaps.ts`](https://github.com/mauriceboe/TREK/blob/main/src/maps/googleMaps.ts) with custom optimization
- **Exports**: PDF generation using pdf-lib in [`src/export/pdfGenerator.ts`](https://github.com/mauriceboe/TREK/blob/main/src/export/pdfGenerator.ts)
- **Plugins**: Extensible SDK located in `plugins/sdk/` with hook-based architecture
- **Core**: Central orchestration module in `src/core/` tying all layers together

## Frequently Asked Questions

### What frontend technologies does TREK use?

TREK uses **React** with **TypeScript** for the user interface, styled with **TailwindCSS**. The application entry point is [`src/index.tsx`](https://github.com/mauriceboe/TREK/blob/main/src/index.tsx), and API interactions are abstracted through modules in `src/api/*.ts`.

### How does TREK enable real-time collaboration between users?

The platform implements **Socket.io** in [`src/realtime/socket.ts`](https://github.com/mauriceboe/TREK/blob/main/src/realtime/socket.ts) to maintain WebSocket connections. This allows the server to broadcast events like itinerary updates to all connected clients editing the same trip simultaneously.

### What database and ORM does TREK employ?

TREK persists data in **PostgreSQL** and uses **Prisma** as the ORM. The database schema is defined in `prisma/schema.prisma`, and the Prisma CLI manages migrations for user accounts, trips, and plugin data.

### How does the TREK plugin system work?

Developers create Node packages that import from `@trek/plugin-sdk` (located in `plugins/sdk/`). These plugins register widgets, API routes, and permissions through a hook-based API, as demonstrated in the [`plugins/travel-tips/index.ts`](https://github.com/mauriceboe/TREK/blob/main/plugins/travel-tips/index.ts) example.