Workflows and Handoff

Common developer workflows

Change frontend UI

cd nuxt-frontend
npm run lint
npm run test:unit
npm run build

Change backend route or service

cd static-web-app/api
npm run lint
npm test

Change database schema

cd database
npm run migrate:status
npm run migrate

Change docs

cd docs-site
npm run build

Build mobile or desktop deliverables

cd nuxt-frontend
npm run cap:sync

cd ../windows-desktop-gateway
dotnet build DesktopGateway.Msi/DesktopGateway.Msi.wixproj --configuration Release

Code style and syntax by area

Area	Style
Nuxt/Vue/TypeScript	Prettier-managed: no semicolons, single quotes, 2 spaces, width 100
Nuxt templates	PascalCase component tags, Composition API, typed script setup
API JavaScript	Follow existing file-local CommonJS style; semicolons and 4-space indentation are common
C# desktop gateway	Nullable enabled, file-scoped namespaces, standard .NET 8 worker conventions
SQL migrations	Add new numbered migrations; do not rewrite applied migration history

Root QA and utility scripts

Command	What it runs
npm run lint	lint:nuxt + lint:api
npm run test	test:nuxt + test:api
npm run qa	lint then test — full pre-merge check
npm run docs:dev	VitePress dev server for the docs site
npm run docs:build	Build VitePress → nuxt-frontend/public/docs/
npm run copilot:commit	Runs scripts/git-commit-push.sh (used by automated tooling)

Deployment workflows already in the repo

azure-swa-nuxt.yml — main frontend + API deploy

Triggers:

• Push to main when nuxt-frontend/**, static-web-app/api/**, or the workflow file changes
• workflow_dispatch (manual, with optional reason)

Path-change detection: uses dorny/paths-filter so docs-only changes only rebuild the docs step, not the full Function App deploy.

What it does:

1. Builds VitePress docs → nuxt-frontend/public/docs/
2. Builds Nuxt with NITRO_PRESET=azure
3. Deploys Azure Static Web App
4. Deploys standalone Azure Function App
5. Applies pending database migrations

Required secrets/environment (Azure): AZURE_STATIC_WEB_APPS_API_TOKEN, AZURE_FUNCTIONAPP_PUBLISH_PROFILE, and any runtime secrets (DB connection string, TOKEN_SECRET for app auth, CENTRIFUGO_PUBLISH_URL / CENTRIFUGO_CLIENT_URL / CENTRIFUGO_HMAC_SECRET / CENTRIFUGO_API_KEY for the self-hosted realtime relay, Twilio / ACS credentials for emergency comms, Aruba Event Hub connection string) configured in Azure App Settings. The legacy WebPubSubConnectionString / web_pub_sub_hub_name / IOT_HUB_* settings are retained during the migration soak period (see docs/deployment/realtime-migration.md) and will be removed in a follow-up decommission PR.

mobile-build.yml — Android APK

Triggers:

• Push to main or feature branches when mobile-relevant files change (android/**, ios/**, capacitor.config.ts, mobile layouts, useAuth.ts)
• Tags matching mobile/v* → full release with version from tag
• workflow_dispatch with version and prerelease inputs

What it does: Installs Node 20, Java 17, syncs Capacitor, builds a debug APK, and creates a GitHub release artifact. iOS continuation is documented as a manual Xcode step.

desktop-gateway-build.yml — Windows MSI

Triggers:

• Push when windows-desktop-gateway/** or the workflow file changes
• Pull requests touching those paths
• Tags matching desktop-gateway/v* → MSI published as GitHub release
• workflow_dispatch

What it does: Restores .NET 8 packages, runs DesktopGateway.Core.Tests, builds the agent, builds the MSI installer, and uploads the MSI artifact. On tag events, creates a GitHub release with the MSI attached.

Release tag conventions:

• Frontend/API: push to main deploys automatically
• Mobile release: git tag mobile/v1.2.0 && git push origin mobile/v1.2.0
• Desktop gateway release: git tag desktop-gateway/v1.2.0 && git push origin desktop-gateway/v1.2.0

Handoff checklist

• [ ] Confirm which runtime path is authoritative for the task: direct local, Docker, Azure, mobile, or desktop gateway
• [ ] Confirm all needed subproject dependencies are installed
• [ ] Check .claude/LOCKS.md before editing protected files
• [ ] Review nuxt.config.ts before changing routing, auth, docs hosting, caching, or deployment behavior
• [ ] Review static-web-app/api/src/functions/index.js and affected route/service modules before backend edits
• [ ] Add new database behavior through a new migration, not by altering history
• [ ] Rebuild docs after docs changes so nuxt-frontend/public/docs stays current
• [ ] Review corresponding workflow files before changing build or release behavior

Known current-state caveats

• Root lint/test commands fail in a fresh clone until child-project dependencies are installed.
• Port usage differs between direct local dev and Docker.
• Auth provider: Okta SSO is active via nuxt-oidc-auth. Auth0 has been removed.
• Mobile distribution is not store-ready from repo state alone.
• Some high-risk files are intentionally lock-protected because prior regressions were costly.

Recommended reading order for a new owner

1. README.md
2. this developer handbook
3. /guide/ operator docs
4. nuxt-frontend/nuxt.config.ts
5. static-web-app/api/src/functions/index.js
6. database/migrations/
7. deployment workflows and deployments/main.bicep
8. BLE RTLS Positioning System.md for deeper RTLS context