# AI Patient Onboarding API — Frontend Integration Guide

**Version**: `1.0.0`  
**Target Audience**: Frontend Engineers (React / React Native / Vue / Next.js / Mobile)  
**Backend Framework**: FastAPI (Python 3.13)  
**Supported Protocols**: HTTP/1.1 REST, JSON, Multipart/Form-Data Formats  
**Interactive API Documentation**:
- **Swagger UI**: `{BASE_URL}/docs`
- **ReDoc**: `{BASE_URL}/redoc`
- **OpenAPI Schema**: `{BASE_URL}/openapi.json`

---

## 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.

### Key Capabilities for Frontend Applications:
1. **Multi-Modal Onboarding**:
   - **Text-Based Onboarding**: Interactive chat-based intake powered by clinical LLM orchestrator.
   - **Voice-First Onboarding**: Natural conversational voice intake supporting English (`en-IN`), Tamil (`ta-IN`), Hindi (`hi-IN`), Telugu (`te-IN`), Kannada (`kn-IN`), Malayalam (`ml-IN`), and Marathi (`mr-IN`) using Sarvam AI ASR/TTS.
2. **Medical Document Analysis**: Vision-based processing of lab reports, prescriptions, and discharge summaries (JPEG, PNG, WEBP, PDF up to 10MB).
3. **Session-Based State Engine**: Stateful intake tracking stored in persistent backend database.
4. **Structured EHR Output**: Automatic clinical JSON result extraction matching standard Electronic Health Record (EHR) models.

---

## 2. Server Base URLs & CORS Configuration

### Server Base URLs:
- **Local Development**: `http://localhost:8000` or `http://127.0.0.1:8000`
- **Staging / Production**: Configured via environment variable (`{BASE_URL}`)

### CORS (Cross-Origin Resource Sharing) Policy:
The backend enforces production-safe `CORSMiddleware`.
- **Allowed Origins**: `http://localhost:3000`, `http://localhost:5173`, `http://127.0.0.1:3000`, `http://127.0.0.1:5173`, `https://onboarding.skyheal.ai` (configurable via `CORS_ORIGINS`).
- **Allowed Credentials**: `true` (`Access-Control-Allow-Credentials: true`).
- **Allowed Headers**: `Authorization`, `Content-Type`, `X-API-Key`, `X-Patient-ID`, `X-Request-ID`, `Accept`, `Origin`.
- **Exposed Headers**: `X-Request-ID`.

---

## 3. Quick Start Integration Flow

```
[ Frontend App ]
       │
       ├── 1. POST /v1/onboarding/start (or /v1/voice-onboarding/start)
       │      └─► Returns session_id (e.g. "ONB-8F12A9C4" or "VOICE-D3CAEA5C")
       │
       ├── 2. POST /v1/onboarding/{session_id}/message (or /turn for voice)
       │      └─► Exchanges multi-turn symptom history & receiving AI responses
       │
       ├── 3. POST /v1/documents/{session_id}/upload (Optional)
       │      └─► Uploads medical reports / lab results
       │
       └── 4. POST /v1/onboarding/{session_id}/complete
              └─► Returns final structured EHR result (PatientOnboardingResult)
```

---

## 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

| HTTP Method | Endpoint Path | Auth Required | Rate Limit | Purpose |
| :--- | :--- | :--- | :--- | :--- |
| `GET` | `/health` | No | None | Service health check & AI provider status |
| `POST` | `/v1/onboarding/start` | **Yes** | 30 req/min | Start text onboarding session |
| `POST` | `/v1/onboarding/{session_id}/message` | **Yes** | 30 req/min | Send text intake message to AI |
| `POST` | `/v1/onboarding/{session_id}/complete` | **Yes** | 30 req/min | Finalize text session & output structured result |
| `POST` | `/v1/voice-onboarding/start` | **Yes** | 30 req/min | Start voice onboarding session |
| `POST` | `/v1/voice-onboarding/{session_id}/turn` | **Yes** | 30 req/min | Process speech recording or text fallback turn |
| `POST` | `/v1/voice-onboarding/{session_id}/complete` | **Yes** | 30 req/min | Finalize voice session & output structured result |
| `GET` | `/v1/voice-onboarding/audio/{audio_id}` | No | None | Stream TTS audio response (WAV/MP3) |
| `POST` | `/v1/documents/{session_id}/upload` | **Yes** | 10 req/min | Upload medical document / report (10MB max) |

---

## 6. Response Time & Timing Metadata

All interactive conversation endpoints append performance metadata to help frontend applications measure latency:

```json
{
  "success": true,
  "session_id": "ONB-8F12A9C4",
  "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).