Synced from the repo — do not edit here

Canonical source: docs/claude/deployment.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

Deployment, Git & Hosting

Git Rules

1. NO git stash — User forbids stash operations in this repo
2. NO automatic commits — Only commit when explicitly requested
3. NO automatic deploys — Always confirm with user first

Firebase Functions Deployment

NEVER deploy all functions at once — always deploy specific functions only

cd /Users/G/basis/basis-functions

# Deploy specific function(s)
firebase deploy --only functions:clinic_service --force
firebase deploy --only functions:analyze_document_summary_v2,functions:analyze_document_summary

# Deploy specific codebase
firebase deploy --only functions:labs

# Deploy Firestore rules/indexes
firebase deploy --only firestore:rules
firebase deploy --only firestore:indexes

Basis Flow Web (Staff Platform)

Full deployment steps:

# 1. Build the Next.js app
cd /Users/G/basis/hybrid/basisflow-web
rm -rf .next  # Clear cache to avoid stale module errors
npm run build

# 2. Copy build output to Firebase public folder
rm -rf /Users/G/basis/basis-functions/public-platform/*
cp -R /Users/G/basis/hybrid/basisflow-web/out/* /Users/G/basis/basis-functions/public-platform/

# 3. Deploy to Firebase Hosting (platform target only)
cd /Users/G/basis/basis-functions
firebase deploy --only hosting:platform

IMPORTANT: Always use --only hosting:platform. Using --only hosting deploys ALL targets.

Blue Screen Flash Issue on Deploy

Problem: Users see a flashing blue loading screen after a new deployment because browsers have cached old JS chunks.

Solution (already applied in firebase.json):

• **/*.html -> no-store (always fetch fresh HTML)
• /_next/static/** -> Long cache (safe: filenames have content hashes)
• ** (everything else) -> max-age=0, must-revalidate

Client-side fallback (already in app/layout.tsx): JS error handler catches chunk loading failures, clears caches, forces page reload (once per session).

Best practices:

1. Always run rm -rf .next before building
2. Deploy during low-traffic hours
3. Use Firebase preview channels for testing:

firebase hosting:channel:deploy preview-v123 --only platform

Basis Hybrid (Client Mobile)

cd /Users/G/basis/hybrid
./sh/build_android.sh  # Android APK/Bundle
./sh/build_ipa.sh      # iOS IPA

# DO NOT run flutter clean (makes compile times too long)

Basis Web (Client Portal)

• Deployed to Netlify (NOT Firebase Hosting)
• Site name: rococo-lily-e33b0a
• Deploy command: cd hybrid/basisweb && netlify deploy --prod
• Link if needed: netlify link --name rococo-lily-e33b0a
• Auto-deploys from git push

Firebase Hosting Targets

Target	Domain	Source	Purpose
app	basis-hybrid.web.app	Legacy Flutter	Flutter web app (deprecated)
platform	platform.basishealth.io	basisflow-web	Staff platform
docs	docs.basishealth.io	docs/ (Docusaurus)	Docs & Handbook + client /guides
forms	forms.basishealth.io	Dynamic	Onboarding forms
book	book.basishealth.io	basis-book	Public booking pages

Deploying the docs site (docs target → basis-hybrid-docs)

The Docusaurus site at /Users/G/basis/docs is Firebase Hosting (site basis-hybrid-docs, custom domain docs.basishealth.io), served from basis-functions/public-docs/. There is no dedicated publish script and CI does not deploy it (docs-on-release.yml only builds an artifact). Deploy manually:

cd /Users/G/basis/docs && npm run build          # -> docs/build/
cp -R build/. /Users/G/basis/basis-functions/public-docs/   # overlay (keeps old hashed chunks)
cd /Users/G/basis/basis-functions && firebase deploy --only hosting:docs

Client-readable how-it-works pages live at docs/features/*.md, published under /guides. (A move to docs.readypractice.com is prepped but reverted until DNS + the Firebase custom domain are set.)

Emulator Setup

cd /Users/G/basis/basis-functions
firebase emulators:start --import ./emulator-data --export-on-exit ./emulator-data

# Start specific emulators only
firebase emulators:start --only functions,firestore

Service	Port	URL
Emulator UI	4000	http://127.0.0.1:4000
Functions	5001	http://127.0.0.1:5001
Firestore	8000	http://127.0.0.1:8000
Realtime DB	9000	http://127.0.0.1:9000
Hosting	5050	http://127.0.0.1:5050
Storage	9191	http://127.0.0.1:9191

Custom Domains / White-Labeling

• Custom domains must be added to Firebase Auth -> Settings -> Authorized domains
• Netlify handles DNS automatically when both site and DNS are on Netlify
• Custom domain -> clinic mapping is in basisweb/lib/clinic-context.tsx -> CUSTOM_DOMAIN_MAP
• For branded sign-in pages, use resolve_clinic_by_subdomain Cloud Function

Known File Warnings

DO NOT MODIFY Without Explicit Request

• hybrid/basisflow/ — deprecated legacy Flutter staff app
• Stripe-related files — payment integration is working; changes can break it
• ImportLabModal, UploadDocumentModal in Basis Flow Web — document upload was previously working; changes broke it
• Orphaned dashboard folder (hybrid/basisflow-web/app/dashboard/) — legacy routes not linked in UI

Large File Warning

File	Lines	Warning
hybrid/basisflow-web/app/(main)/clients/[id]/ClientDetailPage.tsx	~12,000	Use targeted edits with precise context. Broad regex patterns will cause unintended changes.

Pre-Deployment Checklist

• Tested locally with emulators
• Verified no linter errors
• Confirmed with user before deploying
• Monitor logs after deployment for errors
• Never assume deployment succeeded without confirmation