Onboarding

Prerequisites

Install only the toolchains needed for the areas you will touch:

Area	Required tools
General web/docs work	Node.js 20+ or 22, npm
Local API	Azure Functions Core Tools v4
Docker stack	Docker + Docker Compose
Windows desktop gateway	.NET 8 SDK, Windows build environment
Android mobile	Java 17, Android SDK, Capacitor CLI
iOS mobile	Xcode + CocoaPods/Capacitor toolchain on macOS
ESP32 gateway	PlatformIO / ESP-IDF toolchain

Fresh clone bootstrap

From the repo root:

npm install
npm install --prefix nuxt-frontend
npm install --prefix static-web-app/api
npm install --prefix docs-site
npm install --prefix database

Optional project installs:

npm install --prefix ble-scanner

Environment files

Root

Copy the local default environment if you are using Docker or local emulators:

cp .env.example .env

The checked-in .env.example defaults work out of the box with the Docker stack:

Variable	Default	Purpose
POSTGRES_USER	pareto	PostgreSQL user
POSTGRES_PASSWORD	pareto123	PostgreSQL password
POSTGRES_DB	pareto_anywhere	Database name
NUXT_PUBLIC_API_URL	http://localhost:7071/api	Frontend → API base URL
NUXT_PUBLIC_WS_URL	ws://localhost:7071	Frontend WebSocket URL
FUNCTIONS_WORKER_RUNTIME	node	Azure Functions runtime
FUNCTIONS_WORKER_RUNTIME_VERSION	22	Node version for Functions
AzureWebJobsStorage	Azurite emulator connection string	Local storage emulation
PGADMIN_EMAIL	admin@pareto.local	pgAdmin login (optional)
PGADMIN_PASSWORD	admin	pgAdmin password (optional)

API and Azure-specific secrets

Additional environment variables are read directly by runtime code and deployment workflows, including:

• PostgreSQL connection strings (POSTGRESQL_CONNECTION_STRING)
• App auth secret (TOKEN_SECRET) for issuing API JWTs
• Centrifugo realtime relay credentials (CENTRIFUGO_PUBLISH_URL, CENTRIFUGO_CLIENT_URL, CENTRIFUGO_HMAC_SECRET, CENTRIFUGO_API_KEY) — see Realtime Relay
• Twilio / Azure Communication Services settings for emergency comms
• Aruba Event Hub credentials (EVENT_HUB_CONNECTION_STRING, EVENT_HUB_NAME, EVENT_HUB_CONSUMER_GROUP)
• Desktop gateway site-detection environment lists

Keep these in local shell env, Azure App Settings, or workflow secrets. Do not commit them.

Start the app locally

Option A — direct app processes

Frontend:

cd nuxt-frontend
npm run dev

API:

cd static-web-app/api
npm start

Docs:

npm run docs:dev

Option B — Docker (with Makefile)

The repo includes a Makefile that wraps common Docker Compose operations:

make start        # docker-compose up -d (dev stack)
make start-prod   # start production-profile stack
make start-all    # start all profiles including optional tools
make stop         # docker-compose down
make logs         # follow all service logs
make logs-api     # follow API logs only
make db-shell     # psql into the running database
make db-backup    # dump database to a timestamped .sql file
make db-restore   # restore from a backup file
make db-migrate   # apply schema SQL
make test         # run all tests via docker exec
make clean        # remove containers and networks
make clean-all    # remove containers, networks, and volumes (destroys DB data)

Run make help for the full command list.

Docker Compose file variants

File	Purpose
docker-compose.yml	Default dev stack (PostgreSQL, Azurite, API, Nuxt, nginx, Redis)
docker-compose.dev.yml	Alternate dev overrides
docker-compose.prod.yml	Production-profile services
docker-compose.swa-test.yml	Azure Static Web Apps local emulation test stack

Shell start scripts

Script	Platform	What it does
start-dev.sh	Linux/macOS	Copies .env.example → .env if missing, then docker-compose up -d
start-local.sh	Linux/macOS	Similar local-mode startup
start-prod.sh	Linux/macOS	Production-profile Docker startup
start.ps1	Windows PowerShell	Copies .env.example → .env if missing, starts Docker stack
start.bat	Windows CMD	Batch equivalent of start.ps1

Optional tools profile (pgAdmin)

docker compose --profile tools up -d pgadmin

pgAdmin is available at http://localhost:5050 when started with the tools profile. Default credentials from .env.example: admin@pareto.local / admin.

Important current ports:

Surface	Mode	URL
Nuxt dev	direct	http://localhost:3006
Nuxt in Docker	container exposed	http://localhost:3005
nginx unified origin	Docker	http://localhost:8090
API	direct or Docker	http://localhost:7071/api
PostgreSQL	Docker	localhost:5433

First validation commands

From the repo root:

npm run lint        # runs lint:nuxt and lint:api
npm run test        # runs test:nuxt and test:api
npm run qa          # shorthand: lint then test

Known repo behavior:

• These commands fan out into nuxt-frontend/ and static-web-app/api/.
• A fresh clone without subproject installs will fail with missing tools such as eslint or vitest.
• That failure means dependencies are missing locally, not necessarily that the codebase is broken.

Where to start by role

If you need to...	Start here
Change operator/admin UI	nuxt-frontend/pages, components, composables
Change backend routes	static-web-app/api/src/routes
Change backend business logic	static-web-app/api/src/services
Change schema or seed data	database/migrations, database/load-seed.js
Change docs	docs-site/
Change Windows gateway behavior	windows-desktop-gateway/DesktopGateway.Core and DesktopGateway.Agent
Change mobile shell behavior	nuxt-frontend/capacitor.config.ts, android/, ios/, mobile layouts/views
Change BLE utility devices	esp32-gateway/, ble-scanner/

First-week checklist

1. Install all subproject dependencies.
2. Run the root lint/test scripts once.
3. Read Project Status and Architecture.
4. Read the existing operator docs under /guide/ to understand the user-facing model.
5. Confirm whether your task touches any protected files in .claude/LOCKS.md.
6. If working on deployment, read the GitHub workflows and deployments/main.bicep before editing code.