docs: consolidate all integration guides into single master API_INTEGRATION_GUIDE.md

2026-08-31 14:06:48 +05:30
parent e91cdbae6e
commit 0cd932dbce
6 changed files with 378 additions and 756 deletions
@@ -1,4 +1,4 @@
-# AI Patient Onboarding API — Frontend Integration Guide
+# AI Patient Onboarding API — Complete Frontend Integration Guide

 **Version**: `1.0.0`  
 **Target Audience**: Frontend Engineers (React / React Native / Vue / Next.js / Mobile)  
@@ -13,7 +13,9 @@

 ## 1. Executive System Overview

-The **AI Patient Onboarding API** is an enterprise multi-modal clinical intake system designed for hospitals, clinics, and digital health platforms. It automates patient registration, symptom intake, medical history collection, document extraction, and specialty triage before a physician consultation.
+The **AI Patient Onboarding API** is an enterprise multi-modal clinical intake system designed for hospitals, clinics, a
+
+nd digital health platforms. It automates patient registration, symptom intake, medical history collection, document extraction, and specialty triage before a physician consultation.

 ### Key Capabilities for Frontend Applications:
 1. **Multi-Modal Onboarding**:
@@ -60,21 +62,7 @@ The backend enforces production-safe `CORSMiddleware`.

 ---

-## 4. Documentation Index
-
-To explore detailed specifications, refer to the following module guides:
-
-| Module Guide | Focus Area | Description |
-| :--- | :--- | :--- |
-| [`AUTHENTICATION.md`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/docs/AUTHENTICATION.md) | Security & Headers | Bearer tokens, `X-API-Key`, patient session isolation (IDOR protection). |
-| [`ONBOARDING_API.md`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/docs/ONBOARDING_API.md) | Text & Document Intake | Full specification for text chat endpoints, document OCR, and session completion. |
-| [`VOICE_ONBOARDING_API.md`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/docs/VOICE_ONBOARDING_API.md) | Voice & Speech APIs | Audio streaming, WebSpeech fallbacks, multilingual Sarvam AI voice turns. |
-| [`ERROR_HANDLING.md`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/docs/ERROR_HANDLING.md) | Error Codes & SLAs | HTTP 401, 403, 413, 422, 429 status codes and SLA latency boundaries. |
-| [`FRONTEND_EXAMPLES.md`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/docs/FRONTEND_EXAMPLES.md) | TypeScript & React | Copy-pasteable React hooks, MediaRecorder voice capture, and fetch client examples. |
-
---
-
-## 5. Master API Endpoint Directory
+## 4. Master API Endpoint Directory

 | HTTP Method | Endpoint Path | Auth Required | Rate Limit | Purpose |
 | :--- | :--- | :--- | :--- | :--- |
@@ -90,18 +78,387 @@ To explore detailed specifications, refer to the following module guides:

 ---

-## 6. Response Time & Timing Metadata
+## 5. Authentication & Patient Security

-All interactive conversation endpoints append performance metadata to help frontend applications measure latency:
+### Authentication Mechanisms:

+#### Method A: HTTP Bearer Token (Standard)
+```http
+Authorization: Bearer <ACCESS_TOKEN>
+```
+
+#### Method B: `X-API-Key` Custom Header
+```http
+X-API-Key: <API_KEY>
+```
+
+### Supported Access Tokens:
+1. **Service Secret API Key**: `skyheal_secure_api_key_2026` (configurable via `API_SECRET_KEY` in server environment).
+2. **Patient Development Tokens**: `test_token_<PATIENT_ID>` (e.g. `test_token_PAT-10023`). Automatically establishes patient identity context.
+
+### Patient Isolation & IDOR Protection Rules:
+1. When starting a session (`/v1/onboarding/start`), `patient.id` is bound as session owner (`session.patient_id`).
+2. Subsequent requests verify caller's authenticated `patient_id` matches session owner.
+3. Access attempts by other patients return **`HTTP 403 Forbidden`**.
+
+---
+
+## 6. Text Onboarding API Specifications
+
+### 6.1. POST `/v1/onboarding/start`
+
+Starts a new text-based clinical onboarding intake session.
+
+#### Request Headers:
+```http
+Content-Type: application/json
+Authorization: Bearer test_token_PAT-10023
+```
+
+#### Request Body (`StartOnboardingRequest`):
+```json
+{
+  "patient": {
+    "id": "PAT-10023",
+    "name": "Kavitha Ramesh",
+    "age": 35,
+    "gender": "female",
+    "phone": "+919876543210",
+    "abha_id": "91-1234-5678-9012",
+    "insurance_scheme": "PMJAY",
+    "dietary_habits": "Vegetarian"
+  },
+  "category": {
+    "type": "general",
+    "code": "general_medicine",
+    "name": "General Medicine"
+  },
+  "language": "en"
+}
+```
+
+#### Field Descriptions:
+
+| Field | Type | Required | Validation Rules | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `patient.id` | string | **Yes** | Min length 1 | Unique patient identifier |
+| `patient.name` | string | No | Optional | Full name of patient |
+| `patient.age` | integer | No | $0 \le \text{age} \le 120$ | Patient age in years |
+| `patient.gender` | string | No | Optional | Gender identity ("male", "female", "other") |
+| `category.type` | string | **Yes** | `"general"` or `"speciality"` | Onboarding workflow type |
+| `category.code` | string | **Yes** | Min length 1 | Specialty classification code |
+| `category.name` | string | **Yes** | Min length 1 | Category display name |
+| `language` | string | No | Default `"en"` | Preferred intake language |
+
+#### Successful Response (`200 OK` - `StartOnboardingResponse`):
 ```json
 {
  "success": true,
  "session_id": "ONB-8F12A9C4",
+  "patient_id": "PAT-10023",
+  "category": {
+    "type": "general",
+    "code": "general_medicine",
+    "name": "General Medicine"
+  },
+  "language": "en",
+  "status": "in_progress",
+  "stage": "symptoms",
+  "message": "Hello Kavitha Ramesh! I am your clinical onboarding assistant. What symptoms are you experiencing today?"
+}
+```
+
+---
+
+### 6.2. POST `/v1/onboarding/{session_id}/message`
+
+Sends a patient chat response to the AI intake orchestrator.
+
+#### Request Body (`SendMessageRequest`):
+```json
+{
+  "message": "I have had severe chest tightness and shortness of breath for 2 days."
+}
+```
+
+#### Successful Response (`200 OK` - `SendMessageResponse`):
+```json
+{
+  "success": true,
+  "session_id": "ONB-8F12A9C4",
+  "stage": "medical_history",
+  "message": "Thank you for sharing. Does the chest tightness radiate to your arm or jaw, and do you have any history of high blood pressure?",
+  "status": "in_progress",
  "response_time_ms": 1529.74,
  "response_time_sec": 1.53
 }
 ```

- `response_time_ms`: Backend processing duration in milliseconds (floating-point number).
- `response_time_sec`: Backend processing duration in seconds (rounded to 3 decimal places).
+---
+
+### 6.3. POST `/v1/onboarding/{session_id}/complete`
+
+Finalizes the intake session and outputs the structured clinical EHR payload.
+
+#### Request Body (`CompleteOnboardingRequest`):
+```json
+{
+  "confirmed": true
+}
+```
+
+#### Successful Response (`200 OK` - `CompleteOnboardingResponse`):
+```json
+{
+  "success": true,
+  "session_id": "ONB-8F12A9C4",
+  "status": "completed",
+  "result": {
+    "patient_id": "PAT-10023",
+    "abha_id": "91-1234-5678-9012",
+    "phone": "+919876543210",
+    "insurance_scheme": "PMJAY",
+    "category": {
+      "type": "general",
+      "code": "general_medicine",
+      "name": "General Medicine"
+    },
+    "chief_complaint": "Chest tightness and shortness of breath for 2 days",
+    "symptoms": [
+      {
+        "name": "Chest tightness",
+        "duration": "2 days",
+        "severity": "severe",
+        "description": "Triggered during exertion"
+      }
+    ],
+    "medical_history": ["Prehypertension"],
+    "medications": ["Metformin 500mg"],
+    "allergies": ["Penicillin"],
+    "dietary_habits": "Vegetarian",
+    "additional_information": "Patient confirmed details.",
+    "language": "en",
+    "onboarding_completed": true
+  },
+  "message": "Onboarding successfully completed and saved to patient record.",
+  "response_time_ms": 4075.41,
+  "response_time_sec": 4.08
+}
+```
+
+---
+
+## 7. Voice Onboarding API Specifications
+
+### 7.1. POST `/v1/voice-onboarding/start`
+
+Starts a voice-first onboarding session with Sarvam AI multilingual speech engine.
+
+#### Supported Languages:
+`en-IN` (Indian English), `ta-IN` (Tamil), `hi-IN` (Hindi), `te-IN` (Telugu), `kn-IN` (Kannada), `ml-IN` (Malayalam), `mr-IN` (Marathi).
+
+#### Request Body:
+```json
+{
+  "patient": {
+    "id": "PAT-VOICE-1",
+    "name": "Ramesh G",
+    "age": 34,
+    "gender": "male"
+  },
+  "category": {
+    "type": "general",
+    "code": "general_medicine",
+    "name": "General Medicine"
+  },
+  "language": "ta-IN"
+}
+```
+
+#### Successful Response (`200 OK`):
+```json
+{
+  "success": true,
+  "session_id": "VOICE-D3CAEA5C",
+  "patient_id": "PAT-VOICE-1",
+  "category": {
+    "type": "general",
+    "code": "general_medicine",
+    "name": "General Medicine"
+  },
+  "language": "ta-IN",
+  "status": "in_progress",
+  "stage": "greeting",
+  "greeting_text": "வணக்கம் Ramesh G, CureSelect மருத்துவமனைக்கு வரவேற்கிறோம். இன்று உங்களுக்கு என்ன சுகவீனம் உள்ளது?",
+  "audio_url": "/v1/voice-onboarding/audio/aud_a1b2c3d4e5f6",
+  "response_time_ms": 78.32,
+  "response_time_sec": 0.08
+}
+```
+
+---
+
+### 7.2. POST `/v1/voice-onboarding/{session_id}/turn`
+
+Processes a conversational voice turn using audio recording or text fallback.
+
+#### Multipart Form Data:
+- `audio`: Binary audio recording file (`WAV`, `WEBM`, `MP3`, `OGG` up to 10MB).
+- `text_fallback`: String text transcript (used if WebSpeech STT processed client-side).
+
+#### Successful Response (`200 OK`):
+```json
+{
+  "success": true,
+  "session_id": "VOICE-D3CAEA5C",
+  "patient_transcript": "எனக்குகடந்த 3 நாளா நெஞ்சு பாரமா இருக்குங்க.",
+  "ai_text": "நன்றி. இந்த நெஞ்சு பாரம் உடற்பயிற்சி செய்யும் போது அதிகமாகிறதா?",
+  "stage": "symptoms",
+  "completed": false,
+  "audio_url": "/v1/voice-onboarding/audio/aud_f9e8d7c6b5a4",
+  "audio_base64": null,
+  "suggested_specialty": {
+    "specialty": "Cardiology",
+    "reason": "Chest tightness reported"
+  },
+  "response_time_ms": 1412.37,
+  "response_time_sec": 1.41
+}
+```
+
+---
+
+### 7.3. GET `/v1/voice-onboarding/audio/{audio_id}`
+
+Streams generated TTS audio for browser or mobile playback.
+
+```javascript
+const audio = new Audio(`${BASE_URL}/v1/voice-onboarding/audio/${audioId}`);
+await audio.play();
+```
+
+---
+
+## 8. Medical Document Analysis API
+
+### POST `/v1/documents/{session_id}/upload`
+
+Uploads a medical report / prescription for vision extraction.
+
+- **Content-Type**: `multipart/form-data`
+- **File Limit**: Max `10MB` (`10,485,760 bytes`).
+- **Allowed Formats**: `image/jpeg`, `image/png`, `image/webp`, `application/pdf`.
+
+#### Successful Response (`200 OK`):
+```json
+{
+  "success": true,
+  "session_id": "ONB-8F12A9C4",
+  "document_type": "lab_report",
+  "summary": "Report indicates elevated HbA1c (7.2%) and stage 1 hypertension (130/85 mmHg).",
+  "findings": [
+    {
+      "test": "HbA1c",
+      "value": "7.2",
+      "unit": "%",
+      "interpretation": "Elevated"
+    }
+  ],
+  "medications_found": ["Metformin 500mg"],
+  "allergies_found": ["Penicillin"],
+  "message": "Medical document analyzed and integrated into onboarding session."
+}
+```
+
+---
+
+## 9. Error Handling & Status Codes
+
+| HTTP Status Code | Meaning | Cause & Resolution |
+| :--- | :--- | :--- |
+| `400 Bad Request` | Bad Request | Invalid category or unsupported file format. |
+| `401 Unauthorized` | Unauthorized | Missing or invalid `Authorization: Bearer` or `X-API-Key` header. |
+| `403 Forbidden` | Forbidden (IDOR) | Authenticated `patient_id` does not match session owner. |
+| `404 Not Found` | Not Found | Session ID does not exist in backend database. |
+| `413 Payload Too Large` | File Too Large | Uploaded document exceeds 10MB limit. |
+| `422 Validation Error` | Pydantic Error | Request body violates schema rules (e.g. `age < 0`). |
+| `429 Too Many Requests` | Rate Limited | Exceeded rate limit bucket (30 req/min). Check `Retry-After` header. |
+| `500 Internal Error` | Server Error | Unhandled backend failure. |
+
+---
+
+## 10. Frontend React & TypeScript Implementation Examples
+
+### React API Client (`src/api/onboardingClient.ts`)
+
+```typescript
+const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000';
+
+export interface PatientContext {
+  id: string;
+  name?: string;
+  age?: number;
+  gender?: string;
+  phone?: string;
+  abha_id?: string;
+}
+
+export interface CategoryContext {
+  type: 'general' | 'speciality';
+  code: string;
+  name: string;
+}
+
+async function fetchApi<T>(endpoint: string, options: RequestInit = {}, patientId: string): Promise<T> {
+  const token = `test_token_${patientId}`;
+  const headers = new Headers(options.headers || {});
+  headers.set('Authorization', `Bearer ${token}`);
+  if (!(options.body instanceof FormData)) {
+    headers.set('Content-Type', 'application/json');
+  }
+
+  const response = await fetch(`${API_BASE_URL}${endpoint}`, { ...options, headers });
+  if (!response.ok) {
+    const errorBody = await response.json().catch(() => ({ detail: 'Network response error' }));
+    throw new Error(errorBody.detail || `HTTP Error ${response.status}`);
+  }
+  return response.json();
+}
+
+export async function startOnboarding(patient: PatientContext, category: CategoryContext, language: string = 'en') {
+  return fetchApi<any>('/v1/onboarding/start', {
+    method: 'POST',
+    body: JSON.stringify({ patient, category, language }),
+  }, patient.id);
+}
+
+export async function sendMessage(sessionId: string, patientId: string, message: string) {
+  return fetchApi<any>(`/v1/onboarding/${sessionId}/message`, {
+    method: 'POST',
+    body: JSON.stringify({ message }),
+  }, patientId);
+}
+
+export async function completeOnboarding(sessionId: string, patientId: string, confirmed: boolean = true) {
+  return fetchApi<any>(`/v1/onboarding/${sessionId}/complete`, {
+    method: 'POST',
+    body: JSON.stringify({ confirmed }),
+  }, patientId);
+}
+```
+
+---
+
+## 11. Frontend Integration Checklist
+
+```text
+[ ] Configure API_BASE_URL in environment (VITE_API_BASE_URL=http://localhost:8000)
+[ ] Verify CORS preflight request from localhost:3000 / localhost:5173
+[ ] Attach Authorization: Bearer test_token_<PATIENT_ID> header
+[ ] Call POST /v1/onboarding/start and store session_id
+[ ] Multi-turn chat message sending via POST /v1/onboarding/{session_id}/message
+[ ] Handle 401 Unauthorized & 403 Forbidden errors
+[ ] Upload medical documents via POST /v1/documents/{session_id}/upload (10MB max)
+[ ] Call POST /v1/onboarding/{session_id}/complete to retrieve final PatientOnboardingResult
+[ ] Test voice onboarding audio streaming via GET /v1/voice-onboarding/audio/{audio_id}
+```