evaldoc 1.0.0

package/SRS.md

@@ -0,0 +1,448 @@
+# EvalDoc Link-First — Software Requirements (Firebase + Node.js)
+
+**Version:** 7.3
+**Product:** Personal Healthcare AI Link Platform (Link-as-a-Service)
+**Stack:** Firebase (Auth + Firestore + Storage), Node.js/Express backend on Cloud Run (Firebase App Hosting)
+**Goal:** Zero-friction provider link → patient chat → safe responses → analytics
+**Primary buyer:** Individual clinicians and clinics worldwide (B2B SaaS)
+
+> **Changelog (v7.2 → v7.3) — review remediation:**
+> - **Single canonical backend.** `server.js` (Cloud Run via `apphosting.yaml`) is the one backend and owns `/api`. The stale parallel Cloud Function (`functions/src/index.js`) and its `firebase.json /api/** → api` rewrite have been removed (they were 3 months / 45 commits behind and missing every recent feature and security fix). `firebase.json` now only manages Firestore/Storage rules + indexes + static hosting.
+> - **Credit-card numbers are now redacted** (were detected only) — §7.4 claim is now accurate.
+> - **Documentation corrected**: authenticated `/api/patient/*` subsystem documented (§2, §4.2, §13); `analyticsDaily` fields corrected (§5.2); §13 API catalog completed; stale "MVP excludes clinics" bullet reconciled.
+> - **Middleware extraction**: `requireProvider` / `requireMembership(permission)` / `sendError` guards centralize auth+ownership+RBAC (adopted across org + self-serve routes; incremental rollout continuing).
+> - **Scalability**: `trust proxy` for correct client IP; parallelized org-analytics fan-out.
+> - **Tooling**: ESLint + Prettier + GitHub Actions CI + Firestore-emulator test scaffold.
+>
+> **Changelog (v7.1 → v7.2) — security & reliability hardening:**
+> - Fixed three confirmed-exploitable auth bugs: missing admin gate on platform analytics (any doctor could read all providers), unauthenticated satisfaction IDOR (anyone could rate/fabricate conversations), and subscription-cancel IDOR (a doctor could cancel any subscription).
+> - Added fail-closed platform-admin allowlist, constant-time internal-key comparison, request-correlation ids, a process-level async fault net, and defensive LLM response parsing.
+> - New **Section 15 — Security & Reliability Controls** documents the full posture.
+> - New **Section 16 — Next Features (prioritized)**.
+>
+> **Changelog (v7.0 → v7.1):**
+> - **Multi-provider clinics (Phase A–D) implemented**: organizations, RBAC (owner/admin/clinician/staff), email invites with seat enforcement, clinic-wide inbox and aggregate analytics. Added non-breakingly via a lazy "personal org" so the solo flow is unchanged. Remaining: seat-quantity Stripe billing (Phase E) and the clinic admin UI.
+>
+> **Changelog (v6.2 → v7.0)** — reflects the implemented product:
+> - Business model clarified: **B2B SaaS subscription is primary**; patient-pay is an optional per-provider add-on.
+> - New **preview status**: providers get an instant, shareable working link before verification completes.
+> - **Credential verification** is now a documented self-serve workflow (status endpoint, SLA, resubmit, preview fallback).
+> - **Guided onboarding checklist** replaces the blank-dashboard drop.
+> - **GDPR controls** added: data export (portability) and account deletion (erasure).
+> - **Internationalization (i18n)**: locale-aware safety/disclaimer text (6 locales).
+> - **Public pricing** surface added.
+> - REST API is now documented (Section 13), since the product exposes one.
+
+---
+
+## 0) Non-Negotiable Safety/Scope
+
+EvalDoc must **never**:
+
+* diagnose ("you have X", "you might have X")
+* prescribe or recommend treatment ("I recommend you try…")
+* provide dosing instructions
+* advise starting/stopping medicines
+* interpret medical images
+
+EvalDoc may:
+
+* provide general health information
+* provide medication facts + safety warnings (non-dosing)
+* answer clinic FAQs (hours, services)
+* appointment prep guidance
+* post-procedure general guidance (non-personalized)
+* escalate to urgent care when red flags appear
+
+**Fail-closed:** If uncertain → refuse or escalate. Safety text is localized to the provider's `locale` with English fallback.
+
+---
+
+## 1) MVP Definition (Strict)
+
+### MVP promise
+
+A provider gets a working link in **<5 minutes**:
+`evaldoc.com/<handle>`
+Patients open it and chat **without login**.
+
+**Activation guarantee:** A new provider reaches a **live preview link + functional dashboard immediately** after onboarding — billing and credential verification are *not* on the critical path to first value.
+
+### MVP includes
+
+1. Provider onboarding (signup → handle → branding → topics → **instant preview link**)
+2. Guided onboarding checklist (next-step guidance, no blank dashboard)
+3. Public link page (branded chat UI), preview-marked until verified
+4. Topic-controlled assistant (no free chat)
+5. Safety pipeline (input + output + escalation), localized
+6. Conversation logging + safety events
+7. Provider dashboard (usage, top questions, escalations)
+8. Share tools (QR code + copy templates)
+9. Self-serve account controls (data export, account deletion)
+10. Plan gating (Free tier limits + paid tiers)
+
+### MVP excludes (roadmap)
+
+* EHR integrations
+* Custom domains
+* Multi-provider clinic **admin UI** (the org/RBAC/invite API + data layer is built — see §11; only the dashboard screens and seat-quantity billing remain)
+* Real medical image understanding
+* Full UI translation (only safety-critical text is localized)
+
+---
+
+## 2) Roles
+
+* **Platform Admin** (EvalDoc ops) — credential verification, suspensions, platform analytics
+* **Organization** (clinic/practice) — a billing + membership boundary owning one or more providers
+  * **Owner** — billing, delete org, manage all members, full access
+  * **Admin** — manage members (not owner), org settings, clinic-wide inbox/analytics
+  * **Clinician** — own provider profile + own inbox, reply to patients
+  * **Staff** — triage/reply in assigned inboxes only (no clinical settings)
+* **Provider** (subscriber) — a clinician's public profile/link; belongs to an organization
+* **Patient/Visitor** — two supported modes:
+  * **Anonymous** (default) — chats via `/api/chat` with a browser session id, no login. This is the zero-friction MVP path.
+  * **Authenticated patient** (optional) — a logged-in patient account (`/api/patient/*`) with a profile and persistent threads, for providers who want returning-patient continuity. Requires Firebase Auth.
+
+---
+
+## 3) Core UX Flows (Must Build)
+
+### 3.1 Provider Onboarding (Target <5 minutes to a live preview link)
+
+1. Sign up / log in (Firebase Auth)
+2. Choose handle (unique)
+3. Add profile: name, specialty, country, locale
+4. Add branding: photo/logo + colors + welcome message
+5. Choose topics (checkbox)
+6. Upload medical license (for verification — does **not** block preview)
+7. **Provider is created in `preview` status → link works immediately**
+8. Share kit: link + QR + copy templates
+9. (Optional, later) Set up payments; (automatic) credential verification → switch to `published`
+
+### 3.2 Patient Flow (Zero friction)
+
+1. Patient opens `evaldoc.com/<handle>`
+2. Sees provider identity + disclaimers + emergency banner (a **preview notice** appears if unverified)
+3. Chooses topic (or system auto-detects)
+4. Chats (localized disclaimers/escalation)
+5. Optional rating at end
+
+### 3.3 Self-Serve Account Lifecycle
+
+* Check verification status + SLA at any time
+* Track onboarding completion via checklist
+* Export all data (JSON)
+* Delete account (cascading erasure) with explicit confirmation
+
+---
+
+## 4) Core Modules
+
+### 4.1 Link Resolver
+Maps `/<handle>` → provider config. Resolves `published` **and** `preview` providers (preview flagged to the client via `isPreview`). Renders branded chat UI.
+
+### 4.2 Conversation Service
+Anonymous sessions (browser session id). Stores conversations/messages. Enforces monthly chat limits by plan. An optional **authenticated-patient** path (`/api/patient/*`) provides logged-in patient accounts with persistent threads (see §13).
+
+### 4.3 Topic Engine (Strict)
+Only allowed topics. Each topic defines: system prompt, allowed/forbidden behaviors, disclaimer, escalation triggers.
+
+### 4.4 Safety Engine (Critical)
+Defense-in-depth: input checks (PII/PHI incl. credit-card, injection, prohibited medical requests, red flags), output checks (strip/deny unsafe content, enforce disclaimers, escalate), NER-assisted PII detection, always logs safety events. **Patient-facing refusal/escalation/disclaimer text is locale-aware.**
+
+### 4.5 LLM Connector
+Provider chain with **exponential-backoff retry** on transient errors (429/5xx/network). Topic prompts + provider metadata. Tight caps: max tokens, low temperature, short structured answers.
+
+### 4.6 Analytics Engine
+Aggregates chats/day, top topics, common questions, escalation + resolution rates, satisfaction, unique patients.
+
+### 4.7 Verification Service (Provider Credentials)
+Tracks `verificationStatus` (`pending`/`verified`/`rejected`). Exposes self-serve status + SLA + rejection reason + resubmit path. Verified is required for `published`; not required for `preview`.
+
+### 4.8 Account Service (GDPR)
+Data export (portability) and account deletion (erasure, cascading across provider/handle/threads/conversations/messages).
+
+### 4.9 Billing Service (Optional)
+B2B SaaS subscription (primary). Optional per-provider patient-pay add-on via Stripe Connect. Skippable; never blocks first value.
+
+### 4.10 Localization (i18n)
+`SUPPORTED_LOCALES = [en, es, fr, de, pt, ar]`. `normalizeLocale()` collapses region/script subtags. Safety-critical strings translated with English fallback.
+
+---
+
+## 5) Firestore Data Model
+
+### 5.1 `providers/{providerId}` (doc id = ownerUid)
+* `handle` (unique, indexed), `displayName`, `specialty`, `country`, `locale`
+* `photoUrl?`, `logoUrl?`, `brandPrimaryColor`, `brandSecondaryColor`, `welcomeMessage`
+* `contactInfo { phone?, email?, address? }`, `businessHours` (json)
+* `enabledTopics` (array)
+* `status` (`draft` | `preview` | `published` | `suspended`)
+* `verificationStatus` (`pending` | `verified` | `rejected`), `verificationRejectionReason?`
+* `licenseNumber?`, `certificateUrl?`, `certificateFileName?`
+* `plan` (`free` | `pro` | `clinic` | `enterprise`)
+* `monthlyChatLimit`, `monthlyChatCount`, `monthlyChatCountMonth`, `totalChatCount`, `totalEscalationCount`
+* Billing: `pricingModel?`, `paymentEnabled`, `perChatPrice?`, `subscriptionPrice?`, `currency?`, `stripeAccountId?`, `stripeOnboardingComplete`
+* `createdAt`, `updatedAt`
+
+### 5.2 `providers/{providerId}/analyticsDaily/{YYYY-MM-DD}`
+`chatCount`, `uniqueSessions` (array of session ids), `escalationCount`, `satisfactionSum`, `satisfactionCount` (average is derived, not stored), `topicCounts.{topic}`, `questionBuckets.{bucket}`, `updatedAt`
+
+### 5.3 `conversations/{conversationId}` & `threads/{threadId}`
+`providerId`/`doctorId`, `handle`, `sessionId`, `topic`, `isEscalated`, `escalationReason`, `triageCategory`, `status`, `satisfaction`, `createdAt`, `updatedAt` (+ messages subcollection)
+
+### 5.4 `safetyEvents/{eventId}`
+`providerId`, `conversationId`, `eventType` (`blocked_input`|`blocked_output`|`escalated`|`pii_detected`|`abuse`), `details`, `createdAt`
+
+### 5.5 `handles/{handle}`
+`providerId`, `createdAt` (unique reservation; released on account deletion)
+
+### 5.6 `waitlist/{id}`
+`email`, `approved`, `createdAt` (gate is env-toggleable via `WAITLIST_ENABLED`)
+
+### 5.7 `auditLogs/{id}`
+`action`, `actorId`, `actorType`, `resourceType`, `resourceId`, `meta`, `createdAt`
+
+### 5.8 `organizations/{orgId}` (multi-provider clinics)
+`ownerUid`, `name`, `type` (`personal` | `clinic`), `plan`, `seats`, `createdAt`, `updatedAt`
+* `organizations/{orgId}/members/{uid}`: `uid`, `email`, `role` (`owner`|`admin`|`clinician`|`staff`), `providerId?`, `status` (`active`|`invited`), `joinedAt`
+
+### 5.9 `memberships/{uid}`
+`orgId`, `role` — fast "which org is this user in" lookup (one active org per user in v1)
+
+### 5.10 `invitations/{token}`
+`orgId`, `email`, `role`, `token` (unguessable, single-use), `status` (`pending`|`accepted`|`revoked`|`expired`), `invitedBy`, `createdAt`, `expiresAt`
+
+---
+
+## 6) Topics (Hard-coded Keys)
+
+1. `medication_info_safety`
+2. `appointments_preparation`
+3. `general_health_info`
+4. `clinic_services_hours`
+5. `insurance_billing_faq`
+6. `post_procedure_guidance`
+
+Each ships with: system prompt template, disclaimer, forbidden content patterns, escalation triggers.
+
+---
+
+## 7) Safety Rules
+
+### 7.1 Always Block (Refuse)
+* diagnosis claims ("you have", "you might/may/could have", "this is likely")
+* treatment instructions ("take", "use", "apply", "start/stop medication", "I recommend you try")
+* dosing ("500mg", "twice daily", "dose", "how many tablets")
+* off-label suggestions ("not approved but", "try it for…")
+* medical image interpretation ("looks like pneumonia", "tumor")
+* prescriptions ("here is your prescription")
+
+### 7.2 Always Escalate (Emergency)
+chest pain/hurts/tightness/pressure, trouble/difficulty breathing, severe allergic reaction, swelling face/throat, fainting, seizure, stroke signs, severe bleeding, suicidal thoughts / self-harm / "feel like dying" / "kill myself", pregnancy + severe pain/bleeding, newborn/infant severe symptoms, unconsciousness, overdose, sudden vision loss.
+
+### 7.3 Output Constraints
+Conservative, non-alarming, no certainty claims, "seek professional care" on risk, **localized disclaimer footer always present**.
+
+### 7.4 PII/PHI
+Detect + redact: SSN, email, phone, street address, ZIP, DOB, **16-digit credit card**, plus NER-detected person/location/org entities.
+
+---
+
+## 8) Provider Dashboard
+
+1. **Overview**: usage, escalations, resolution rate, satisfaction, unique patients
+2. **Onboarding checklist**: step completion %, next action (hidden when complete)
+3. **Verification banner**: status, SLA, rejection reason + resubmit, preview reminder
+4. **Share**: preview/public link + QR + copy templates
+5. **Conversations**: anonymized transcripts (PII removed), search, export, delete
+6. **Settings**: branding, topics, contact info, business hours, notifications
+7. **Account**: export data, delete account
+8. **Plan & Billing**: current plan + usage limit; optional payment setup
+
+---
+
+## 9) Hosting & Runtime
+Frontend on Firebase Hosting. Backend: Node.js/Express (`server.js`) deployable as a service or Cloud Functions. Assets in Firebase Storage. Auth via Firebase Auth.
+
+**Security:** HSTS, CSP, X-Frame-Options DENY, X-Content-Type-Options, Referrer-Policy, Permissions-Policy; per-IP rate limiting; 100kb body cap; no internal error/stack leakage to clients.
+
+---
+
+## 10) Business Model
+
+**Primary — B2B SaaS subscription (provider/clinic pays EvalDoc):**
+
+| Plan | Price/mo | Seats | Chats/mo | Highlights |
+|------|----------|-------|----------|------------|
+| Free | $0 | 1 | 50 | Safety pipeline, basic analytics, branded link + QR |
+| Pro | $29 | 1 | Unlimited | Custom branding, full analytics, AI drafts, priority verification |
+| Clinic | $99 | 5 | Unlimited | Team inbox, shared analytics, clinic branding |
+| Enterprise | Custom | Unlimited | Unlimited | SSO/SAML, data residency, DPA & BAA, SLAs |
+
+**Secondary — optional patient-pay add-on (per provider):** per-chat or subscription, processed via Stripe Connect. Platform fee applies on top of processor fees. Public pricing is exposed via the pricing endpoints so patients see cost before chatting.
+
+---
+
+## 11) Multi-Provider Clinics (Phase A–D Implemented)
+
+Organizations are a membership + billing boundary owning one or more providers. Added non-breakingly: a solo provider gets a **lazy personal org** (`orgId = providerId`, sole owner) the first time they touch org features, so the existing solo flow is unchanged.
+
+* **RBAC** — pure, unit-tested `can(role, action)` core; `canManageMember`/`canAssignRole` guard privilege escalation (admins can't touch owners/each other; nobody mints owners via invite).
+* **Invites & seats** — email invites with unguessable single-use expiring tokens; seat enforcement (active + pending vs plan limit) at both invite and accept time.
+* **Clinic-wide inbox** (`/api/org/inbox`) and **aggregate analytics** (`/api/org/analytics`) — owner/admin only.
+
+**Remaining (roadmap):**
+* Phase E — seat-quantity Stripe subscription (consolidated org billing)
+* Clinic admin **UI** (the API/data layer is complete)
+* Ownership transfer flow; multi-org membership per user
+* Full UI internationalization (beyond safety text)
+* Custom domains, EHR integrations
+* SSO/SAML, data residency, BAA/DPA automation for Enterprise
+* 2FA + email change for account security
+
+---
+
+## 12) Definition of Done
+
+* Provider publishes a **live preview link in <5 minutes** (no verification/billing wait)
+* Patient chats without login; preview state is clearly disclosed
+* Topics enforced (no generic assistant)
+* Safety blocks diagnosis/treatment/dosing; red flags escalate; text localized
+* Conversations + safety events logged
+* Dashboard shows usage + escalations + onboarding checklist + verification status
+* Free tier limit enforced
+* Provider can export and delete their account data
+* Public pricing is visible
+
+---
+
+## 13) REST API (Implemented)
+
+> Auth = Firebase ID token in `Authorization: Bearer <token>` unless marked **public**.
+
+**Provider & onboarding**
+* `POST /api/provider` — create provider (starts in `preview`)
+* `POST /api/provider/update` — update profile/branding/topics/status (publish requires verified)
+* `GET /api/me` — current provider profile
+* `GET /api/provider` *(public)* — resolve provider by handle
+* `GET /api/provider/verification-status` — status, SLA, resubmit, preview flag
+* `GET /api/provider/onboarding-status` — checklist + next action
+* `GET /api/search-providers` *(public)* — provider search
+* `GET /api/qr/:handle` *(public)* — QR PNG for the provider link
+
+**Account (GDPR)**
+* `GET /api/account/export` — full data export (JSON)
+* `DELETE /api/account` — cascading erasure (`{ confirm: "DELETE" }`)
+
+**Organizations & team (multi-provider clinics)**
+* `GET /api/org` — current org, members, seat usage (lazily provisions a personal org)
+* `POST /api/org/invite` — invite a member (RBAC + seat check)
+* `POST /api/org/invite/accept` — accept an invite (`{ token }`)
+* `GET /api/org/members` — list members
+* `PATCH /api/org/members/:uid` — change a member's role (RBAC)
+* `DELETE /api/org/members/:uid` — remove a member (frees a seat)
+* `GET /api/org/inbox` — clinic-wide patient threads (owner/admin)
+* `GET /api/org/analytics` — clinic-wide aggregate analytics (owner/admin)
+
+**Pricing (public)**
+* `GET /api/pricing` — SaaS plans + add-on terms
+* `GET /api/pricing/:handle` — patient-facing cost for a provider
+
+**Chat & anonymous patient (public)**
+* `POST /api/chat` — send a message (topic-gated, safety-filtered, payment-gated if enabled)
+* `GET /api/chat/history` — session history
+* `POST /api/satisfaction` — rating (requires the owning `sessionId`)
+* `POST /api/waitlist` — join waitlist
+
+**Authenticated patient accounts** *(Firebase Auth; dispatched via `app.all('/api/patient/*')`)*
+* `GET /api/patient/me`, `POST /api/patient/create`
+* `POST /api/patient/thread`, `GET /api/patient/threads`, `GET /api/patient/thread/:id/messages`
+* `POST /api/patient/message`, `POST /api/patient/thread/:id/read`
+
+**Doctor inbox & async pipeline**
+* `GET /api/doctor/threads`, `GET /api/doctor/thread/:id`, `PATCH /api/doctor/thread/:id`
+* `POST /api/doctor/message`
+* `POST /api/doctor/draft/accept` | `/reject` | `/regenerate`
+* `GET /api/doctor/notifications`, `POST /api/doctor/notifications/preferences`, `POST /api/doctor/notifications/read`
+* `GET /api/doctor/feedback/stats`
+* `GET /api/conversations`, `GET /api/conversation` (query), `GET /api/conversation/:id`, `POST /api/conversation/:id/reply`, `DELETE /api/conversations/:id`
+
+**Analytics & safety**
+* `GET /api/analytics`, `GET /api/admin/analytics` (platform-admin only), `GET /api/safety-events`
+
+**Billing (Stripe)**
+* `POST /api/stripe/create-connect-account` | `/create-account-link` | `/refresh-account-status` | `/set-pricing`
+* `GET /api/stripe/diagnostics`
+* `GET /api/payment/config/:handle` *(public)*
+* `POST /api/payment/update-pricing` | `/create-subscription` | `/cancel-subscription` | `/create-intent` | `/create-checkout-session` | `/check-access` | `/webhook`
+* `GET /api/payment/transactions`, `GET /api/payment/revenue`
+
+**Ops**
+* `GET /health` (+ `?deep=true`), `GET /api/launch-status`, `POST /api/internal/daily-digest` (X-API-Key)
+
+---
+
+## 14) Configuration
+
+* `WAITLIST_ENABLED` (`true`/`false`) — gate self-serve signups
+* `ADMIN_UIDS` — comma-separated Firebase UIDs allowed to access platform-admin views (fail-closed if unset)
+* `DEEPSEEK_API_KEY`, `GEMINI_API_KEY` — LLM providers
+* `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PUBLISHABLE_KEY`
+* `INTERNAL_API_KEY` — internal cron endpoints
+* `ALLOWED_ORIGINS` — CORS allowlist
+* Firebase Admin credentials
+
+---
+
+## 15) Security & Reliability Controls
+
+**Authentication & authorization**
+* Firebase ID-token auth on all provider/doctor/org endpoints (`requireAuth`).
+* **Platform-admin gate** — `/api/admin/analytics` requires membership in the `ADMIN_UIDS` allowlist (fail-closed).
+* **Ownership/IDOR checks** — every resource accessed by id (threads, conversations, drafts, subscriptions, org members) is verified to belong to the caller / caller's org before any read-modify-write.
+* **RBAC** — org actions go through a pure, unit-tested `can(role, action)` core; `canManageMember`/`canAssignRole` block privilege escalation and owner-minting.
+* **Anonymous-but-scoped patient actions** — satisfaction ratings require the owning `sessionId`; no doc is created for unknown ids.
+
+**Secrets & transport**
+* Internal cron key compared in **constant time**; rate-limited.
+* Security headers: HSTS, CSP, X-Frame-Options DENY, X-Content-Type-Options, Referrer-Policy, Permissions-Policy.
+* Per-IP rate limiting; 100 kb body cap; CORS allowlist.
+* No internal error/stack/Stripe details leaked to clients.
+
+**Reliability**
+* **Request-correlation ids** (`X-Request-Id`, echoed; surfaced in 500 responses) for traceable support.
+* **Process-level fault net** — `unhandledRejection` / `uncaughtException` are logged, not silently fatal.
+* **LLM resilience** — exponential-backoff retry, multi-provider fallback chain, defensive response parsing, static safe fallback.
+* Fire-and-forget pipelines (triage/draft/notifications) are wrapped so a failure degrades gracefully and never crashes the request.
+* Bounded queries on platform-wide scans; pagination on list endpoints.
+
+**Data protection (GDPR)**
+* Self-serve data export (portability) and cascading account deletion (erasure).
+* PII/PHI detection + redaction (regex + NER) before storage/display.
+* Audit log on sensitive actions (chat, drafts, deletions, member changes).
+
+---
+
+## 16) Next Features (Prioritized)
+
+**P0 — trust & safety**
+1. **Email verification** before publishing or accepting payments (Firebase `email_verified`).
+2. **Admin verification console** — approve/reject provider credentials with reason + email notification (closes the manual-verification loop).
+3. **2FA** for provider accounts (TOTP) and email-change with re-auth.
+
+**P1 — clinic completion (Phase E + UI)**
+4. **Seat-quantity Stripe billing** for clinics (consolidated org subscription).
+5. **Clinic admin UI** — member list, invite form, clinic inbox/analytics (API already shipped).
+6. **Provider profiles per clinician within an org** (decouple provider creation from the owner uid).
+
+**P2 — growth & retention**
+7. **Webhooks/Zapier** for clinics (new escalation, new conversation) → EHR/CRM.
+8. **Scheduled reports** (weekly digest email of usage + escalations).
+9. **Custom domains** and white-label branding for Clinic/Enterprise.
+
+**P3 — depth**
+10. **Full UI internationalization** (beyond safety text), RTL support.
+11. **Analytics deep-dive**: cohort retention, topic trends, satisfaction over time.
+12. **Configurable safety rules per org** (within platform guardrails) + audit.

package/apphosting.staging.yaml

@@ -0,0 +1,48 @@
+# Staging deployment — mirrors production config with lower resources
+runConfig:
+  minInstances: 0
+  maxInstances: 2
+  cpu: 1
+  memoryMiB: 256
+  concurrency: 40
+
+env:
+  - variable: NODE_ENV
+    value: staging
+    availability:
+      - BUILD
+      - RUNTIME
+
+  - variable: FIREBASE_CONFIG
+    value: auto
+    availability:
+      - BUILD
+      - RUNTIME
+
+  # API Keys (use test/staging keys)
+  - variable: GEMINI_API_KEY
+    secret: GEMINI_API_KEY
+
+  - variable: DEEPSEEK_API_KEY
+    secret: DEEPSEEK_API_KEY
+
+  # Stripe TEST keys (pk_test_ / sk_test_)
+  - variable: STRIPE_PUBLISHABLE_KEY
+    secret: STRIPE_PUBLISHABLE_KEY_STAGING
+
+  - variable: STRIPE_SECRET_KEY
+    secret: STRIPE_SECRET_KEY_STAGING
+
+  - variable: STRIPE_WEBHOOK_SECRET
+    secret: STRIPE_WEBHOOK_SECRET_STAGING
+
+  # Staging URL
+  - variable: PLATFORM_URL
+    value: https://staging.evaldoctor.ai
+    availability:
+      - RUNTIME
+
+  - variable: ALLOWED_ORIGINS
+    value: https://staging.evaldoctor.ai
+    availability:
+      - RUNTIME

package/apphosting.yaml

@@ -0,0 +1,50 @@
+# Settings for Cloud Run
+runConfig:
+  minInstances: 0
+  maxInstances: 10
+  cpu: 1
+  memoryMiB: 512
+  concurrency: 80
+
+# Environment variables and secrets
+env:
+  - variable: NODE_ENV
+    value: production
+    availability:
+      - BUILD
+      - RUNTIME
+
+  - variable: FIREBASE_CONFIG
+    value: auto
+    availability:
+      - BUILD
+      - RUNTIME
+
+  # API Keys
+  - variable: GEMINI_API_KEY
+    secret: GEMINI_API_KEY
+
+  - variable: DEEPSEEK_API_KEY
+    secret: DEEPSEEK_API_KEY
+
+  # Stripe API Keys
+  - variable: STRIPE_PUBLISHABLE_KEY
+    secret: STRIPE_PUBLISHABLE_KEY
+
+  - variable: STRIPE_SECRET_KEY
+    secret: STRIPE_SECRET_KEY
+
+  - variable: STRIPE_WEBHOOK_SECRET
+    secret: STRIPE_WEBHOOK_SECRET
+
+  # Platform URL (HTTPS required for HIPAA compliance)
+  - variable: PLATFORM_URL
+    value: https://evaldoctor.ai
+    availability:
+      - RUNTIME
+
+  # CORS — restrict to production origin
+  - variable: ALLOWED_ORIGINS
+    value: https://evaldoctor.ai
+    availability:
+      - RUNTIME

package/bin/evaldoc.cjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Generated by npxhub. Runs evaldoc locally: npx evaldoc [--port <n>] [--no-open]
+"use strict"
+const { spawn } = require("node:child_process")
+const fs = require("node:fs")
+const http = require("node:http")
+const path = require("node:path")
+
+const CONFIG = {
+  "mode": "script",
+  "startScript": "start",
+  "staticDir": "",
+  "port": 8080,
+  "env": [
+    {
+      "name": "GEMINI_API_KEY",
+      "description": "Google Generative AI (Gemini 2.0 Flash) key used by the primary LLM in functions/src/llm.js.",
+      "required": true
+    },
+    {
+      "name": "DEEPSEEK_API_KEY",
+      "description": "DeepSeek API key for the fallback LLM (called via the openai client).",
+      "required": false
+    },
+    {
+      "name": "HUGGINGFACE_API_KEY",
+      "description": "Hugging Face token for the medical NER / inference models.",
+      "required": false
+    },
+    {
+      "name": "STRIPE_SECRET_KEY",
+      "description": "Stripe secret key for payment and Connect flows.",
+      "required": false
+    },
+    {
+      "name": "STRIPE_WEBHOOK_SECRET",
+      "description": "Stripe webhook signing secret used to verify incoming webhook requests.",
+      "required": false
+    },
+    {
+      "name": "GOOGLE_APPLICATION_CREDENTIALS",
+      "description": "Path to a Firebase/Firestore service-account JSON used by firebase-admin.",
+      "required": true
+    }
+  ]
+}
+const root = path.join(__dirname, "..")
+const pkg = require(path.join(root, "package.json"))
+const args = process.argv.slice(2)
+const flag = (name) => args.includes(name)
+const portArg = args.indexOf("--port")
+const port = Number(portArg >= 0 ? args[portArg + 1] : process.env.PORT || CONFIG.port)
+
+if (flag("--version") || flag("-v")) {
+  console.log(pkg.version)
+  process.exit(0)
+}
+if (flag("--help") || flag("-h")) {
+  console.log(`${pkg.name} ${pkg.version}\n\nUsage: npx ${pkg.name} [--port <n>] [--no-open]`)
+  if (CONFIG.env.length) {
+    console.log("\nEnvironment variables:")
+    for (const e of CONFIG.env) console.log(`  ${e.name}${e.required ? " (required)" : ""}  ${e.description}`)
+  }
+  process.exit(0)
+}
+
+const missing = CONFIG.env.filter((e) => e.required && !process.env[e.name])
+if (missing.length) {
+  console.error("Set these environment variables first:")
+  for (const e of missing) console.error(`  ${e.name}  ${e.description}`)
+  process.exit(1)
+}
+
+const url = `http://localhost:${port}`
+function openBrowser() {
+  if (flag("--no-open")) return
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open"
+  const cmdArgs = process.platform === "win32" ? ["/c", "start", "", url] : [url]
+  spawn(cmd, cmdArgs, { stdio: "ignore", detached: true }).on("error", () => {}).unref()
+}
+
+if (CONFIG.mode === "static") {
+  const dir = path.join(root, CONFIG.staticDir)
+  const types = { ".html": "text/html", ".js": "text/javascript", ".css": "text/css", ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg", ".ico": "image/x-icon", ".woff2": "font/woff2" }
+  http
+    .createServer((req, res) => {
+      const clean = path.normalize(decodeURIComponent((req.url || "/").split("?")[0])).replace(/^(\.\.[/\\])+/, "")
+      let file = path.join(dir, clean)
+      if (!file.startsWith(dir) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) file = path.join(dir, "index.html")
+      res.setHeader("Content-Type", types[path.extname(file)] || "application/octet-stream")
+      fs.createReadStream(file).on("error", () => res.writeHead(404).end()).pipe(res)
+    })
+    .listen(port, () => {
+      console.log(`${pkg.name} running at ${url}`)
+      openBrowser()
+    })
+} else {
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm"
+  const child = spawn(npm, ["run", CONFIG.startScript], { cwd: root, stdio: "inherit", env: { ...process.env, PORT: String(port) }, shell: process.platform === "win32" })
+  setTimeout(openBrowser, 2500)
+  const stop = () => child.kill("SIGINT")
+  process.on("SIGINT", stop)
+  process.on("SIGTERM", stop)
+  child.on("exit", (code) => process.exit(code ?? 0))
+}

package/cors.json

@@ -0,0 +1,8 @@
+[
+  {
+    "origin": ["*"],
+    "method": ["GET", "POST", "PUT", "DELETE", "HEAD"],
+    "maxAgeSeconds": 3600,
+    "responseHeader": ["Content-Type", "Authorization"]
+  }
+]