openevidence-reference-architecture

# OpenEvidence Reference Architecture ## Overview Production architecture for clinical decision support integrations with OpenEvidence. Designed for healthcare platforms needing evidence-based query processing, citation-backed clinical answers, and full audit logging for regulatory compliance. Key design drivers: HIPAA-compliant data handling, deterministic citation pipelines for clinical accuracy, query audit trails for malpractice risk mitigation, and sub-second response times for point-of-care workflows where clinicians need answers during patient encounters. ## Architecture Diagram ``` Clinician UI ──→ API Gateway (auth + HIPAA) ──→ Query Service ──→ OpenEvidence API ↓ ↓ /query Audit Logger ──→ Audit DB Cache (Redis) /citations ↓ ↓ Analytics ──→ Usage Dashboard Citation Store ──→ Evidence DB ``` ## Service Layer ```typescript class ClinicalQueryService { constructor(private oe: OpenEvidenceClient, private cache: CacheLayer, private audit: AuditLogger) {} async queryEvidence(query: ClinicalQuery): Promise<EvidenceResponse> { await this.audit.log({ type: 'query_submitted', clinicianId: query.clinicianId, queryText: query.text, timestamp: new Date() }); const cacheKey = `evidence:${this.hashQuery(query.text)}`; const cached = await this.cache.get(cacheKey); if (cached) { await this.audit.log(...