Developer Handbook

This handbook documents the current repository state from the codebase itself: active applications, supporting projects, cloud and network architecture, business logic, developer workflows, and handoff notes.

What is in scope

• nuxt-frontend/ — active Nuxt 3 web application and Capacitor mobile shell
• static-web-app/api/ — active Azure Functions v4 backend API
• database/ — PostgreSQL migrations and seed tooling
• docs-site/ — published VitePress documentation
• windows-desktop-gateway/ — active Windows BLE gateway agent and MSI installer
• esp32-gateway/ and ble-scanner/ — supporting BLE ingestion utilities
• archived/ and static-web-app/ legacy folders — historical surfaces retained for reference

Current repository shape

Area	Current state	Why it matters
Nuxt frontend	Active	Main operator/admin UI, mobile layout, docs hosting, Capacitor packaging
Azure Functions API	Active	Auth, RBAC, telemetry ingestion, emergency workflows, health, diagnostics
Database	Active	Schema history for RTLS, emergency, analytics, weather, phone beacons, desktop gateways
Docs site	Active	Built into nuxt-frontend/public/docs and deployed with the frontend workflow
Windows desktop gateway	Active	Dedicated Windows service + MSI + tests + release workflow
Android mobile build	Partially automated	GitHub workflow builds debug APKs; iOS remains source/Xcode driven
ESP32 gateway	Supporting utility	Alternate BLE-to-IoT-Hub path for hardware deployments
Legacy vanilla frontend and root Functions	Archived	Useful for migration context, not current delivery targets

Quick links

• Project Status
• Onboarding
• Architecture
• Frontend
• Backend and API
• Data and Business Logic
• Platforms and Devices
• Workflows and Handoff

Monorepo map

flowchart TD
  A[Repo root] --> B[nuxt-frontend]
  A --> C[static-web-app/api]
  A --> D[database]
  A --> E[docs-site]
  A --> F[windows-desktop-gateway]
  A --> G[esp32-gateway]
  A --> H[ble-scanner]
  A --> I[archived]

  B --> B1[Nuxt 3 UI]
  B --> B2[Capacitor Android/iOS shell]
  B --> B3[Public docs output]

  C --> C1[HTTP routes]
  C --> C2[IoT/Event ingestion]
  C --> C3[Emergency services]

  D --> D1[Migrations]
  D --> D2[Seeds]

  F --> F1[Windows service]
  F --> F2[MSI packaging]
  F --> F3[Desktop gateway tests]

Read this first for handoff

1. Start with Project Status for the active/legacy split.
2. Use Onboarding to get a fresh clone running.
3. Use Architecture and Data and Business Logic to understand system behavior.
4. Use Workflows and Handoff before changing deployment, mobile, desktop, or docs flows.