ibiome

iBiome

Firebase-native gut-health coaching platform. Next.js 15 + Expo monorepo with multi-tenant workspaces, AI-assisted meal scoring, and a full daily planner.

---

Stack

Layer	Tech
Web app	Next.js 15 (App Router)
Mobile	Expo Router (scaffold)
Auth	Firebase Authentication
Database	Cloud Firestore
Storage	Firebase Storage
AI	Anthropic Claude (server-side proxy)
Analytics	PostHog (scaffold)
Errors	Sentry (scaffold)
Billing	Stripe (scaffold)

---

Monorepo layout

apps/
  web/          Next.js app — all pages, API routes, components
  mobile/       Expo React Native scaffold
  functions/    Firebase Cloud Functions (background jobs, OCR pipeline)
packages/
  ui/           Design tokens + shared components (Playfair Display, Outfit, parchment palette)
  types/        Shared TypeScript interfaces
  domain/       Deterministic meal scoring, gamification, recommendation engine
  ai/           Anthropic provider abstraction, structured output contracts, entitlement checks
  firebase/     Client + Admin SDK setup, typed repositories
  config/       Env parsing, feature flags, plan entitlements
  validation/   Zod schemas

---

Quick start

1. Clone and install

git clone https://github.com/YOUR_ORG/ibiome.git
cd ibiome
npm install

2. Configure environment

Copy the example and fill in your values:

cp .env.example .env.local

Open .env.local and fill in:

# ── App ──────────────────────────────────────────────────────────────
NEXT_PUBLIC_APP_NAME=InnerBiome
NEXT_PUBLIC_USE_FIREBASE_EMULATORS=false

# ── Firebase Web Config ───────────────────────────────────────────────
# Firebase Console → Project Settings → Your apps → web app → SDK config
NEXT_PUBLIC_FIREBASE_API_KEY=AIzaSy...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=ibiome-app.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=ibiome-app
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=ibiome-app.firebasestorage.app
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789:web:abc123

# ── Firebase Admin SDK ────────────────────────────────────────────────
# Firebase Console → Project Settings → Service accounts → Generate new key
FIREBASE_PROJECT_ID=ibiome-app
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@ibiome-app.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n"

# ── Anthropic (AI Coach features) ────────────────────────────────────
# console.anthropic.com → API Keys
ANTHROPIC_API_KEY=sk-ant-api03-...

Windows + OneDrive users: do NOT use next dev — use next build && next start to avoid EINVAL readlink errors.

3. Deploy Firebase rules

# One-time setup — deploys Firestore rules, Storage rules, indexes
npx firebase deploy --only firestore,storage

4. Run locally

cd apps/web
npm run build
npm start
# → http://localhost:3000

5. Type check

cd apps/web
npx tsc --noEmit

---

Deploy to Vercel (recommended)

1. Push to GitHub
2. Import repo in vercel.com/new
3. Set Root directory to apps/web
4. Add all env vars from .env.local in Vercel project settings
5. Deploy

Vercel auto-detects Next.js and handles the monorepo correctly with vercel.json (included).

---

Deploy to Firebase Hosting (Cloud Run)

# Add output: standalone to apps/web/next.config.ts first, then:
npx firebase deploy --only hosting

See docs/deploy-firebase.md for full Cloud Run setup.

---

Firebase project setup (first time)

If starting from a fresh Firebase project:

# 1. Update .firebaserc with your project ID
# 2. Enable Authentication → Email/Password provider
# 3. Create Firestore database (production mode)
# 4. Enable Storage
# 5. Deploy rules
npx firebase deploy --only firestore,storage

---

App structure

Authentication flow

• Sign up → email + password + username
• Onboarding → language / timezone / units → POST /api/onboarding/bootstrap
  • Creates /users/{uid}, /users/{uid}/profile/main, /workspaces/{id}, /workspaces/{id}/memberships/{uid}

Planner (auto-seeds on first load)

• loadPlannerDashboard() calls ensurePlannerMonthSeed()
• Missing days are batch-written from 7 rotating templates
• Stored at /users/{uid}/tracking/default/dailyPlans/{isoDate}
• Check-ins at /users/{uid}/tracking/default/dailyCheckins/{isoDate}

AI features (Pro-gated)

All AI calls are server-side. No Anthropic key is ever sent to the client.

Feature	Route	Gate
Meal scoring	POST /api/ai/meal-score	Pro
Menu URL analysis	POST /api/ai/menu-url	Pro
Dietician chat	POST /api/ai/chat	Pro

Upload pipeline

• File → Firebase Storage at users/{uid}/uploads/{docId}/{filename}
• Metadata → Firestore at users/{uid}/uploadedDocuments/{docId}
• OCR extraction → Cloud Function trigger (stub in apps/functions/)

---

Environment variables reference

Variable	Required	Description
NEXT_PUBLIC_FIREBASE_API_KEY	✅	Firebase web API key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN	✅	project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID	✅	Firebase project ID
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET	✅	Firebase storage bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID	✅	Firebase sender ID
NEXT_PUBLIC_FIREBASE_APP_ID	✅	Firebase app ID
FIREBASE_PROJECT_ID	✅	Same as public project ID (server-side)
FIREBASE_CLIENT_EMAIL	✅	Service account email
FIREBASE_PRIVATE_KEY	✅	Service account private key (with \n newlines)
ANTHROPIC_API_KEY	⚠️ AI only	Enables AI Coach features
NEXT_PUBLIC_USE_FIREBASE_EMULATORS	❌ optional	Set true for local emulator dev

---

Security notes

• Service account key (FIREBASE_PRIVATE_KEY) must never be committed to git
• .env.local is in .gitignore — never commit it
• All AI calls are server-side — the Anthropic key is never exposed to the browser
• Firebase Security Rules enforce per-user data isolation
• Invite tokens are hashed server-side and never stored in plain text

---

License

Private — all rights reserved.