Vocal ER — Development & Project Strategy
How we build this without drift, borrowed from what already worked across ICG Labs. Companion to BRIEF.md (the why) and PRD.md (the what).
Learnings we're importing from the ICG Labs portfolio
| From | The lesson | Applied to Vocal ER |
|---|---|---|
| Spoken (most recent) | The lab pattern: before building the product, ship an internal interactive showcase where every risky component gets its own standalone demo — including at least one real flagship demo that proves the hardest part (Spoken's live photo→rig uploader). The lab doubles as the shared artifact the co-founder reacts to. | lab/ in this repo, deployed to an internal subdomain. Real demos for the risky parts: live voice analysis and the triage call experience. Nina reacts to demos, not to documents. |
| BuddyUp | App Store releases meant days of waiting per update — brutal for iteration speed. | Web-first (already decided in the founding meeting). Capacitor wrap later gets OTA updates so we never re-live that. |
| Snupix | A plan site at a subdomain keeps the partner and the plan in sync — docs live in the repo, the site renders them, one source of truth. | The lab renders BRIEF and this strategy as pages straight from docs/*.md. Editing the doc updates the site. |
| NinasAI | A stateless app (no database, nothing stored) can still deliver the full experience — and removes an entire class of risk. | Phase 0 lab has zero backend and stores nothing. Phase 1 stays PHI-free by design. |
| Prism | The showcase is the component library — demos become the parts bin the real app assembles from. | Lab demos are written as extractable components, not throwaway sketches. |
| Gig Console (app template) | Read-only public + operator-token edit, enforced server-side — the build-in-public shell. | The pattern for any public demo mode later; guards live on the server, never just hidden buttons. |
| Sharpe / MINT | Padlocked snapshots: internal things can have URLs without being announcements. | Lab is link-only + noindex — shareable with Nina and Barry, invisible to search. |
| CRANE / Redline | Compliance-shaped products (permits, HIPAA) win by making the compliance path a feature, designed in from day one. | The PHI boundary, audit-loggable schema, and RTM design-ins come from RESEARCH.md, not retrofits. |
Environments & domains (the ladder)
| Stage | Where | Purpose | When |
|---|---|---|---|
| Local | localhost:3000 | Development | Always |
| Lab (internal) | vocal-er.icglabs.co | Component demos + docs pages. Link-only, noindex. What Nina/Barry review. | Now (Phase 0) |
| Dev | Vercel preview URLs (every push/PR gets one) | Automatic per-change review builds — this is the dev environment; no maintenance. | Phase 1 |
| Staging | vocal-er-staging.icglabs.co (alias of the staging branch) | Production-like config; Nina's UAT before anything ships. | Phase 1+ |
| Production | Branded domain, TBD with the name decision (no .er TLD exists; candidates to check: vocaler.app, vocal-er.com, getvocaler.com…) | The real app. Separate Vercel project from the lab. | Phase 1 launch |
| PHI tier | Separate Vercel project and separate database org | Tier 2 clinical environment — isolated so the consumer tier never inherits PHI obligations (see RESEARCH.md §2). | Phase 3 |
Notes: subdomain spelling stays hyphenated (vocal-er) everywhere internal — it sidesteps the "Vocaler" problem until branding is settled. The lab is Vercel project icg-vocal-er built from the lab/ subdirectory (the Spoken precedent: the lab owns the icglabs.co subdomain); the production app later gets its own separate project and branded domain, so lab experiments can never break production. The lab ships with a password gate (fail-open until SITE_PASSWORD is set in Vercel env) and noindex.
The PRD is the anti-drift layer
PRD.md is the single source of truth for what we're building. The brief holds the vision; the PRD holds the specs; the lab holds the proof.
The rules:
- No feature gets built until its PRD section exists — user story, acceptance criteria, states, data touched, compliance notes, out-of-scope list.
- Change the PRD first, then the code. If implementation wants to deviate, the PRD gets edited (one commit) before the build continues. Drift is a diff you can see.
- Demos before product. Any component with real risk (voice, recording, triage flow) ships in the lab first; Nina's reaction updates the PRD; only then does it graduate into the product.
- Every PR references the PRD section it implements. Review question #1 is "does this match the PRD?"
- Compliance notes are part of the spec. Each feature's PRD section says what data it touches and which side of the PHI boundary it lives on — so Barry reviews specs, not surprises.
The loop: lab demo → Nina feedback → PRD locked → build → preview → staging UAT → production.
Phase plan
- Phase 0 — Lab (now).
lab/Next.js app: component demos + BRIEF/strategy pages. No backend, nothing stored. Deployed internal. Exit: Nina has clicked through every demo and reacted. - Phase 1 — v1 consumer app. Auth, real exercise library (from Nina's Drive content), player + programs, email check-ins, disclaimer gate, booking. Stack per RESEARCH.md: Vercel Pro + dedicated Supabase project (not the shared ICG instance), PHI-ready architecture (RLS,
audit_logtable, UUIDs, zero health data in logs/analytics). Exit: first real users on the paid-or-free decision point. - Phase 2 — Triage nurse + practice loop. Voice-first triage (decision tree as code, per RESEARCH.md §1), practice video recording/upload for coach review, program reassignment, SMS check-ins.
- Phase 3 — Tier 2 providers + HIPAA switch-on. Provider onboarding, content builder, patient management, in-app video sessions, laryngoscopy uploads — on the isolated PHI stack with BAAs signed. RTM design-ins (adherence telemetry, clinician time logs, episode-of-care model) land here.
- Parallel track — the corpus. Transcribe/diarize Nina's recordings, structure + label (RESEARCH.md §1 groundwork) — feeds the triage persona now and the listening coach later.
Working agreements
- Repo layout:
docs/is canonical (brief, PRD, strategy, research);lab/is Phase 0;app/(orweb/) arrives in Phase 1 as its own Next.js project. - Cadence: small commits, every push previewable; a working session with Nina per phase gate (demo walkthrough, not status meeting).
- Quality gates: QA pass + design review before anything is shown at a phase gate; Barry architecture review before Phase 2 (data starts flowing) and again before Phase 3 (PHI).
- Naming: "Vocal ER" everywhere user-facing until the brand decision;
vocal-ereverywhere technical.