evaldoc 1.0.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,769 @@
+# EvalDoc Technical Architecture
+
+## 📐 System Architecture Overview
+
+EvalDoc is a full-stack web application built for scalability, reliability, and ease of maintenance in resource-constrained environments.
+
+---
+
+## 🏗️ Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     CLIENT LAYER                             │
+├─────────────────────────────────────────────────────────────┤
+│  Landing Page    │  Patient Chat   │  Doctor Dashboard      │
+│  (index.html)    │  (chat.html)    │  (app/index.html)      │
+│                  │                 │  (app/inbox.html)       │
+│                  │                 │  (app/analytics.html)   │
+└──────────────┬───────────┬──────────────────┬───────────────┘
+               │           │                  │
+               ▼           ▼                  ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   APPLICATION LAYER                          │
+├─────────────────────────────────────────────────────────────┤
+│         Node.js + Express Server (server.js)                │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  Routes:                                              │  │
+│  │  - /api/provider    (Public provider info)           │  │
+│  │  - /api/chat        (Patient messaging)              │  │
+│  │  - /api/conversations (Doctor inbox)                 │  │
+│  │  - /api/analytics   (Platform metrics)               │  │
+│  │  - /api/me          (Doctor profile)                 │  │
+│  └───────────────────────────────────────────────────────┘  │
+└──────────────┬───────────────────────┬──────────────────────┘
+               │                       │
+               ▼                       ▼
+┌──────────────────────────┐  ┌──────────────────────────────┐
+│     AI SERVICES          │  │   DATABASE LAYER             │
+├──────────────────────────┤  ├──────────────────────────────┤
+│  DeepSeek API (Primary)  │  │  Firebase Firestore          │
+│  Google Gemini (Fallback)│  │  ┌────────────────────────┐  │
+│                          │  │  │  Collections:          │  │
+│  functions/src/llm.js    │  │  │  - providers           │  │
+│                          │  │  │  - conversations       │  │
+└──────────────────────────┘  │  │  - messages (sub)      │  │
+                              │  │  - safetyEvents        │  │
+┌──────────────────────────┐  │  │  - analytics           │  │
+│   AUTHENTICATION         │  │  └────────────────────────┘  │
+├──────────────────────────┤  │                              │
+│  Firebase Auth           │  │  Firebase Admin SDK          │
+│  - Email/Password        │  └──────────────────────────────┘
+│  - Token-based           │
+└──────────────────────────┘
+```
+
+---
+
+## 🗂️ File Structure
+
+```
+EvalDoc/
+├── public/                          # Static assets (hosted on Firebase)
+│   ├── index.html                   # Landing page
+│   ├── chat.html                    # Patient chat interface
+│   │
+│   ├── assets/                      # Media files
+│   │   └── logo.jpg                 # Brand logo
+│   │
+│   ├── css/                         # Stylesheets
+│   │   ├── chat.css                 # Patient chat styles
+│   │   └── styles.css               # Landing page styles
+│   │
+│   ├── js/                          # Client-side scripts
+│   │   ├── chat.js                  # Patient chat logic
+│   │   └── search.js                # Doctor search
+│   │
+│   └── app/                         # Doctor dashboard
+│       ├── index.html               # Dashboard home
+│       ├── inbox.html               # Conversation inbox
+│       ├── analytics.html           # Analytics dashboard
+│       ├── app.css                  # Dashboard styles
+│       ├── app.js                   # Dashboard logic
+│       ├── inbox.js                 # Inbox logic
+│       ├── analytics.js             # Analytics logic
+│       └── config.js                # Firebase configuration
+│
+├── functions/                       # Firebase Cloud Functions
+│   └── src/
+│       ├── index.js                 # Cloud Functions entry
+│       ├── llm.js                   # AI integration
+│       └── patient-api.js           # Patient API handlers
+│
+├── server.js                        # Local development server
+├── firestore.rules                  # Database security rules
+├── firebase.json                    # Firebase configuration
+└── .env                             # Environment variables
+
+Documentation/
+├── PLATFORM_OVERVIEW.md             # Platform summary
+├── DOCTOR_TUTORIAL.md               # Doctor user guide
+├── PATIENT_GUIDE.md                 # Patient user guide
+└── ARCHITECTURE.md                  # This file
+```
+
+---
+
+## 💾 Database Schema
+
+### Firestore Collections
+
+#### 1. **providers**
+Doctor profiles and settings
+
+```javascript
+{
+  id: "auto-generated",
+  ownerId: "firebase-auth-uid",
+  handle: "dr-sarah-amina",              // Unique URL identifier
+  displayName: "Dr. Sarah Amina",
+  email: "sarah@example.com",
+  specialty: "Family Medicine",
+  country: "US",
+  locale: "en",
+  photoUrl: "https://...",
+  logoUrl: "https://...",
+  brandPrimaryColor: "#4fb3a4",
+  brandSecondaryColor: "#297B56",
+  welcomeMessage: "Welcome! How can I help?",
+  enabledTopics: [
+    "medication_info_safety",
+    "general_health_info",
+    ...
+  ],
+  status: "published",                   // draft | published | suspended
+  monthlyChatCount: 45,
+  monthlyChatCountMonth: "2026-01",
+  createdAt: Timestamp,
+  updatedAt: Timestamp
+}
+```
+
+#### 2. **conversations**
+Chat sessions between patients and providers
+
+```javascript
+{
+  id: "auto-generated",
+  providerId: "provider-doc-id",
+  sessionId: "anonymous-session-id",     // Patient identifier
+  handle: "dr-sarah-amina",
+  topic: "general_health_info",
+
+  // Client info (optional)
+  clientName: "John Doe",
+  clientEmail: "john@example.com",
+  clientPhone: "+256123456789",
+
+  // Status
+  isEscalated: false,
+  escalationReason: null,                // "red_flag" | null
+
+  // Message summaries
+  lastUserMessage: "What should I do...",
+  lastAssistantMessage: "For a fever...",
+  lastMessageAt: Timestamp,
+
+  // Timestamps
+  createdAt: Timestamp,
+  updatedAt: Timestamp
+}
+```
+
+#### 3. **messages** (subcollection of conversations)
+Individual messages in a conversation
+
+```javascript
+conversations/{conversationId}/messages/{messageId}
+{
+  id: "auto-generated",
+  role: "user",                          // user | assistant
+  content: "What should I do about...",
+  safetyFlags: ["pii_detected"],         // Array of safety flags
+  createdAt: Timestamp
+}
+```
+
+#### 4. **safetyEvents**
+Tracked safety incidents and escalations
+
+```javascript
+{
+  id: "auto-generated",
+  providerId: "provider-doc-id",
+  conversationId: "conversation-id",
+  eventType: "escalated",                // escalated | blocked_input | blocked_output | pii_detected
+  details: {
+    flags: ["severe_pain", "chest_pain"],
+    reason: "red_flag"
+  },
+  createdAt: Timestamp
+}
+```
+
+---
+
+## 🔌 API Endpoints
+
+### Public Endpoints (No Auth Required)
+
+#### `GET /api/provider?handle={handle}`
+Get public provider information
+
+**Query Params**:
+- `handle` (required): Doctor's unique handle
+
+**Response**:
+```json
+{
+  "handle": "dr-sarah-amina",
+  "displayName": "Dr. Sarah Amina",
+  "specialty": "Family Medicine",
+  "welcomeMessage": "Welcome!",
+  "brandPrimaryColor": "#4fb3a4",
+  "enabledTopics": ["medication_info_safety", ...],
+  "status": "published"
+}
+```
+
+#### `POST /api/chat`
+Send patient message and get AI response
+
+**Body**:
+```json
+{
+  "handle": "dr-sarah-amina",
+  "sessionId": "anonymous-uuid",
+  "message": "What should I do about fever?",
+  "topic": "general_health_info",
+  "clientName": "John Doe",        // Optional
+  "clientEmail": "john@email.com", // Optional
+  "clientPhone": "+256123456789"   // Optional
+}
+```
+
+**Response**:
+```json
+{
+  "conversationId": "conv-id",
+  "response": "For a fever, you should...",
+  "escalation": false,
+  "safetyFlags": []
+}
+```
+
+### Protected Endpoints (Auth Required)
+
+#### `GET /api/me`
+Get current logged-in doctor's profile
+
+**Headers**: `Authorization: Bearer {firebase-token}`
+
+**Response**: Full provider object
+
+#### `GET /api/conversations?limit=100`
+Get all conversations for logged-in doctor
+
+**Headers**: `Authorization: Bearer {firebase-token}`
+
+**Query Params**:
+- `limit` (optional): Max conversations to return (default: 30, max: 100)
+
+**Response**:
+```json
+{
+  "conversations": [
+    {
+      "id": "conv-id",
+      "sessionId": "session-uuid",
+      "clientName": "John Doe",
+      "lastUserMessage": "What should...",
+      "lastMessageAt": Timestamp,
+      "isEscalated": false,
+      ...
+    }
+  ]
+}
+```
+
+#### `GET /api/conversation/:id`
+Get single conversation with full message history
+
+**Headers**: `Authorization: Bearer {firebase-token}`
+
+**Response**:
+```json
+{
+  "id": "conv-id",
+  "sessionId": "session-uuid",
+  "messages": [
+    {
+      "role": "user",
+      "message": "What should I do?",
+      "createdAt": Timestamp
+    },
+    {
+      "role": "assistant",
+      "message": "For a fever...",
+      "createdAt": Timestamp
+    }
+  ],
+  ...
+}
+```
+
+#### `GET /api/analytics?period=month`
+Get platform-wide analytics
+
+**Headers**: `Authorization: Bearer {firebase-token}`
+
+**Query Params**:
+- `period` (optional): today | week | month | quarter | all
+
+**Response**:
+```json
+{
+  "summary": {
+    "totalDoctors": 15,
+    "activeDoctors": 12,
+    "totalConversations": 450,
+    "uniquePatients": 320
+  },
+  "doctors": [
+    {
+      "displayName": "Dr. Sarah",
+      "conversationCount": 45,
+      "uniquePatients": 32,
+      "messageCount": 180
+    }
+  ],
+  "period": "month"
+}
+```
+
+---
+
+## 🤖 AI Integration
+
+### LLM Service (`functions/src/llm.js`)
+
+#### AI Provider Priority
+1. **DeepSeek** (Primary) - Better medical accuracy
+2. **Google Gemini** (Fallback) - Backup if DeepSeek fails
+3. **Generic Response** - If both fail
+
+#### Function: `generateResponse()`
+
+```javascript
+async function generateResponse({ topicConfig, message, provider }) {
+  // 1. Try DeepSeek
+  try {
+    return await callDeepSeek({ topicConfig, message, provider });
+  } catch (error) {
+    console.error('DeepSeek failed:', error);
+  }
+
+  // 2. Fallback to Gemini
+  try {
+    return await callGemini({ topicConfig, message, provider });
+  } catch (error) {
+    console.error('Gemini failed:', error);
+  }
+
+  // 3. Generic fallback
+  return genericResponse(topicConfig);
+}
+```
+
+#### Safety Features
+
+**Input Analysis**:
+- PII detection (emails, phone numbers, addresses)
+- Red flag keywords (chest pain, severe bleeding, etc.)
+- Escalation triggers
+
+**Output Analysis**:
+- Medical advice blocking
+- Diagnosis blocking
+- Prescription blocking
+- Dosing recommendations blocking
+
+**Red Flag Keywords**:
+```javascript
+const RED_FLAGS = [
+  'chest pain', 'difficulty breathing', 'severe bleeding',
+  'loss of consciousness', 'suicidal', 'kill myself',
+  'severe pain', 'can\'t breathe', 'heart attack'
+];
+```
+
+---
+
+## 🔐 Security
+
+### Authentication Flow
+
+```
+1. Doctor signs up/in
+   ↓
+2. Firebase Auth creates user
+   ↓
+3. Frontend gets ID token
+   ↓
+4. Token sent in Authorization header
+   ↓
+5. Backend verifies token
+   ↓
+6. Request proceeds if valid
+```
+
+### Firestore Security Rules
+
+```javascript
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+
+    // Helper functions
+    function isSignedIn() {
+      return request.auth != null;
+    }
+
+    function isOwner(uid) {
+      return isSignedIn() && request.auth.uid == uid;
+    }
+
+    // Providers collection
+    match /providers/{providerId} {
+      allow read: if true;  // Public read
+      allow create: if isSignedIn();
+      allow update, delete: if isOwner(resource.data.ownerId);
+    }
+
+    // Conversations collection
+    match /conversations/{conversationId} {
+      allow read: if isSignedIn();  // Doctors can read all
+      allow create: if true;  // Anyone can create (patients)
+      allow update, delete: if false;  // No direct updates
+
+      // Messages subcollection
+      match /messages/{messageId} {
+        allow read: if isSignedIn();
+        allow create: if true;
+        allow update, delete: if false;
+      }
+    }
+
+    // Safety events (admin only)
+    match /safetyEvents/{eventId} {
+      allow read: if isSignedIn();
+      allow create: if true;
+      allow update, delete: if false;
+    }
+  }
+}
+```
+
+### Data Protection
+
+1. **PII Redaction**: Automatically removes sensitive info from logs
+2. **Encrypted Storage**: All Firestore data encrypted at rest
+3. **Token Validation**: Every protected request validates Firebase token
+4. **Rate Limiting**: Monthly chat limits per provider
+5. **Session Management**: Anonymous sessions for patient privacy
+
+---
+
+## 🚀 Deployment
+
+### Local Development
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Set environment variables
+cp .env.example .env
+# Edit .env with your API keys
+
+# 3. Start development server
+npm run dev
+# Server runs on http://localhost:8080
+```
+
+### Environment Variables
+
+```bash
+# .env file
+DEEPSEEK_API_KEY=your_deepseek_key
+GEMINI_API_KEY=your_gemini_key
+FIREBASE_SERVICE_ACCOUNT=path/to/service-account.json
+```
+
+### Production Deployment
+
+```bash
+# 1. Build and deploy to Firebase
+firebase deploy
+
+# This deploys:
+# - Hosting (static files in public/)
+# - Cloud Functions (functions/src/index.js)
+# - Firestore rules (firestore.rules)
+```
+
+### Hosting Configuration (`firebase.json`)
+
+```json
+{
+  "hosting": {
+    "public": "public",
+    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
+    "rewrites": [
+      {
+        "source": "**",
+        "function": "api"
+      }
+    ]
+  },
+  "functions": {
+    "source": "functions"
+  }
+}
+```
+
+---
+
+## 📊 Data Flow
+
+### Patient Chat Flow
+
+```
+1. Patient opens doctor's unique link
+   → GET /api/provider?handle=dr-sarah-amina
+
+2. Page loads with doctor's branding and topics
+
+3. Patient selects topic and types message
+
+4. Frontend sends POST /api/chat
+   {
+     handle: "dr-sarah-amina",
+     sessionId: "anon-uuid",
+     message: "What should I do about fever?",
+     topic: "general_health_info"
+   }
+
+5. Backend processes:
+   a. Validates provider exists and is published
+   b. Checks monthly usage limits
+   c. Analyzes message for safety (PII, red flags)
+   d. Saves user message to Firestore
+   e. Calls AI (DeepSeek → Gemini fallback)
+   f. Analyzes AI response for safety
+   g. Saves AI response to Firestore
+   h. Returns response to patient
+
+6. Patient sees AI response instantly
+
+7. If escalated:
+   a. Safety event logged
+   b. Conversation marked as escalated
+   c. Doctor sees alert in inbox
+```
+
+### Doctor Inbox Flow
+
+```
+1. Doctor signs in
+   → Firebase Auth validates
+
+2. Opens inbox
+   → GET /api/conversations
+
+3. Backend returns:
+   - All conversations for this doctor
+   - Sorted by last message time
+   - With escalation flags
+
+4. Doctor clicks conversation
+   → GET /api/conversation/:id
+
+5. Backend returns:
+   - Full conversation details
+   - All messages (user + AI)
+   - Patient contact info if provided
+
+6. Doctor reviews and can reply (coming soon)
+```
+
+---
+
+## 🎨 Frontend Architecture
+
+### Tech Stack
+- **Vanilla JavaScript**: No frameworks, fast loading
+- **CSS3**: Modern styling with CSS Grid and Flexbox
+- **Firebase SDK**: Client-side auth and real-time updates
+
+### Key Components
+
+#### Patient Chat (`public/chat.html` + `public/js/chat.js`)
+- Topic selection dropdown
+- Message composer
+- Chat message display
+- Session management
+- AI response rendering
+
+#### Doctor Dashboard (`public/app/index.html` + `public/app/app.js`)
+- Authentication UI
+- Profile onboarding
+- Topic configuration
+- Branding customization
+- Link sharing tools
+
+#### Doctor Inbox (`public/app/inbox.html` + `public/app/inbox.js`)
+- Conversation list with filters
+- Message history viewer
+- Patient contact display
+- Escalation alerts
+- Reply interface (coming soon)
+
+#### Analytics (`public/app/analytics.html` + `public/app/analytics.js`)
+- Summary statistics cards
+- Doctor performance table
+- Time period filtering
+- Data visualization
+
+---
+
+## 🔧 Configuration
+
+### Topics Configuration
+
+Topics are defined in server code and can be enabled/disabled per doctor:
+
+```javascript
+const TOPICS = {
+  medication_info_safety: {
+    name: "Medication Information & Safety",
+    systemPrompt: "You are a helpful medical assistant...",
+    disclaimer: "This is not medical advice...",
+    redFlags: ["chest pain", "difficulty breathing", ...]
+  },
+  general_health_info: {
+    name: "General Health Information",
+    ...
+  },
+  ...
+};
+```
+
+### AI Model Configuration
+
+```javascript
+// DeepSeek Configuration
+{
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  model: 'deepseek-chat',
+  temperature: 0.7,
+  maxTokens: 800
+}
+
+// Gemini Configuration
+{
+  apiKey: process.env.GEMINI_API_KEY,
+  model: 'gemini-1.5-flash',
+  temperature: 0.7,
+  maxOutputTokens: 800
+}
+```
+
+---
+
+## 📈 Scalability Considerations
+
+### Current Limits
+- **Monthly chats per doctor**: Configurable (default: 1000)
+- **Message history**: 100 messages per conversation
+- **Concurrent users**: Limited by Firebase Spark plan
+
+### Scaling Strategy
+1. **Horizontal Scaling**: Firebase auto-scales Cloud Functions
+2. **Database Sharding**: Firestore automatically distributes data
+3. **CDN**: Static assets served via Firebase CDN
+4. **Caching**: Implement Redis for frequently accessed data
+5. **Load Balancing**: Firebase handles automatically
+
+### Performance Optimizations
+- Lazy loading of conversation messages
+- Pagination for large datasets
+- Debounced search inputs
+- Optimistic UI updates
+- Service worker for offline support (future)
+
+---
+
+## 🧪 Testing Strategy
+
+### Manual Testing Checklist
+- [ ] Patient can open doctor link
+- [ ] Chat interface loads correctly
+- [ ] AI responds to messages
+- [ ] Messages saved to database
+- [ ] Doctor inbox shows conversations
+- [ ] Escalations flagged correctly
+- [ ] Analytics display accurately
+
+### Future Automated Testing
+- Unit tests for API endpoints
+- Integration tests for AI service
+- E2E tests for critical user flows
+- Load testing for scalability
+
+---
+
+## 📝 Monitoring & Logging
+
+### Current Logging
+- Console logs in server.js
+- Firebase Functions logs
+- Client-side error tracking (future)
+
+### Key Metrics to Track
+- Response time (API latency)
+- AI success/failure rates
+- Escalation frequency
+- User engagement (messages per session)
+- Doctor response times
+
+---
+
+## 🔮 Future Architecture Plans
+
+### Planned Enhancements
+
+1. **Real-time Updates**: WebSocket for live inbox refresh
+2. **Push Notifications**: FCM for doctor alerts
+3. **Payment Integration**: Stripe for subscriptions
+4. **Advanced Analytics**: BigQuery for complex queries
+5. **Multi-language**: i18n support
+6. **Microservices**: Separate AI service
+7. **CDN Optimization**: Cloudflare integration
+8. **Monitoring**: Sentry for error tracking
+
+---
+
+## 📚 Related Documentation
+
+- [PLATFORM_OVERVIEW.md](./PLATFORM_OVERVIEW.md) - High-level platform description
+- [DOCTOR_TUTORIAL.md](./DOCTOR_TUTORIAL.md) - Doctor user guide
+- [PATIENT_GUIDE.md](./PATIENT_GUIDE.md) - Patient user guide
+- [Firebase Documentation](https://firebase.google.com/docs)
+- [DeepSeek API Docs](https://platform.deepseek.com/docs)
+- [Gemini API Docs](https://ai.google.dev/docs)
+
+---
+
+*Last Updated: January 2026*
+*Version: 1.0*