DIAL — Developer Quick Reference

🖥️ Local Development

Serve the app (production config)

# From the dora-tma project root
npx ng serve --configuration production --port 4201
# App: http://localhost:4201

With Firebase Emulators

firebase emulators:start
# Emulator UI: http://localhost:4000
# Firestore:   http://localhost:8080
# Auth:        http://localhost:9099

Build for production

npm run build:prod
# Output: dist/dora-tma/browser/

🔥 Firebase Commands

Deploy (requires SSL bypass on this machine)

# Full deploy (hosting + Firestore rules + Functions)
NODE_TLS_REJECT_UNAUTHORIZED=0 firebase deploy

# Hosting only
NODE_TLS_REJECT_UNAUTHORIZED=0 firebase deploy --only hosting

# Functions only
NODE_TLS_REJECT_UNAUTHORIZED=0 firebase deploy --only functions

Build Cloud Functions

cd functions && npm install && npm run build
# Compiled output: functions/lib/

Set ANTHROPIC_API_KEY on Cloud Run

gcloud run services update FUNCTION_NAME \
  --update-env-vars ANTHROPIC_API_KEY=sk-ant-... \
  --region us-central1
# Do NOT set this in firebase.json secrets[] — causes deploy-time 403s

Re-authenticate Firebase CLI

NODE_TLS_REJECT_UNAUTHORIZED=0 firebase login --reauth

📦 npm Scripts

Script	What it does
npm run build:prod	Production Angular build with optimization
npm run build	Development build (no optimization)
npm test	Run Karma/Jasmine unit tests
npm run lint	ESLint check across the project
npm install	Install dependencies — use this in CI, not `npm ci`

🗺️ Route Map

Route	Guard	Description
/auth/signin	noAuthGuard	Sign-in page
/auth/signup	noAuthGuard	Registration page
/auth/reset	noAuthGuard	Password reset
/invite/:token	noAuthGuard	Org invite link — auto-joins org on sign-up
/dashboard	authGuard	Role-aware dashboard (member or admin view)
/assessment/new	authGuard	Start a new assessment
/assessment/:id/capabilities	authGuard	Capability scoring wizard
/assessment/:id/summary	authGuard	Radar chart + composite score
/assessment/:id/results	authGuard	Per-capability AI assessments + recommendations
/history	authGuard	Past assessments list
/compare	adminGuard	Team comparison view
/org/insights	adminGuard	Org-level AI insights

🔑 Environment Variables

Variable	Where set	Description
ANTHROPIC_API_KEY	Cloud Run (gcloud)	Anthropic API key for Claude Sonnet calls in Cloud Functions
WIF_PROVIDER	GitHub Actions secret	Workload Identity Federation provider resource name
ANTHROPIC_API_KEY	GitHub Actions secret	Separate key for AI release notes generation in CI

📁 Key Files

functions/src/index.ts

All 4 Cloud Functions: assessCapability, generateRecommendations, chatAboutRecommendations, generateInsights

src/app/data/capability-definitions.ts

Source of truth for all 20 DORA capabilities with maturity level descriptions (Emerging/Advancing/Leading)

src/app/app.routes.ts

All route definitions with lazy loading and guard assignments

src/app/services/

Core services: AuthService, AssessmentService, OrganizationService, AiService, PdfExportService, InsightsService

firestore.rules

Firestore security rules — org/team/assessment access control

firebase.json

Dual hosting targets: dial-app (Angular SPA) and docs (static docs site)

angular.json

Build config, lazy loading settings, budget limits, SCSS include paths

.github/workflows/deploy-and-release.yml

5-job CI/CD pipeline: version → build → deploy → release-notes → create-release

⚠️ Common Gotchas

🔒

Firebase CLI SSL errors on this machine

This machine has SSL certificate issues that block Firebase CLI API calls. All firebase commands must be prefixed with the SSL bypass env var.

NODE_TLS_REJECT_UNAUTHORIZED=0 firebase deploy

🔧

Firebase Tools must be pinned to v13.15.2

v13.15.3+ introduced a mandatory extensions API check that always 403s in CI because firebaseextensions.instances.list is not included in any standard IAM role. Downgrading to v13.15.2 is the only fix.

npm install -g firebase-tools@13.15.2

📅

Firestore Timestamps in Angular templates

Firebase 11 returns raw Firestore Timestamp objects, not JS Dates. Angular's | date pipe throws NG02100 on a raw Timestamp. Add a toDate() helper to the component and call it in the template.

toDate(v: any): Date {'{'} return v?.toDate ? v.toDate() : v; {'}'}

🔄

auth.currentUser is null on page refresh

Firebase Auth is async — auth.currentUser is null immediately after a page load before the auth state is restored. Pattern: check authService.currentUserProfile first, then fall back to getUserProfile(auth.currentUser.uid) inside an authStateReady() callback.

📦

Use npm install, not npm ci, in CI

The npm registry intermittently returns 403/404 for older pinned transitive deps (yallist, minimatch, core-util-is). npm ci hard-fails on these; npm install is resilient. Also: lock files generated on Node 25 locally are missing Node 20 optional deps, causing npm ci to fail with "lock file out of sync".

npm install # not npm ci

🔐

ANTHROPIC_API_KEY — set via gcloud, not firebase.json

Using secrets: ["ANTHROPIC_API_KEY"] in firebase.json causes deploy-time 403 permission errors. Instead, set the key directly on the Cloud Run service using gcloud run services update --update-env-vars.

🌐

firebase@11 required with @angular/fire@19

If firebase@10 is in package.json, you get a runtime error: "Type does not match the expected instance. Did you pass a reference from a different Firestore SDK?" Fix: upgrade to firebase@11.

npm install firebase@11

☁️ Firebase Project

Setting	Value
Project ID	dora-tma
App site	https://dial-assessment.web.app
Docs site	https://dial-docs.web.app
Auth	Email/password
Functions runtime	Node.js 20
Service account	firebase-adminsdk-fbsvc@dora-tma.iam.gserviceaccount.com