System Architecture

One Health is a patient-centric care network composed of independently deployable services that communicate via HTTP + JWT, share immutable schemas through a versioned contracts package, and persist to a single MongoDB Atlas cluster.

Block diagram — services + responsibilities

Service-by-service responsibility matrix

Service	Port	Language	Owns	Does NOT own
apps/web	6200	Next.js 15 / React 19	UI, MSAL + GIS auth bootstrap, session-cookie validation at edge	Business logic, encryption, DB access
apps/api	6201	NestJS 10 / TypeScript strict	22 modules of business domain, envelope encryption at repo boundary, CSRF, rate limiting, RBAC + consent guards, hash-chained audit	UI rendering, LLM calls, retrieval
apps/ml	6202	FastAPI / Python 3.12 / Pydantic v2	ASR + NER + CDS + Coding AI; sanitize → delimit → de-ID → schema-validate → audit pipeline; dual-LLM with audited fallback	PHI at rest (all PHI lives in api's DB)
memory-store	6401	FastAPI / motor	Knowledge graph CRUD, hybrid retrieval (4 routes + classifier + serializer + audit), MCP server for Claude Code	Agent orchestration
research-engine	6402	FastAPI / motor	5 agents (Researcher / Critic / Correlator / Replicator / Librarian), 12 trusted-source connectors, change-stream promotion pipeline	Data persistence (uses memory-store HTTP)
orchestrator	6403	FastAPI / motor	Hypothesis candidate lifecycle (6 phases), feasibility scoring, stakeholder approval, dispatch scheduling	LLM calls (delegates to research-engine)
model-optimization	6404	FastAPI / motor	Decision graph (15 node types), trace capture, DPO pair builder, outcome feedback, benchmark harness	None (read-only consumer of other tiers' audit trails)

Deployment topology

Cross-service comms — inviolable rules

1. HTTP + JWT only (FR-KIA-012). No shared database connections, no direct Python imports across services, no message-bus short-circuits.
2. Shared schemas through packages/patientrx-contracts/ only. Single canonical source; no duplication. Published as contracts-v1.0.0 to GitHub Release + local mirror. See the consolidation PR #167 for how we eliminated the duplicate tree.
3. Every inter-service call is audited on the caller side with {source, target, action, latency, outcome}.
4. Failures fail-soft with audit trail — LLM fallback (FR-021a), retrieval fallback (SPEC-06), consent-service-unavailable → 500 with generic body.
5. Rate limits per-consumer — the retrieve endpoint is 100/min; consumers use admin-token bypass for batch workloads.

What sits outside the diagram

• GitHub Actions CI — 10+ required checks per PR (gitleaks, Semgrep, Trivy, npm-audit, pip-audit, group3-contract-tests, pattern-consistency, docs-coverage, mandatory-hooks-checklist, compliance-checklist)
• Claude Code harness — 11 pre-edit / pre-bash / stop hooks at the developer's environment layer that block known anti-patterns at authoring time
• BAA registry — apps/api/src/config/baa-registry.yml; every outbound vendor registered + fail-closed on unsigned in prod

Deeper

• Research AI block diagram → — zoom into the 4 research services
• Auth + consent flow → — how a request crosses the trust boundary
• Audit chain → — how tamper-evidence works
• Data model → — the 36+ collections + their encryption posture