How to Debug TREK Code: Essential Strategies for the Travel Planner Stack

Debug TREK code by running the full-stack app in development mode with source maps enabled, attaching a Node debugger to the NestJS backend on port 9229, inspecting WebSocket traffic in browser DevTools, and verifying environment variables like ENCRYPTION_KEY and LOG_LEVEL to isolate runtime failures.

TREK is a full-stack, real-time collaborative travel planner built with a NestJS backend and React 19 frontend. When learning how to debug TREK code, you must account for its three-layer architecture: the SQLite-backed API server, the Vite-powered client, and the WebSocket synchronization layer that keeps trip data in sync across users.

Understanding the TREK Architecture

Before diving into specific debugging tactics, map the codebase to its runtime layers:

Layer	Technologies	Key Entry Points
Backend	NestJS 11, TypeScript, SQLite	[server/src/main.ts](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts) bootstraps the app; [server/src/websocket.ts](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) handles real-time channels.
API Security	SSRF Guard, Crypto utils	[server/src/utils/ssrfGuard.ts](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/ssrfGuard.ts) validates outbound HTTP; [server/src/utils/crypto.ts](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/crypto.ts) manages ENCRYPTION_KEY logic.
Frontend	React 19, Zustand, Vite, Tailwind	[client/src/App.tsx](https://github.com/mauriceboe/TREK/blob/main/client/src/App.tsx) is the root component; feature folders like client/src/components/Weather/ contain UI logic.
Real-time Sync	WebSocket (ws)	Clients connect to /ws (requires reverse-proxy configuration for upgrade).
Add-ons	Dynamic modules	Schemas in shared/src/* (e.g., [shared/src/trip/trip.schema.ts](https://github.com/mauriceboe/TREK/blob/main/shared/src/trip/trip.schema.ts)) validate toggled features.

Backend Debugging Techniques

Inspect Server Logs

TREK writes runtime logs to data/logs/trek.log. Adjust verbosity by setting the LOG_LEVEL environment variable from info to debug in your .env file.

For encryption-related failures, trace the key derivation logic in [server/src/utils/crypto.ts](https://github.com/mauriceboe/TREK/blob/main/server/src/utils/crypto.ts). A missing or malformed ENCRYPTION_KEY causes immediate startup crashes.

Attach VS Code Debugger

Configure your launch.json to attach to the Node process on port 9229. Set breakpoints directly in [server/src/main.ts](https://github.com/mauriceboe/TREK/blob/main/server/src/main.ts) or within any NestJS service to inspect request pipelines.

{
  "type": "node",
  "request": "attach",
  "name": "Attach to TREK",
  "port": 9229
}

Debug WebSocket Handlers

Insert logging inside [server/src/websocket.ts](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) to trace message flow:

// server/src/websocket.ts
ws.on('message', (msg) => {
  console.debug('WS message received:', msg);
  // Process synchronization logic...
});

Frontend Debugging Strategies

React Component Inspection

For UI bugs, start with high-traffic components like [client/src/components/Weather/WeatherWidget.tsx](https://github.com/mauriceboe/TREK/blob/main/client/src/components/Weather/WeatherWidget.tsx) or TripFormModal.tsx. Use Chrome or Firefox DevTools to inspect the component tree and verify Tailwind class applications directly in the JSX.

Zustand State Debugging

Since TREK uses Zustand for client state, you can dump the entire store to the console at any time:

// Anywhere in the client codebase
import { useStore } from '@/store';
console.log('Current store state:', useStore.getState());

This reveals whether state updates triggered by WebSocket messages actually reached the UI layer.

WebSocket Connection Troubleshooting

Connection drops between the React client and NestJS server usually stem from reverse-proxy misconfigurations.

1. Open browser DevTools → Network → filter by WS.
2. Verify the client successfully upgrades to /ws.
3. If the connection fails, ensure your Nginx (or equivalent) includes a location /ws block to forward WebSocket traffic.

Check the README for recommended reverse-proxy examples that handle the WebSocket upgrade headers.

Environment Configuration and Common Pitfalls

Missing environment variables are the most common cause of TREK startup failures. Use .env.example as your template and never commit real secrets.

Symptom	Likely Cause	Quick Fix
Server crashes on start	Missing ENCRYPTION_KEY or invalid ADMIN_* credentials	Generate a key via openssl rand -hex 32, set ADMIN_EMAIL and ADMIN_PASSWORD.
WebSocket connection refused	Reverse-proxy not forwarding /ws	Add the location /ws block from the README examples.
API returns 500 for external HTTP calls	SSRF guard blocking the URL	Add the domain to ALLOW_INTERNAL_NETWORK (security-sensitive).
UI not updating after state change	WebSocket message lost or state not syncing	Verify the client receives the update event in [server/src/websocket.ts](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts).

Testing and Plugin Development

Run the Vitest suite to catch regressions early:

npm test

Run a single spec in watch mode for targeted feedback:

npx vitest run shared/src/weather/weather.schema.spec.ts --watch

For plugin developers, use the plugin-sdk CLI to validate manifests:

npm run sdk:dev        # Launches sandbox with hot-reload

npx ts-node plugin-sdk/src/cli/validate.ts ./my-plugin/manifest.json

Performance Profiling

TREK ships with two helper scripts for performance analysis. After recording a Chrome DevTools performance trace, run:

node scripts/analyze-react-profiler.cjs trace.json
node scripts/analyze-devtool-profiler.cjs trace.json

These pinpoint React render bottlenecks or slow JavaScript execution in the event loop.

Summary

• Start with logs: Check data/logs/trek.log and adjust LOG_LEVEL to debug for verbose output.
• Use source maps: Run npm run dev to enable hot-reload and full source-map support for both frontend and backend.
• Attach a debugger: Connect VS Code to the Node process on port 9229 to breakpoint NestJS services.
• Trace WebSocket issues: Verify /ws upgrade in browser DevTools and log messages in server/src/websocket.ts.
• Validate state: Log useStore.getState() to debug Zustand state mismatches.
• Check environment: Ensure ENCRYPTION_KEY, ADMIN_EMAIL, and ADMIN_PASSWORD are set before startup.

Frequently Asked Questions

Why does my TREK server crash immediately on startup?

The NestJS backend requires a valid ENCRYPTION_KEY and admin credentials to bootstrap. Generate a secure key with openssl rand -hex 32, set it in your .env file alongside ADMIN_EMAIL and ADMIN_PASSWORD, then restart. Without these variables, the crypto utilities in server/src/utils/crypto.ts throw fatal errors.

How do I debug why my React UI is not updating when trip data changes?

First, verify the WebSocket connection is active in browser DevTools under the Network → WS tab. Then, log the Zustand store state using console.log(useStore.getState()) to confirm the client received the update. If the store updated but the UI did not, check the React component's subscription to the specific store slice in client/src/App.tsx or related feature folders.

Where can I find logs for failed outgoing HTTP requests made by the server?

TREK logs outbound HTTP activity and SSRF rejections to data/logs/trek.log. If a request returns 500, check if the URL was blocked by server/src/utils/ssrfGuard.ts. You can temporarily allow internal network ranges by setting ALLOW_INTERNAL_NETWORK, though this reduces security protections.

How do I run a single unit test when debugging a schema validation error?

Use Vitest's file filter with the --watch flag to isolate the failing test. For example, run npx vitest run shared/src/weather/weather.schema.spec.ts --watch to continuously execute only the weather schema specs. This provides rapid feedback while you modify validation logic in the shared layer.

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