Component Quick-Start Guides

Concise guides for AI assistants working on specific components. Each section tells you exactly where to look and what patterns to follow.

Adding a New HTTP Route

1. Open server/src/routes/http.ts
2. Find the section matching your domain (auth, beacons, gateways, etc.)
3. Add your route following this pattern:

if (url === "/your-endpoint" && method === "GET") {
  const g = guard_auth(req);       // or guard_admin for admin-only
  if (g instanceof Response) return g;
  const { db } = g;

  // Your logic here
  return rs_res_ok({ data: result });
}

4. If you need a new Valibot schema, add it to server/src/schemas.ts
5. If the web frontend needs to call this route, add schemas to web/src/lib/contracts.ts

Adding a New Web Page

1. Create the page function in web/src/pages/your_page.ts
2. Create HTML templates in web/src/templates/your_page/
3. Register the menu handler in web/src/pages/dashboard.ts
4. Export the page function and import it in dashboard.ts
5. Add any needed API schemas to web/src/lib/contracts.ts

Adding a New Mobile Screen

1. Create mobile/lib/screens/your_screen.dart as a StatefulWidget
2. Navigate to it from an existing screen using Navigator.push()
3. Use ApiClient for server communication
4. If it needs BLE data, take BleScanner as a constructor parameter

Adding a New Database Table

1. Create migration file server/migrations/NNN_description.ts:

import { Database } from "bun:sqlite";
export default function(db: Database) {
  db.run(`CREATE TABLE IF NOT EXISTS your_table (...)`);
}

2. Add query result type to lib/src/types/query.d.ts
3. Add Valibot schema to server/src/schemas.ts
4. Rebuild migration embeds for production: bun scripts/build/generators/embeds.ts

Adding a New Valibot Schema

For MQTT/external data (shared)

Add to lib/src/schemas.ts

For DB query results (server)

Add to server/src/schemas.ts

For API contracts (web)

Add to web/src/lib/contracts.ts

For mobile models

Add to mobile/lib/models/navigation_data.dart with fromJson/toJson

Adding a New Tracking Algorithm

1. Create server/src/algs/tracking_alg_yourname.ts
2. Export a function matching the algorithm interface
3. Register it in server/src/tracking.ts in the algorithm map
4. It will automatically appear in /tracking/algorithms and be selectable via /tracking/start/yourname

Modifying the Navigation System

Server-side (graph storage)

• Floor/node/edge CRUD: server/src/routes/http.ts (search for /floor, /node, /edge)
• Navigation bundle: search for /navigation/project
• Pathfinding: search for /navigation/pathfind

Web-side (graph editor)

• Editor UI: web/src/pages/navigation.ts
• Uses Pixi.js directly (not through canvas.ts)

Mobile-side (navigation)

• Graph: mobile/lib/core/navigation_graph.dart
• Position: mobile/lib/core/positioning.dart
• Renderer: mobile/lib/game/navigation_game.dart
• Screen: mobile/lib/screens/navigation_screen.dart

Modifying the Build Process

Server build

• Entry: scripts/build/server.sh
• Embeds web UI: scripts/build/generators/embeds.ts → server/src/static_embeds.ts

Web build

• Entry: web/build.ts
• Config injection happens here (define constants)

Mobile build

• Entry: scripts/build/mobile.sh
• Release pipeline: scripts/release/mobile.ts

Full build

• Entry: scripts/build/all.sh (calls server + mobile builds)

Running Tests

# Server tests
cd server && bun test

# Contract tests (server ↔ mobile)
bun test:contracts

# Mobile tests
cd mobile && flutter test

# Web type checking
cd web && bun run typecheck

Key Files to Read First

When starting work on any component, read these files first:

• Server: server/src/server.ts (entry point, all exports)
• Web: web/src/web.ts + web/src/pages/dashboard.ts (router + main page)
• Mobile: mobile/lib/screens/home_screen.dart (connection flow)
• Lib: lib/src/schemas.ts + lib/src/types/query.d.ts (data contracts)
• Config: main.config.json + docs at docs/guide/configuration.md