Introduction and Motivation

1. Introduction and Motivation

Digital health systems are usually built as a set of point solutions: an electronic health record (EHR) integration layer, a clinical alerting module, a research-data pipeline, an audit subsystem, and a consent-management process, each developed by a different team against a different set of assumptions about trust, data residency, and failure modes. The seams between these subsystems are where a large share of real-world harm originates — stale consent state feeding a research extract, an alerting rule silently changing behavior without an audit trail, or a federated model update that cannot be distinguished from an adversarial one.

MedIntelOS is structured as a direct response to that observation: rather than optimizing any one subsystem in isolation, it treats interoperability, decision support, federated computation, provenance, and consent as five faces of a single design problem, and asks what a codebase looks like when the boundaries between them are made explicit, typed, and independently testable.

The repository is unusually candid about its own maturity. Its README states plainly that it is an "alpha, educational system, not a production EHR, not a complete FHIR implementation, not a medical device, and not evidence of regulatory compliance." This wiki takes that framing seriously. Rather than evaluating MedIntelOS as a candidate for clinical deployment — a category error the maintainers themselves warn against — it evaluates the project as a piece of systems-engineering scholarship: a worked example of how to decompose a multi-stakeholder health-data platform into components whose guarantees can be reasoned about individually, and whose composition risk is documented rather than hidden.

1.1 Scope of This Wiki

This wiki analyzes the MedIntelOS repository as retrieved from source, covering the Python service layer (src/medintelos), the Solidity consent and audit contracts (contracts/), the accompanying documentation set (docs/), and the operational tooling (Docker, Compose, and CI configuration). It is organized around the six functional pillars the maintainers themselves identify in the project's implemented-scope table, plus dedicated treatment of security posture, deployment practice, and validation methodology.

Table 1. Implemented pillars and their explicit boundaries

Pillar	What is implemented	Explicit boundary
FHIR R5	JSON resource builders, in-memory CRUD, a narrow search subset, version IDs, ETags, a CapabilityStatement endpoint	Not a conformance-tested or persistent FHIR server
CDS Hooks / CDSS	Discovery endpoint and a patient-view service; qSOFA, NEWS2, an AKI rule, and a CHA₂DS₂-VASc helper	Educational rules only; not clinically validated
Federated learning	Sample-weighted aggregation, a pluggable update callback, a Gaussian differential-privacy experiment, basic outlier detection	No secure aggregation or formal privacy accountant
Audit	An in-memory SHA-256 hash chain over structured entries	Tamper-evident within one process; not durable or externally anchored
Consent	Solidity consent and audit-ledger contracts with Hardhat tests	Identity, legal authority, erasure, governance, and key custody remain off-chain
Operations	Docker, Compose, CI, linting, tests, generated API documentation	Production infrastructure is out of scope

1.2 Why a Unified Codebase Is a Meaningful Design Choice

A skeptical reading might ask why interoperability, decision support, federated learning, audit, and consent belong in the same repository at all, given that production deployments will typically source each capability from a different vendor or subsystem. The answer the codebase implicitly gives is pedagogical and architectural rather than operational: by keeping the five concerns in one place but behind clean module boundaries — a FastAPI process (api/app.py) that depends on, but does not entangle, fhir/, cdss.py, audit.py, and federated.py, plus a wholly separate Solidity codebase for consent — the project offers a single place to study how these systems' data contracts meet at runtime.

The System Architecture Overview page makes this composition, and the fact that no module directly calls into another's internals, visible with a diagram.

---

Next: Standards and Research Context →