feat(api): production security, cors hardening, latency optimizations, postman artifacts & frontend documentation
This commit is contained in:
@@ -0,0 +1,107 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user