Humanlike Platform Architecture

AI receptionist platform for healthcare practices.

Architecture

Phone (Twilio) ──→ Cloud Run API ──→ OpenAI Realtime (WebSocket)
Browser mic    ──→ OpenAI Realtime (direct WebSocket from client)
Portal chat    ──→ Cloud Run API ──→ OpenAI Chat Completions

Cloud Run API
  ← Receives tool execution requests
  → Runs tools (caller lookup, calendar, SMS, knowledge base)
  → Returns results to voice/chat session

Components

1. Web App (web/)

React SPA on Firebase Hosting.

• Firebase Auth (Google OAuth, email/password)
• Onboarding wizard (business profile, AI persona, knowledge base)
• Dashboard for business configuration
• Voice client at /voice — GPT-4o Realtime or Moshi
• Portal chat at /portal/:slug — AI chat for visitors (OpenAI Chat Completions)
• Staff management, knowledge base articles, calendar integration

2. Cloud Functions (functions/)

Firebase Cloud Functions (Node.js 22). Five Express API modules:

• adminApi — admin dashboard, business management, role management
• calendarApi — Google Calendar OAuth flow and sync
• siteApi — static site generation, publishing, website import
• staffApi — staff invitation and management
• stripeApi — subscription billing

3. API Service (services/api/)

Tool execution API on Cloud Run. Stateless.

Key endpoints:

• POST /api/token — OpenAI ephemeral token creation
• GET/POST /api/tools — tool definitions and execution
• POST /api/chat — OpenAI Chat Completions proxy (streaming)
• GET /api/prompt — rendered system prompt for a business
• GET /api/portal/resolve — resolve slug to business
• POST /api/portal/tools — tool execution for portal chat
• POST /api/twiml — Twilio voice webhook
• WS /api/media-stream — Twilio Media Stream handler

Tools: verify_caller, send_verification_code, check_verification_code, check_availability, book_appointment, lookup_appointment, cancel_appointment, search_knowledge, transfer_call, send_sms, end_call, flag_caller, send_portal_link

4. Shared Types (shared/)

@humanlike/shared workspace package. TypeScript types, Firestore path builders, constants.

Infrastructure

• Firebase Hosting — web app
• Firebase Cloud Functions — backend APIs
• Cloud Run — API service (Docker container)
• Firestore — multi-tenant business data
• Cloud Storage — static site hosting (humanlike-sites bucket)
• Firebase Auth — authentication with custom claims (sysAdmin, biz: { id, role, ver }, visitor)

Third-Party Integrations

• OpenAI — Realtime API (voice), Chat Completions (portal), TTS
• Google Calendar — appointment scheduling via OAuth
• Stripe — subscription billing
• Twilio — phone number provisioning, inbound calls, SMS

Deep Dives

• Prompt System — template pipeline, variable injection, caching
• Twilio Call Flow — inbound call → AI provider → tool execution → interaction logging
• Tool System — definitions, conditional inclusion, execution, adding new tools
• Chat Architecture — static site chat vs portal chat
• Firestore Schema — collections, types, security rules, path builders

Clinic Safety Guardrails

1. No diagnosis, no treatment recommendation, no medication dosing.
2. Allowed intents only: book/reschedule/cancel, clinic info, pre-approved preparation instructions.
3. Mandatory escalation: chest pain, breathing issues, uncontrolled bleeding, severe pain, pediatric emergencies, suicidal/self-harm language.
4. Emergency signals: instruct caller to contact emergency services, transfer to human.
5. All transcripts persisted for QA and medico-legal review.