SafeCall Docs

Appearance

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:
typescript
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 });
}
  1. If you need a new Valibot schema, add it to server/src/schemas.ts
  2. 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 Ariadne Screen ​

  1. Create ariadne/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:
typescript
import { Database } from "bun:sqlite";
export default function(db: Database) {
  db.run(`CREATE TABLE IF NOT EXISTS your_table (...)`);
}
  1. Add query result type to lib/src/types/query.d.ts
  2. Add Valibot schema to server/src/schemas.ts
  3. 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 ariadne/lib/models/navigation_data.dart with fromJson/toJson

Adding a New Tracking Algorithm ​

  1. Create server/src/algs/tracking_alg_yourname.ts as a pure module: it default-exports an Algorithm (see server/src/algs/tracking_alg_types.ts) and imports only that types file and other pure algorithm modules
  2. Add a configured instance to TRACKING_ALG_CATALOG in server/src/algs/tracking_alg_catalog.ts; its name is the registry name
  3. Add tools/rtls-sim/algs/prod_yourname.ts so the simulator runs the same entry
  4. Add server/tests/tracking_alg_yourname.test.ts
  5. It will automatically appear in /api/v1/tracking/algorithms and be selectable via /api/v1/tracking/start/yourname

See tracking for how the runner drives these modules.

Modifying the Navigation System ​

Server-side (graph storage) ​

  • Floor/node/edge CRUD: server/src/routes/http.ts (route declarations use /floor, /node, /edge before the /api/v1 prefix is applied)
  • Navigation bundle: search for the /navigation/project route declaration (served under /api/v1/navigation/project)
  • Pathfinding: search for the /navigation/pathfind route declaration (served under /api/v1/navigation/pathfind)

Web-side (graph editor) ​

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

Ariadne-side (navigation) ​

  • Graph: ariadne/lib/core/navigation_graph.dart
  • Position: ariadne/lib/core/positioning.dart
  • Renderer: ariadne/lib/game/navigation_game.dart
  • Screen: ariadne/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)

Ariadne build ​

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

Full build ​

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

Running Tests ​

bash
# Everything (typecheck, unit tests, Playwright, contracts)
bun test:all

# Server tests
cd server && bun test

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

# Ariadne tests
cd ariadne && 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)
  • Ariadne: ariadne/lib/screens/home_screen.dart (connection flow)
  • Lib: lib/src/schemas.ts + lib/src/types/query.d.ts (data contracts)
  • Config: config/main.config.json (legacy fallback: root main.config.json) + docs at docs/guide/configuration.md