### Start Server (Production)

Source: https://github.com/mauriceboe/trek/blob/main/wiki/Development-environment.md

Starts the server in production mode.

```bash
npm start
```

--------------------------------

### Run TREK with Docker

Source: https://github.com/mauriceboe/trek/blob/main/README.md

Quickly start TREK using Docker. Ensure you have Docker installed and an ENCRYPTION_KEY generated. The container maps local data and upload directories.

```bash
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
```

--------------------------------

### Install KItinerary on Linux

Source: https://github.com/mauriceboe/trek/wiki/Development-environment

Installs the KItinerary binary on Debian-based Linux systems. This is required for the booking-confirmation import feature to function.

```bash
sudo apt-get install -y libkitinerary-bin
```

--------------------------------

### Run Trek with Docker

Source: https://github.com/mauriceboe/trek/wiki/Install-Docker

Use this command for a single-container Docker setup, suitable for testing or simple personal installations. Ensure you replace `<your-32-byte-hex-key>` with a generated key for security.

```bash
docker run -d \
  --name trek \
  -p 3000:3000 \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  -e ENCRYPTION_KEY=<your-32-byte-hex-key> \
  --restart unless-stopped \
  mauriceboe/trek:latest
```

--------------------------------

### Run TREK with Docker

Source: https://github.com/mauriceboe/trek/wiki/Quick-Start

Starts the TREK container, generates an encryption key, and maps necessary ports and volumes for persistence. Ensure Docker is installed and port 3000 is available.

```bash
ENCRYPTION_KEY=$(openssl rand -hex 32) docker run -d \
  --name trek \
  -p 3000:3000 \
  -e ENCRYPTION_KEY=$ENCRYPTION_KEY \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  --restart unless-stopped \
  mauriceboe/trek:latest
```

--------------------------------

### Install All Project Dependencies

Source: https://github.com/mauriceboe/trek/wiki/Development-environment

Run this command at the root of the repository to install all dependencies for the npm workspace monorepo.

```bash
npm ci
```

--------------------------------

### Basic TREK Helm Installation

Source: https://github.com/mauriceboe/trek/wiki/Install-Helm

Installs TREK using the Helm chart with default configurations. This includes a ClusterIP service, default PVC sizes, and no ingress.

```bash
helm install trek trek/trek
```

--------------------------------

### Install Trek Helm Chart with Admin Credentials

Source: https://github.com/mauriceboe/trek/wiki/Install-Helm

Use this command to install the Trek Helm chart and set initial admin credentials. Both ADMIN_EMAIL and ADMIN_PASSWORD must be set together. If either is missing, a default admin account with a random password will be created.

```bash
helm install trek trek/trek \
  --set secretEnv.ADMIN_EMAIL=admin@example.com \
  --set secretEnv.ADMIN_PASSWORD=<your-secure-password>
```

--------------------------------

### Run All Workspaces Development Server

Source: https://github.com/mauriceboe/trek/blob/main/wiki/Development-environment.md

Starts the development server for all workspaces simultaneously using concurrently. This is the recommended way to work.

```bash
npm run dev
```

--------------------------------

### Install TREK Helm Chart with Ingress Enabled

Source: https://github.com/mauriceboe/trek/blob/main/charts/README.md

Install the TREK Helm chart from a local directory, enabling Ingress and configuring a custom host. Refer to `values.yaml` for more configuration options.

```sh
helm install trek ./chart \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=yourdomain.com
```

--------------------------------

### Install TREK on Proxmox VE LXC

Source: https://github.com/mauriceboe/trek/wiki/Install-Proxmox

Run this command in the Proxmox VE Shell to install TREK. Always verify the latest command on the community-scripts TREK page before execution.

```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/trek.sh)"
```

--------------------------------

### System Notice i18n Key Examples

Source: https://github.com/mauriceboe/trek/blob/main/docs/system-notices.md

Examples of i18n keys used for different system notice fields. These keys follow the convention 'system_notice.<notice_id_snake>.<field>'.

```plaintext
system_notice.welcome_v1.title
system_notice.welcome_v1.body
system_notice.welcome_v1.cta_label
system_notice.welcome_v1.highlight_plan
system_notice.welcome_v1.hero_alt
```

--------------------------------

### Start TREK with Docker Compose

Source: https://github.com/mauriceboe/trek/wiki/Install-Docker-Compose

Command to start TREK in detached mode using Docker Compose. Use 'docker compose logs -f' to monitor the application's output.

```bash
docker compose up -d
```

```bash
docker compose logs -f
```

--------------------------------

### Install TREK with Explicit Encryption Key

Source: https://github.com/mauriceboe/trek/wiki/Install-Helm

Installs TREK and sets an explicit 64-character hex encryption key using the `openssl rand -hex 32` command.

```bash
helm install trek trek/trek \
  --set secretEnv.ENCRYPTION_KEY=$(openssl rand -hex 32)
```

--------------------------------

### NestJS Module Layout Example

Source: https://github.com/mauriceboe/trek/blob/main/server/src/nest/README.md

Illustrates the typical file structure for a domain module within the NestJS migration layer.

```tree
shared/src/<domain>/<domain>.schema.ts(.spec.ts)   # Zod contract — single source of truth
server/src/nest/<domain>/<domain>.service.ts        # business logic (ported 1:1 from the Express service)
server/src/nest/<domain>/<domain>.controller.ts     # same routes/verbs/params/status codes as Express
server/src/nest/<domain>/<domain>.module.ts         # registered in app.module.ts
```

--------------------------------

### Page Structure Example

Source: https://github.com/mauriceboe/trek/blob/main/client/src/pages/PATTERN.md

Illustrates the typical file organization for a page, separating the container component from its associated hook and model.

```treeview
src/pages/
  DashboardPage.tsx          ← container: reads the hook, renders JSX
  dashboard/
    useDashboard.ts          ← state, effects, API calls, handlers
    dashboardModel.ts        ← (optional) pure types + helpers, no React
```

--------------------------------

### Build All Workspaces Sequentially

Source: https://github.com/mauriceboe/trek/blob/main/wiki/Development-environment.md

Builds the shared code, then the server, and finally the client in order.

```bash
npm run build
```

--------------------------------

### Preview Client Production Build

Source: https://github.com/mauriceboe/trek/blob/main/wiki/Development-environment.md

Locally previews the production build of the client application.

```bash
npm run preview
```

--------------------------------

### Install TREK with Generated Encryption Key

Source: https://github.com/mauriceboe/trek/wiki/Install-Helm

Installs TREK and instructs the Helm chart to generate a random 32-character alphanumeric encryption key for encrypting secrets at rest. This is recommended for new installations.

```bash
helm install trek trek/trek --set generateEncryptionKey=true
```

--------------------------------

### NestJS Parity Test Example

Source: https://github.com/mauriceboe/trek/blob/main/server/src/nest/README.md

Example of a parity test to ensure identical responses between Express and NestJS controllers.

```typescript
tests/parity/<domain>.parity.test.ts. Mock the shared service
identically for both apps, then fire the same request at the Express route and the
Nest controller with the `expectParity()` harness (`tests/parity/parity.ts`) and
assert identical status + body. This is the gate before flipping the toggle.
See `weather.parity.test.ts`.
```

--------------------------------

### NestJS End-to-End Test Example

Source: https://github.com/mauriceboe/trek/blob/main/server/src/nest/README.md

Example of an end-to-end test for a NestJS module, using a temporary in-memory database and real authentication guards.

```typescript
tests/e2e/<domain>.e2e.test.ts. Boot the Nest module against a temp
in-memory SQLite db via the shared harness (`tests/e2e/harness.ts`:
`createTempDb`/`seedUser`/`sessionCookie`), exercising the **real** `JwtAuthGuard`
end-to-end (401 without cookie, 200 with a signed session). Mock external I/O
(HTTP/etc.). See `weather.e2e.test.ts`.
```

--------------------------------

### NestJS Controller Unit Test Example

Source: https://github.com/mauriceboe/trek/blob/main/server/src/nest/README.md

Example of a NestJS controller unit test, focusing on asserting status codes, error bodies, and input forwarding.

```typescript
tests/unit/nest/<domain>.controller.test.ts
Instantiate the controller with a mocked service; assert status codes, the exact
`{ error }` bodies, and that inputs are forwarded correctly (defaults, coercion).
See `weather.controller.test.ts`.
```

--------------------------------

### Run All System Notice Tests

Source: https://github.com/mauriceboe/trek/blob/main/docs/system-notices.md

A combined command to run all server-side unit and integration tests for system notices, followed by client-side unit tests for the `SystemNoticeModal` component.

```bash
cd server && npx vitest run tests/unit/systemNotices/ tests/integration/systemNotices.test.ts
cd client && npm run test -- SystemNoticeModal
```

--------------------------------

### Generate Random Encryption Key at Install

Source: https://github.com/mauriceboe/trek/blob/main/charts/trek/templates/NOTES.txt

Set this value to true to have the Helm chart automatically generate a random encryption key during installation. This key is persisted across upgrades.

```bash
--set generateEncryptionKey=true
```

--------------------------------

### Run Server Unit Tests for System Notices

Source: https://github.com/mauriceboe/trek/blob/main/docs/system-notices.md

Execute unit tests for system notice conditions. No database is required for these tests.

```bash
cd server && npx vitest run tests/unit/systemNotices/
```

--------------------------------

### Install TREK Using Existing Kubernetes Secret for Encryption Key

Source: https://github.com/mauriceboe/trek/wiki/Install-Helm

Creates a Kubernetes secret named 'trek-secrets' with an encryption key and then installs TREK, referencing this existing secret.

```bash
kubectl create secret generic trek-secrets \
  --from-literal=ENCRYPTION_KEY=$(openssl rand -hex 32)

helm install trek trek/trek \
  --set existingSecret=trek-secrets
```

--------------------------------

### Format All Workspaces

Source: https://github.com/mauriceboe/trek/blob/main/wiki/Development-environment.md

Formats the code across all workspaces according to predefined style guidelines.

```bash
npm run format
```

--------------------------------

### Run Server Integration Tests

Source: https://github.com/mauriceboe/trek/blob/main/wiki/Development-environment.md

Executes the integration tests for the server.

```bash
npm run test:integration
```

--------------------------------

### Get Journey Share Link

Source: https://github.com/mauriceboe/trek/blob/main/MCP.md

Retrieves the current public share link for a journey.

```APIDOC
## get_journey_share_link

### Description
Get the current public share link for a journey.

### Method
GET

### Endpoint
/journeys/{journey_id}/share-link
```

--------------------------------

### Idempotency Interceptor Configuration

Source: https://github.com/mauriceboe/trek/blob/main/server/src/nest/README.md

Example of configuring the global idempotency interceptor for replaying client requests.

```typescript
common/idempotency.interceptor.ts — global `APP_INTERCEPTOR` replaying the
client's `X-Idempotency-Key` on mutations, mirroring the legacy
`applyIdempotency` middleware so retried writes don't double-apply.
```

--------------------------------

### Run Server Integration Tests for System Notices

Source: https://github.com/mauriceboe/trek/blob/main/docs/system-notices.md

Execute integration tests for system notices against an in-memory SQLite database. These tests cover API endpoints and dismissal logic.

```bash
cd server && npx vitest run tests/integration/systemNotices.test.ts
```

--------------------------------

### Get Journey Suggestions

Source: https://github.com/mauriceboe/trek/blob/main/MCP.md

Retrieves suggested trips to add to journeys, based on recent trip history.

```APIDOC
## get_journey_suggestions

### Description
Get suggested trips to add to journeys (based on recent trip history).

### Method
GET

### Endpoint
/journeys/suggestions
```

--------------------------------

### Run Tests

Source: https://github.com/mauriceboe/trek/wiki/Development-environment

Execute all project tests from the repository root to ensure code quality before pushing changes. This is a crucial step in the development workflow.

```bash
npm test
```

--------------------------------

### Get Journey

Source: https://github.com/mauriceboe/trek/blob/main/MCP.md

Retrieves a full snapshot of a specific journey, including its metadata, entries, contributors, and linked trips.

```APIDOC
## get_journey

### Description
Get a full snapshot of a journey: metadata, entries, contributors, and linked trips.

### Method
GET

### Endpoint
/journeys/{journey_id}
```

--------------------------------

### Run Server Tests with Coverage

Source: https://github.com/mauriceboe/trek/blob/main/wiki/Development-environment.md

Executes server tests and generates a coverage report.

```bash
npm run test:coverage
```

--------------------------------

### Container Component Example

Source: https://github.com/mauriceboe/trek/blob/main/client/src/pages/PATTERN.md

A presentation-only container component that fetches data from its hook and renders the UI. It should not contain stateful logic.

```tsx
export default function DashboardPage() {
  const { t } = useTranslation()
  const { trips, isLoading, handleCreate } = useDashboard()
  if (isLoading) return <Spinner />
  return <Grid trips={trips} onCreate={handleCreate} />
}
```

--------------------------------

### Run Coverage for Server and Client

Source: https://github.com/mauriceboe/trek/blob/main/wiki/Development-environment.md

Generates test coverage reports for the server and client workspaces.

```bash
npm run test:cov
```

--------------------------------

### System Notices Data Flow Diagram

Source: https://github.com/mauriceboe/trek/blob/main/docs/system-notices.md

Illustrates the sequence of operations for fetching and displaying system notices, from user authentication to client-side rendering and dismissal.

```text
1. User authenticates
        │
        ▼
2. authStore.loadUser() completes
        │
        ▼
3. SystemNoticeHost mounts → calls useSystemNoticeStore.fetch()
        │   (also triggered on cold page reload if store not yet loaded)
        ▼
4. GET /api/system-notices/active
        │
        ▼
5. service.getActiveNoticesFor(userId)
   ├── reads user row  (login_count, first_seen_version, role)
   ├── counts user trips
   ├── reads user_notice_dismissals
   ├── filters SYSTEM_NOTICES:
   │     – not dismissed
   │     – within [minVersion, maxVersion) range for the running app version
   │     – all conditions pass (AND logic)
   ├── sorts by priority → severity → publishedAt (desc)
   └── strips server-only fields (conditions, publishedAt, minVersion, maxVersion, priority)
        │
        ▼
6. Client receives SystemNoticeDTO[]
        │
        ▼
7. SystemNoticeHost partitions by display type
   ├── modal  → ModalRenderer  (multi-page pager, slide transitions)
   ├── banner → BannerRenderer (sticky top bar, max 2)
   └── toast  → ToastRenderer  (fires window.__addToast, auto-dismisses)
        │
        ▼
8. User dismisses → POST /api/system-notices/:id/dismiss
   ├── Server: INSERT OR IGNORE into user_notice_dismissals
   └── Client: optimistic remove from store (retry once on failure)
```