evaldoc 1.0.0

package/docs/ARCHITECTURE_SUMMARY.md

@@ -0,0 +1,323 @@
+# EvalDoc Thread-Based Architecture
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PATIENT EXPERIENCE                        │
+└─────────────────────────────────────────────────────────────┘
+
+Patient clicks → evaldoc.com/dr-john-cardiology
+      ↓
+Prompted to "Continue with Google"
+      ↓
+Signs in with Google account
+      ↓
+Thread created: thread_googleuid_drjohn
+      ↓
+Patient sends message → AI responds
+      ↓
+Conversation persists forever (accessible anytime)
+
+
+┌─────────────────────────────────────────────────────────────┐
+│                    DOCTOR EXPERIENCE                         │
+└─────────────────────────────────────────────────────────────┘
+
+Doctor logs into dashboard
+      ↓
+Sees inbox with all threads
+      ↓
+Threads grouped by patient (not sessionId)
+      ↓
+Can view conversation history
+      ↓
+Can reply manually (overrides AI)
+      ↓
+Gets notifications for new messages
+```
+
+## Data Flow
+
+```
+┌──────────┐         ┌──────────┐         ┌──────────┐
+│ Patient  │ ◄─────► │  Thread  │ ◄─────► │  Doctor  │
+│ (Google) │         │          │         │(Provider)│
+└──────────┘         └──────────┘         └──────────┘
+     │                    │                     │
+     ├── email            ├── patientId         ├── handle
+     ├── name             ├── doctorId          ├── displayName
+     ├── photo            ├── status            ├── specialty
+     ├── doctorIds[]      ├── messages[]        ├── pricingModel
+     └── fcmToken         └── unreadCounts      └── stripeAccount
+```
+
+## Collections Structure
+
+```
+Firestore
+├── patients/{patientId}
+│   └── Profile data (email, name, photo)
+│
+├── providers/{doctorId}
+│   └── Doctor profile (existing)
+│
+└── threads/{thread_patientId_doctorId}
+    ├── Thread metadata
+    └── messages (subcollection)
+        └── {messageId}
+            ├── role: patient | doctor | ai
+            ├── message: "..."
+            ├── createdAt
+            └── readStatus
+```
+
+## Authentication Flow
+
+```
+                    ┌──────────────────┐
+                    │  Firebase Auth   │
+                    └────────┬─────────┘
+                             │
+                    ┌────────▼─────────┐
+                    │ Google Sign-In   │
+                    └────────┬─────────┘
+                             │
+            ┌────────────────┴────────────────┐
+            │                                 │
+    ┌───────▼────────┐              ┌────────▼───────┐
+    │ Patient Token  │              │ Doctor Token   │
+    │ (uid)          │              │ (custom claim) │
+    └───────┬────────┘              └────────┬───────┘
+            │                                 │
+    ┌───────▼────────┐              ┌────────▼───────┐
+    │ Read own       │              │ Read doctor    │
+    │ threads        │              │ threads        │
+    └────────────────┘              └────────────────┘
+```
+
+## API Endpoints
+
+### Patient APIs (NEW)
+```
+POST /api/patient/create
+  → Create patient profile on first sign-in
+
+POST /api/patient/thread
+  → Get or create thread with doctor
+  Body: { doctorHandle: "dr-john-cardiology" }
+
+GET /api/patient/threads
+  → Get all threads for this patient
+
+POST /api/patient/message
+  → Send message to doctor
+  Body: { threadId, message, topic }
+  Response: { response, escalation }
+
+GET /api/patient/thread/:id/messages
+  → Load conversation history
+```
+
+### Doctor APIs (UPDATED)
+```
+GET /api/doctor/threads
+  → Get all threads (patients)
+
+GET /api/doctor/thread/:id
+  → View specific conversation
+
+POST /api/doctor/message
+  → Manual reply to patient
+  Body: { threadId, message, override }
+```
+
+## Key Features
+
+### ✅ Implemented
+- Google Sign-In authentication
+- Thread-based conversations
+- Persistent message history
+- AI-powered responses
+- Safety filters & escalation
+- Firestore security rules
+- Payment integration ready
+
+### 🚧 Pending (Phase 2)
+- Doctor inbox UI update
+- Doctor manual reply UI
+- Web push notifications
+- Real-time message updates
+- Thread search & filters
+- Patient contact info display
+
+### 📋 Future Enhancements
+- Multi-language support
+- Voice messages
+- Image attachments
+- Video consultations
+- Appointment scheduling
+- Prescription handling
+
+## Billing Model
+
+```
+Per-Chat Pricing
+├── Patient sends first message
+├── Payment required before AI responds
+├── Thread marked as "paid"
+└── Unlimited messages in thread
+
+Subscription Pricing
+├── Patient pays monthly
+├── Unlimited threads
+└── Unlimited messages
+
+Free Model
+└── No payment required
+```
+
+## Security Model
+
+```
+Firestore Rules
+├── patients/{id}
+│   └── Only patient can read/update own profile
+│
+├── threads/{id}
+│   └── Patient OR doctor can read
+│   └── Only backend can write
+│
+└── threads/{id}/messages/{msgId}
+    └── Same as parent thread
+    └── Only backend can write
+```
+
+## Advantages Over Previous System
+
+| Feature | Old (sessionId) | New (Threads) |
+|---------|----------------|---------------|
+| **Identity** | Anonymous session | Google account |
+| **Cross-device** | ❌ Lost on new device | ✅ Works everywhere |
+| **History** | ❌ Lost if cleared | ✅ Persistent forever |
+| **Multiple doctors** | ❌ Messy | ✅ Clean separation |
+| **Doctor inbox** | ❌ Shows sessionIds | ✅ Shows patient names |
+| **Notifications** | ❌ Not possible | ✅ Push notifications |
+| **Billing** | Per conversation | Per thread (cleaner) |
+
+## Migration Path
+
+```
+Phase 1: Core (COMPLETED) ✅
+├── Patient authentication
+├── Thread creation
+├── Message sending
+├── API endpoints
+└── Security rules
+
+Phase 2: Doctor UI (PENDING)
+├── Update inbox to show threads
+├── Add manual reply capability
+├── Show patient profiles
+└── Add thread management
+
+Phase 3: Enhancements (FUTURE)
+├── Web push notifications
+├── Real-time updates
+├── Advanced search
+└── Analytics dashboard
+```
+
+## Performance & Scale
+
+**Reads per chat session:**
+- Load provider: 1 read
+- Load thread: 1 read
+- Load messages: N reads (50 max)
+- **Total: ~52 reads**
+
+**Writes per message:**
+- Patient message: 3 writes (message + thread + patient)
+- AI response: 2 writes (message + thread)
+- **Total: 5 writes per exchange**
+
+**Estimated costs (1000 users, 10 msgs each/month):**
+- Writes: 50,000 × $0.18/100k = **$0.09**
+- Reads: 100,000 × $0.06/100k = **$0.06**
+- **Total: ~$0.15/month** (very cheap!)
+
+## Firestore Indexes Required
+
+```bash
+# Create these in Firebase Console
+threads
+  - (patientId, lastMessageAt DESC)
+  - (doctorId, lastMessageAt DESC)
+  - (doctorId, status, lastMessageAt DESC)
+
+messages
+  - (threadId, createdAt ASC)
+```
+
+## Testing Scenarios
+
+1. **New patient flow:**
+   - Visit doctor link → Sign in → Send message → Get response
+
+2. **Returning patient:**
+   - Visit doctor link → Already signed in → See history → Continue chat
+
+3. **Multiple doctors:**
+   - Patient talks to Dr. A → Separate thread
+   - Patient talks to Dr. B → New thread
+   - Both conversations independent
+
+4. **Doctor view:**
+   - Doctor logs in → Sees all patients
+   - Clicks patient → Sees full conversation
+   - Can reply manually
+
+## Quick Start Commands
+
+```bash
+# Deploy security rules
+firebase deploy --only firestore:rules
+
+# Deploy functions
+firebase deploy --only functions
+
+# Deploy hosting
+firebase deploy --only hosting
+
+# Test locally
+firebase emulators:start
+```
+
+## Support & Debugging
+
+**Common issues:**
+
+1. **"Unauthorized" error**
+   - Check Firebase Auth is enabled
+   - Verify token is sent in header
+
+2. **Messages not saving**
+   - Check Firestore rules deployed
+   - Verify API endpoint integration
+
+3. **Google Sign-In fails**
+   - Check authorized domains in Firebase
+   - Verify API keys configured
+
+**Debug checklist:**
+- [ ] Firebase Console → Authentication → Google enabled
+- [ ] Firestore rules deployed
+- [ ] Functions deployed
+- [ ] `/app/config.js` has correct Firebase config
+- [ ] Browser console shows no errors
+
+---
+
+**Status**: Phase 1 Complete ✅
+**Next Steps**: Update doctor inbox UI
+**Timeline**: Ready for testing

package/docs/DEPLOYMENT.md

@@ -0,0 +1,86 @@
+# Firebase Deployment Guide
+
+## Prerequisites
+
+Make sure you have:
+- Firebase CLI installed (`npm install -g firebase-tools`)
+- Logged in to Firebase (`firebase login`)
+- Your API keys ready (Gemini and DeepSeek)
+
+## Step 1: Set Environment Variables (Secrets)
+
+Run these commands to configure your API keys:
+
+```bash
+# Set Gemini API Key (required)
+firebase functions:secrets:set GEMINI_API_KEY
+
+# Set DeepSeek API Key (optional fallback)
+firebase functions:secrets:set DEEPSEEK_API_KEY
+```
+
+When prompted, paste your API key values.
+
+## Step 2: Install Dependencies
+
+```bash
+cd functions
+npm install
+cd ..
+```
+
+## Step 3: Deploy to Firebase
+
+Deploy everything (Hosting + Functions + Firestore rules):
+
+```bash
+firebase deploy
+```
+
+Or deploy individually:
+
+```bash
+# Deploy only Cloud Functions
+firebase deploy --only functions
+
+# Deploy only Hosting
+firebase deploy --only hosting
+
+# Deploy only Firestore rules
+firebase deploy --only firestore:rules
+```
+
+## Configuration Files
+
+### apphosting.yaml
+Defines runtime configuration and environment variables for Firebase App Hosting.
+- Sets runtime resources (CPU, memory, instances)
+- References secrets (GEMINI_API_KEY, DEEPSEEK_API_KEY)
+
+### functions/src/index.js
+The Cloud Function is configured to use secrets via:
+```javascript
+exports.api = functions
+  .runWith({
+    secrets: ['GEMINI_API_KEY', 'DEEPSEEK_API_KEY']
+  })
+  .https.onRequest(async (req, res) => { ... });
+```
+
+## Current Status
+- Production URL: https://evaldoc--evaldocplatform.us-east4.hosted.app/
+- Functions endpoint: https://us-central1-evaldocplatform.cloudfunctions.net/api
+
+## Troubleshooting
+
+### If functions fail to deploy:
+```bash
+# Check Firebase logs
+firebase functions:log
+
+# Check if secrets are set
+firebase functions:secrets:access GEMINI_API_KEY
+```
+
+### If secrets are not accessible:
+Make sure you've set them using `firebase functions:secrets:set` and that your functions code includes them in `runWith({ secrets: [...] })`