Getting Started

Tech Stack

• Frontend: React 18 + TypeScript, Vite, Firebase Hosting
• Cloud Functions: Firebase Cloud Functions (Node.js 22, TypeScript, Express)
• Voice/Chat API: Cloud Run (plain JavaScript, no TypeScript)
• Shared Package: @humanlike/shared (TypeScript types, helpers, Firestore paths)
• Database: Firestore (multi-tenant)
• Auth: Firebase Auth with custom claims
• Third-party: OpenAI (Realtime + Chat Completions), Twilio, Google Calendar, Stripe

Monorepo Layout

web/              — React + Vite dashboard & portal (TypeScript)
functions/        — Firebase Cloud Functions (TypeScript, Express routers)
services/api/     — Cloud Run voice/chat API (plain JavaScript, no TS)
shared/           — @humanlike/shared package (TypeScript) — types, helpers, verticals
docs/             — VitePress documentation site + prompt templates
scripts/          — Seed scripts, check scripts

Build Order

shared must build before functions or web.

Both web and functions import from @humanlike/shared, which requires a build step to emit JavaScript from TypeScript.

Key Commands

# Install dependencies
pnpm install

# Build shared (must run first)
pnpm --filter @humanlike/shared build

# Start web dashboard dev server
pnpm --filter @humanlike/web dev

# Start Cloud Run API dev server (plain Node, no build step)
node services/api/serve.js

# Seed prompts to Firestore
GOOGLE_APPLICATION_CREDENTIALS=path/to/key.json node scripts/seed-prompts.mjs

# Check scripts (zero-dep, exit 0 = pass, 1 = error, 2 = warnings)
# All support: --staged, --last-commit, --base <ref>
node scripts/check-deploy-targets.mjs     # which CI jobs will trigger
node scripts/check-typesync.mjs           # JS field access vs TS types
node scripts/check-rules-sync.mjs         # firestore.rules vs schema doc vs types
node scripts/check-prompt-vars.mjs        # template {{vars}} vs context sources

# Documentation
pnpm docs:dev       # local docs dev server
pnpm docs:build     # production docs build

Deployment

Push to main triggers path-based CI:

Changed Path	Deploys
web/** or shared/**	Web app to Firebase Hosting
functions/** or shared/**	Cloud Functions
services/api/**	API to Cloud Run
firestore.rules or firestore.indexes.json	Firestore rules

Path filters are defined in scripts/deploy-paths.json.

Critical Gotchas

• services/api/ is plain JavaScript -- no TypeScript, no build step, no type imports. Everything else is TypeScript.
• shared must build first -- web and functions import from @humanlike/shared which needs pnpm --filter @humanlike/shared build.
• Prompt workflow -- prompts live as Markdown in docs/prompts/, tool defs as JSON in docs/prompts/tools/. Edit those files, then run seed-prompts.mjs to push to Firestore. The API reads from Firestore at runtime.