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

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. Styling and layout utilize TailwindCSS, while API interactions are abstracted through modules in src/api/*.ts.

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)

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), the API organizes core models such as Trip, DayPlan, and PackingList in src/models/*.ts. All endpoints are versioned under /api/v1/.

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

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
• 2FA handling: Defined in src/auth/2fa.ts
• Plugin permissions: Configured in 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 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
• Route optimizer: Custom service in 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, 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.

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

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

(source: plugins/travel-tips/index.ts)

DevOps and Configuration

Deployment is containerized using Docker with Dockerfile and docker-compose.yml templates.

Environment configuration is centralized via dotenv (see 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
• 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 and src/auth/2fa.ts
• Real-time: Socket.io implementation in src/realtime/socket.ts for live collaboration
• Maps: Google Maps integration via src/maps/googleMaps.ts with custom optimization
• Exports: PDF generation using pdf-lib in 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, 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 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 example.

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