⚡ Developer Quick Reference

Essential commands, key files, environment setup, and common gotchas

🏠 Home 🏗️ Architecture 📖 Framework 🗺️ User Journeys 🚀 SDLC

💻 Common Commands

Start Dev Server

npm start

Starts Angular dev server on port 4202

Production Build

npm run build:prod

Output: dist/solomon-app/browser

Deploy to Firebase

npm run deploy

Builds + deploys (SSL bypass included)

Start Emulators

npm run emulators

Emulator UI at http://localhost:4000

Production Preview

npx ng serve --configuration production --port 4202

Run locally with prod config

Deploy Functions Only

NODE_TLS_REJECT_UNAUTHORIZED=0 firebase deploy --only functions

For voice ID or Cloud Function changes

SSL Bypass Required: This machine has SSL certificate issues. All Firebase CLI commands that hit Google APIs need NODE_TLS_REJECT_UNAUTHORIZED=0 prepended.

🔧 Firebase Configuration

# Project
Project ID:    solomon-3ead2
Project Number: 756977799377

# Sites
App:       https://solomon-3ead2.web.app
Docs:      https://solomon-docs.web.app

# Service Account
SA:  firebase-adminsdk-fbsvc@solomon-3ead2.iam.gserviceaccount.com

# Functions Runtime
Runtime:  Node.js 20

Hosting Targets

Solomon uses dual hosting targets defined in .firebaserc:

app → solomon-3ead2 — the main Angular application (dist/solomon-app/browser)
docs → solomon-docs — this documentation site (docs/)

📂 Key Files

package.json

Dependencies + npm scripts (Angular 19, Firebase 11)

angular.json

Build config, lazy loading, budget limits

firebase.json

Hosting targets, Firestore/Storage rules, emulators

.firebaserc

Project + target mapping (app + docs)

src/app/app.routes.ts

Route definitions, lazy-loaded, guarded

functions/src/index.ts

Cloud Functions: chat, TTS, session mgmt, Stripe

Core Services

Service	Purpose
`AuthService`	Sign-in/up, user profiles, role-based access
`SessionService`	CRUD for counseling sessions, couples/individual modes
`MessageService`	Real-time message stream, sequence ordering
`AiService`	Wraps Cloud Function `chat` (5-min timeout, 2-min client)
`EncryptionService`	AES-256-GCM encrypt/decrypt for messages
`TtsService`	ElevenLabs streaming TTS via Cloud Function
`CounselorService`	Counselor profiles, annotations, assignments
`InviteService`	Couples invite workflow
`SubscriptionService`	Stripe subscription management
`PdfExportService`	jsPDF-based session export

🗄️ Firestore Collections

Collection	Purpose
`userProfiles`	User identity, denomination, profile context
`counselingSessions`	Session metadata, participants, status
`chatMessages`	Encrypted conversation history, sequence-ordered
`sessionKeys`	AES-256-GCM encryption keys per session
`sessionInvites`	Couples partner invite tokens (7-day expiry)
`counselorAnnotations`	Pastoral notes on AI messages, encrypted
`counselorChats`	Direct messages between counselor & counselee
`counselorApplications`	Counselor approval workflow
`counselorSubscriptions`	Stripe subscription state
`sessionGuidedPrompts`	Counselor-seeded prompts for session openers

🔑 Environment Variables

# Cloud Run (set via functions/.env in CI, NOT firebase.json secrets[])
ANTHROPIC_API_KEY       # Claude API for AI counseling
ELEVENLABS_API_KEY      # ElevenLabs for TTS voice synthesis
STRIPE_SECRET_KEY       # Stripe for counselor subscriptions
STRIPE_WEBHOOK_SECRET   # Stripe webhook verification

# Local Development
NODE_TLS_REJECT_UNAUTHORIZED=0  # SSL bypass for Firebase CLI

Important: Do NOT use secrets: ["ANTHROPIC_API_KEY"] in firebase.json or onCall() — this causes deploy-time permission errors. Do NOT use gcloud run services update --update-env-vars — it creates a separate revision that gets wiped on the next Firebase deploy. Instead, write secrets to functions/.env in CI before firebase deploy.

⚠️ Common Gotchas

🔒

SSL Certificate Errors on Firebase CLI

All Firebase commands that hit Google APIs fail without SSL bypass on this machine.

Fix: Prepend NODE_TLS_REJECT_UNAUTHORIZED=0 to every Firebase CLI command.

🔄

auth.currentUser is null on page refresh

Race condition — Firebase Auth hasn't restored the session yet when components initialize.

Fix: Check authService.currentUserProfile first, fallback to getUserProfile(auth.currentUser.uid).

📦

Firebase SDK version mismatch

@angular/fire@19 requires firebase@11. Using firebase@10 causes "Type does not match the expected instance" at runtime.

Fix: npm install firebase@11

📅

Firestore Timestamp in templates

Firebase 11 returns Timestamps, not JS Dates. Angular's | date pipe throws NG02100 on raw Timestamp.

Fix: Add toDate(v: any): Date { return v?.toDate ? v.toDate() : v; } to component and use toDate(field) | date:... in templates.

🚫

firebase.json secrets[] causes permission errors

Using secrets: ["ANTHROPIC_API_KEY"] in firebase.json triggers deploy-time Secret Manager permission errors. Using gcloud run services update creates a revision that gets wiped on next deploy and fails when the old container image is garbage-collected.

Fix: Write secrets to functions/.env in CI before firebase deploy. Firebase 2nd-gen functions natively load .env files.

📁

SCSS imports fail without includePaths

SCSS token imports like @use 'styles/tokens' won't resolve without the include path configured.

Fix: Ensure angular.json has stylePreprocessorOptions: { includePaths: ["src"] }.

📊 Build Budgets

Initial bundle: 1.5 MB warning / 4 MB error
Component styles: 15 KB warning / 45 KB error
Current initial bundle: ~622 KB (after firebase 12 → 11 downgrade)