Developer Setup & Project Conventions

Owner(s): CrowdPM team | Last updated: 2026-03-08 | Status: Production

Developer Setup & Project Conventions

Purpose

This page is the wiki-level onboarding guide for contributors. The repository docs remain the operational source for exact commands and environment details, but this page should be sufficient to explain:

• how the repo is organized;
• what local setup requires;
• what to expect from pnpm dev;
• which environment files matter;
• which conventions contributors must follow.

Repository layout

Top-level directories and files of interest:

• frontend/ — React + Vite application, map UI, dashboard UI, Firebase web config.
• functions/ — Firebase Functions backend, Fastify API, pairing logic, ingest pipeline, tests.
• shared-types/ — shared types/utilities used across workspaces.
• scripts/ — local helper scripts such as the device emulator and simulation helpers.
• examples/esp32/CrowdPMNodeESP32/ — hardware-oriented example node code.
• docs/ — operational runbooks for local development, demo deployment, and production release.
• infra/ — CI/CD and infrastructure automation assets.
• firestore.rules, storage.rules, firebase.json — security rules and emulator/deploy targets.

Prerequisites

Install these once per workstation:

• Node.js 24.x
• pnpm 10.x
• Firebase CLI (firebase login required)
• Python 3.12
• Java JDK 25
• Git 2.34+
• Google Cloud CLI (optional but useful for broader Google Cloud work)

Core local setup flow

From the repository root:

git clone git@github.com:denuoweb/CrowdPMPlatform.git
cd CrowdPMPlatform
pnpm install
cp .firebaserc.example .firebaserc
cp frontend/.env.example frontend/.env.local
cp functions/.env.example functions/.env.local

Firebase project convention for local work

The local emulator workflow is intentionally pinned to a fake/demo-style local alias so contributors do not accidentally point routine development at a real Firebase project.

Important convention:

• use the local/demo alias for emulator work only;
• do not treat the local alias as a deploy target.

Environment files

frontend/.env.local

Expected values include:

• VITE_API_BASE
• VITE_GOOGLE_MAPS_API_KEY
• VITE_GOOGLE_MAP_ID
• VITE_FIREBASE_API_KEY
• VITE_FIREBASE_AUTH_DOMAIN
• VITE_FIREBASE_PROJECT_ID
• VITE_FIREBASE_STORAGE_BUCKET
• VITE_FIREBASE_MESSAGING_SENDER_ID
• VITE_FIREBASE_APP_ID
• VITE_FIREBASE_AUTH_EMULATOR_HOST (optional; used for local auth emulator)
• VITE_SMOKE_TEST_USER_EMAIL

Conventions:

• restart the Vite dev server after changing frontend env variables;
• never commit .env.local files;
• ensure VITE_API_BASE points to the correct environment.

functions/.env.local

Expected values include:

• DEVICE_TOKEN_PRIVATE_KEY
• DEVICE_ACTIVATION_URL
• DEVICE_VERIFICATION_URI
• DEVICE_TOKEN_ISSUER
• DEVICE_TOKEN_AUDIENCE
• DEVICE_ACCESS_TOKEN_TTL_SECONDS
• DEVICE_REGISTRATION_TOKEN_TTL_SECONDS
• DEV_AUTH_USER_EMAIL
• DEV_AUTH_USER_PASSWORD
• DEV_AUTH_USER_DISPLAY_NAME
• SMOKE_TEST_USER_EMAIL

Conventions:

• use an Ed25519 private key in PKCS8 PEM form for DEVICE_TOKEN_PRIVATE_KEY;
• change activation/verification URLs only when explicitly testing alternate flows;
• local auth emulator test credentials may be overridden here if needed.

functions/.secret.local

This file is required for functions that declare secrets via defineSecret.

Important convention:

• the Firebase Functions emulator will attempt to read Secret Manager if local secret overrides are absent;
• without functions/.secret.local, local startup can fail with secret-access errors;
• keep this file out of version control.

Typical local use:

cat > functions/.secret.local <<'EOF'
DEVICE_TOKEN_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----
EOF

What pnpm dev does

Running the following from the repo root starts the normal local stack:

pnpm dev

Expected components:

• frontend Vite dev server on http://localhost:5173
• Firebase Emulator Suite on the local project alias
• functions TypeScript build watcher
• Emulator UI on http://localhost:4000

Default local login

The local development guide documents a seeded default auth-emulator user.

Default credentials:

• email: smoke-tester@crowdpm.dev
• password: crowdpm-dev

These can be overridden using the DEV_AUTH_USER_* variables in functions/.env.local.

Verification checklist after setup

After local startup, verify at least the following:

Health endpoint

curl http://127.0.0.1:5001/demo-crowdpm/us-central1/crowdpmApi/health

Expected response:

{ "ok": true }

Frontend

Open http://localhost:5173 and confirm the app loads.

Emulator UI

Open http://localhost:4000 and confirm Firestore, Storage, Auth, and Functions are visible.

Device and simulation helper scripts

The root workspace includes helper scripts that contributors should know exist:

• pnpm device:pair
• pnpm device:simulate:osu

Use cases:

• re-running or debugging device onboarding / ingest flows;
• exercising simulated data paths outside the main UI smoke test;
• validating ingest behavior after backend changes.

When documenting exact script arguments, prefer the repository README or source-level comments if the invocation changes.

Smoke-test workflow

When ingest logic changes, run the documented smoke test:

1. start the local stack with pnpm dev;
2. sign in with the local test user;
3. open the User Dashboard tab;
4. click Run Smoke Test;
5. confirm the device is seeded, paired, and a payload is submitted;
6. confirm resulting batch metadata and map rendering behavior;
7. optionally inspect Firestore, Storage, and Functions logs in the emulator UI.

Development conventions

1. Never commit local secrets

Do not commit:

• .env.local
• .secret.local
• downloaded service account JSON files
• any copied private keys

2. Run quality gates before pushing

At minimum, contributors should run:

pnpm lint
pnpm -r build

Run tests relevant to the changed workspace as appropriate.

3. Keep docs synchronized

Any change to one of the following usually requires doc updates:

• route names or auth behavior;
• env variables;
• pairing flow;
• smoke-test behavior;
• deployment process.

Update:

1. source code;
2. repo docs / examples;
3. wiki pages.

4. Use the emulator-first workflow

Do not make normal contributor onboarding depend on live cloud resources or real hardware unless there is a clearly documented reason.

5. Preserve role terminology

Use the role names that match the code and API surface:

• guest
• authenticated user/device owner
• moderator
• super admin

Avoid collapsing everything into a vague single “admin” role in docs.

Related pages

• System Design (with diagrams)
• Demo Scripts
• Deployment Guide
• Team Standards for Development