# Project pack: TREK @ d805774

Facts about **TREK** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> TREK is a self-hosted trip planner. You build a day-by-day itinerary on a map, add places and bookings, track a shared budget, keep packing lists and documents, and plan with friends or family in real time. It works as an installable app on your phone.

## Version and source
- Repository: https://github.com/liketrek/TREK
- Pinned commit: `d80577480c672799154ea9912918d906d16c0a75`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/liketrek/TREK/archive/d80577480c672799154ea9912918d906d16c0a75.zip
- Official docs: https://github.com/liketrek/TREK/wiki
- Live demo: https://demo.liketrek.com/. Shared demo. Don't enter real data.
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/liketrek/TREK bespoke-trek
  cd bespoke-trek
  git checkout --detach d80577480c672799154ea9912918d906d16c0a75
  # Prepare development requirements and local configuration first.
  cd server
  npm install
  npm run dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  ENCRYPTION_KEY=$(openssl rand -hex 32) docker run -d -p 3000:3000 -e ENCRYPTION_KEY=$ENCRYPTION_KEY -v ./data:/app/data -v ./uploads:/app/uploads mauriceboe/trek
  # then open http://localhost:3000 (the admin login is printed in the container log on first start)
  ```

- Needs: Docker for a trial, Node 22 for development
- Develop: `cd server && npm run dev  # and, in another terminal: cd client && npm run dev`
- Test: `cd client && npm test`
- Stack: typescript (React, Vite, Node.js, Express, Tailwind). Difficulty for a non-developer with an AI: **moderate**. A compact TypeScript project with a React client, a Node server and a plugin SDK. Settings cover most trips; new features follow clear client and server folders.

## The project's own AI instructions
Read these in the repository before changing code: `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **trips-and-members** [settings]: Itineraries, collaborators, categories and currencies. → `In the app, under Trips, Members and Budget`
- **admin-settings** [settings]: Registration, language and integrations. → `Admin panel and environment variables`
- **plugins** [extend]: Add features without changing the core. → `plugin-sdk/ and the examples in plugin-sdk/examples`
- **mcp-access** [extend]: Let an AI assistant read and edit your trip safely. → `MCP.md`
- **client-ui** [code]: Screens, map layers and styling. → `client/src`
- **server-api** [code]: New data and endpoints. → `server/`

## Must keep working
- Encryption of stored secrets with ENCRYPTION_KEY.
- Real-time sync between collaborators.
- Upload handling and file permission checks.

## Staying updatable
Use plugins and the MCP interface first. Keep code changes in new client components and server routes.

## Data, costs and safety
- Personal data: **yes**. Stored in: A SQLite database and uploaded documents in /app/data and /app/uploads. Bookings, passport copies and travel dates are sensitive. Back up the data and uploads folders.
- Service: Map and place search provider (optional, free tiers): Search for places and show maps.
- Service: Email (SMTP) (optional, usually free to a few dollars): Invitations.
- Setting `ENCRYPTION_KEY` (**secret**: the person enters it themselves, never in chat): Key that protects stored secrets. Keep a copy safe; never paste it into an AI chat.
- Setting `ADMIN_EMAIL`: Email of the first admin account.
- Setting `ADMIN_PASSWORD` (**secret**: the person enters it themselves, never in chat): Password of the first admin account. Never paste it into an AI chat.
- Trips contain dates when your home is empty. Share access carefully.
- Keep ENCRYPTION_KEY safe and backed up. Without it stored secrets cannot be read.
- Don't commit the data or uploads folders.

---

# Customising TREK

TREK has a React client, a Node server and a plugin SDK. Start with plugins when you can.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Screens and map views | client/src/ |
| Server routes, database and services | server/ |
| Shared types | shared/ |
| Plugin SDK and examples | plugin-sdk/ |
| AI access description | MCP.md |
| Helm charts | charts/ |

## Use the gentlest change first

1. **Settings (no code):** trips, members, budgets, categories and admin settings.
2. **Extend:** plugins and the MCP interface.
3. **Code:** client components and server routes.

## Recipes

- **New plugin:** copy an example from `plugin-sdk/examples`, change its manifest and hooks, and load it from the admin panel.
- **New trip field:** add it to the database setup and the trip route in `server/`, then to the trip form in `client/src`.

## Running and checking your changes

- Run server and client dev servers, create a trip, add a place and a budget item.
- `npm test` in `client/` and `npm run typecheck` in `server/`.
- Open it on a phone-sized window to check mobile layout.

## Pitfalls

- Back up the data folder before testing schema changes.
- Map providers need keys or rate limits. Test with a small number of requests.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/trek/d805774/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/trek/d805774/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/trek/d805774/r2/SKILL.md)