Complete Service Stubs: RAG, Audio Capture, FHIR Adapter, Agent Orchestrator

[Sakeeb91]

Priority

P1

Story Points

34 (8 + 8 + 13 + 5 for orchestrator)

Dependencies

Depends on #6 (Shared Libraries), #22 (Service Communication)

Summary

Implement the 4 remaining service stubs to complete the core platform architecture: RAG service for AI-enhanced document retrieval, Audio Capture service for medical dictation, FHIR Adapter for healthcare data interoperability, and Agent Orchestrator for multi-service workflows.

Background

Currently these services are empty stubs:

1. RAG Service (services/rag) - Retrieval-augmented generation for clinical documentation
2. Audio Capture Service (services/audio-capture) - Audio recording and streaming
3. FHIR Adapter Service (services/fhir-adapter) - FHIR resource transformation
4. Agent Orchestrator Service (services/agent-orchestrator) - Workflow orchestration

Service Breakdown

1. RAG Service (8 story points)

Purpose: Provide context-aware AI assistance for clinical documentation using retrieval-augmented generation.

Key Features:

• Vector embedding generation for clinical documents
• Semantic search over patient history
• Context retrieval for AI prompts
• Integration with vector database (pgvector)
• Integration with LLM providers (OpenAI, Anthropic)

Endpoints:

• POST /embeddings - Generate embeddings for documents
• POST /search - Semantic search over documents
• POST /retrieve-context - Get relevant context for prompt
• GET /health - Health check

Tech Stack:

• Node.js/TypeScript
• pgvector for vector storage
• OpenAI embeddings API
• LangChain for RAG pipeline

---

2. Audio Capture Service (8 story points)

Purpose: Handle audio recording, storage, and streaming for medical dictation workflows.

Key Features:

• Real-time audio streaming via WebSocket
• Audio file upload and storage (S3)
• Audio format conversion
• Audio quality validation
• Integration with transcription service

Endpoints:

• WebSocket /stream - Real-time audio streaming
• POST /upload - Upload audio file
• GET /audio/:id - Retrieve audio file
• GET /audio/:id/metadata - Get audio metadata
• DELETE /audio/:id - Delete audio file

Tech Stack:

• Node.js/TypeScript
• WebSocket for streaming
• AWS S3 for storage
• FFmpeg for format conversion

---

3. FHIR Adapter Service (13 story points)

Purpose: Transform ScribeMed data to/from FHIR R4 format for healthcare interoperability.

Key Features:

• FHIR R4 resource transformation (Patient, Encounter, Observation, etc.)
• FHIR validation
• Integration with EHR systems
• FHIR search API
• Bulk FHIR export

Endpoints:

• GET /Patient/:id - Get FHIR Patient resource
• GET /Encounter/:id - Get FHIR Encounter resource
• GET /Observation/:id - Get FHIR Observation resource
• POST /Patient - Create FHIR Patient
• GET /Patient?identifier=:mrn - Search patients
• POST /$export - Bulk FHIR export

Tech Stack:

• Node.js/TypeScript
• HAPI FHIR validator
• FHIR R4 specification
• Integration with ScribeMed database

FHIR Resource Mappings:

ScribeMed → FHIR R4
---------------------
patients → Patient
encounters → Encounter
notes → DocumentReference / DiagnosticReport
vitals → Observation
prescriptions → MedicationRequest
providers → Practitioner
organizations → Organization

---

4. Agent Orchestrator Service (5 story points)

Purpose: Coordinate multi-service workflows for complex clinical documentation tasks.

Key Features:

• Workflow definition and execution
• Service coordination (transcription → RAG → documentation → coding)
• State management for long-running workflows
• Error handling and retry logic
• Workflow monitoring and logging

Example Workflow:

1. Audio uploaded to Audio Capture Service
2. Orchestrator triggers Transcription Service
3. Transcription complete → Orchestrator retrieves result
4. Orchestrator calls RAG Service for context
5. Orchestrator calls Documentation Service to generate note
6. Orchestrator calls Coding Service for ICD-10/CPT codes
7. Final result aggregated and returned

Endpoints:

• POST /workflows - Start new workflow
• GET /workflows/:id - Get workflow status
• GET /workflows/:id/steps - Get workflow execution steps
• DELETE /workflows/:id - Cancel workflow

Tech Stack:

• Node.js/TypeScript
• Workflow state machine
• Service clients from Service-to-Service Communication & Integration Patterns #22
• Event-driven architecture

---

Acceptance Criteria

RAG Service:

• Vector embeddings generation working
• Semantic search returns relevant results
• Context retrieval integrated with LLM
• Tests for embedding and search
• Documentation with usage examples

Audio Capture Service:

• WebSocket streaming functional
• File upload with validation working
• S3 integration complete
• Audio format conversion working
• Tests for upload and streaming

FHIR Adapter:

• At least 5 FHIR resources supported (Patient, Encounter, Observation, DocumentReference, Practitioner)
• FHIR validation passing
• Search API working
• Bulk export functional
• Tests for transformation and validation
• FHIR compliance verified

Agent Orchestrator:

• End-to-end workflow execution working
• Service coordination functional
• Error handling and retries working
• Workflow state persistence
• Tests for workflow execution
• Monitoring and logging complete

Implementation Timeline

Month 1:

• Week 1-2: RAG Service
• Week 3-4: Audio Capture Service

Month 2:

• Week 1-3: FHIR Adapter Service
• Week 4: Agent Orchestrator Service

Testing Requirements

• Unit tests for each service (70%+ coverage)
• Integration tests for service communication
• E2E tests for complete workflows
• FHIR compliance testing
• Performance testing for RAG search

Documentation

• Service README for each service
• API documentation
• FHIR mapping documentation
• Workflow examples
• Integration guides

Status

Open

Related Issues

• Shared Libraries Package Setup #6: Shared Libraries Package Setup
• Service-to-Service Communication & Integration Patterns #22: Service-to-Service Communication Patterns
• Comprehensive Testing Infrastructure & Coverage Requirements #19: Comprehensive Testing Infrastructure