System Architecture Overview

3. System Architecture Overview

MedIntelOS is organized as a small number of independently testable Python modules beneath a single FastAPI process, a parallel Solidity codebase for on-chain consent, and a documentation set that doubles as an explicit specification of production replacement points.

Figure 1 shows the system at the level of its principal actors and runtime boundaries: an EHR or research client interacting with the API through an API-key boundary; federated participant sites interacting with the aggregation coordinator; and patients, proxies, and verified institutions interacting with the consent contracts independently of the Python service.

flowchart TB
    subgraph Clients["External Actors"]
        EHR["EHR / Research Client"]
        Patient["Patient / Authorized Proxy"]
        Sites["Federated Participant Sites"]
        Institution["Verified Institution"]
    end

    subgraph API["FastAPI Boundary (medintelos.api.app)"]
        Auth["API-Key Authenticator"]
        MW["Size-Limit + Security-Header Middleware"]
        Routes["Routes: FHIR CRUD, CDS Hooks, CDSS Evaluate"]
    end

    subgraph Core["Domain Modules (src/medintelos)"]
        FHIR["FHIRStore\nIn-memory JSON repository"]
        CDSS["CDSSEngine\nRiskScorer + Alerts"]
        AUD["AuditChain\nSHA-256 hash chain"]
        FED["FederatedCoordinator\nWeighted aggregation"]
    end

    subgraph Chain["Consent Layer (Solidity)"]
        Consent["MedIntelOSConsentManager"]
        Ledger["MedIntelOSAuditLedger"]
    end

    EHR --> Auth
    Auth --> MW --> Routes
    Routes --> FHIR
    Routes --> CDSS
    Routes --> AUD
    Sites --> FED
    FED --> AUD
    Patient --> Consent
    Institution --> Consent
    Consent --> Ledger

Loading

Figure 1. MedIntelOS runtime architecture: external actors, the FastAPI boundary, the four core domain modules, and the Solidity consent layer.

Three design decisions are visible in this diagram and recur throughout the codebase:

1. A single authentication boundary. Every external interaction with the Python service passes through one object (APIKeyAuthenticator) before reaching any domain logic, which keeps the authorization boundary in one auditable place rather than scattered across route handlers.
2. No cross-module coupling. The four domain modules — the FHIR store, the CDSS engine, the audit chain, and the federated coordinator — do not call into one another; the API layer is the only component that composes them, which lets each module be unit-tested and, per the project's own "production replacement points" table, swapped independently.
3. An architecturally disjoint consent layer. The consent layer is a separate Solidity codebase, deployed to its own chain, that a production system would integrate through an oracle or off-chain worker rather than a direct function call. This separation is a deliberate acknowledgment that identity, legal capacity, and irrevocable on-chain history are governed by different rules than an in-process Python object.

3.1 Module Dependency Structure

Figure 2 makes the same boundary explicit at the level of source files. The API module (api/app.py) is the only file that imports from every domain module; each domain module's dependencies point inward toward shared primitives (config.py, audit.py) rather than outward toward the API layer or toward each other. The Solidity contracts and their Hardhat/TypeScript test suite form a wholly separate dependency graph, reflecting the fact that the consent layer is versioned, compiled, and deployed independently of the Python package.

flowchart TB
    app["api/app.py"] --> schemas["api/schemas.py"]
    app --> security["security.py"]
    app --> cdss["cdss.py"]
    app --> fhir_repo["fhir/repository.py"]
    app --> fhir_build["fhir/builders.py"]
    app --> audit["audit.py"]
    app --> config["config.py"]
    fhir_repo --> fhir_build
    security --> config
    federated["federated.py"] --> audit
    contracts["contracts/MedIntelOSConsent.sol"] --> contract_tests["contract-tests/consent.ts"]

Loading

Figure 2. Source-level module dependency graph. Arrows indicate an import relationship; the API module is the sole point of composition.

3.2 Repository Layout

src/medintelos/
  api/                 FastAPI routes and request validation
  fhir/                FHIR builders, parsers, and in-memory repository
  cdss.py              Clinical scoring and alert examples
  federated.py         Federated aggregation coordinator
  audit.py             Tamper-evident audit chain
  security.py          API authentication boundary
contracts/             Solidity consent and audit contracts
contract-tests/        Hardhat contract tests
tests/                 Python unit and API tests
docs/                  Architecture, threat model, and deployment notes
examples/              Synthetic requests only

• src/medintelos/api/ — FastAPI routes, Pydantic request/response schemas, and error-to-HTTP mapping.
• src/medintelos/fhir/ — FHIR resource builders, an in-memory repository, and a narrow search implementation.
• src/medintelos/cdss.py — Clinical scoring rules, alert construction, and CDS Hooks card serialization.
• src/medintelos/federated.py — The federated learning coordinator, aggregation strategies, and the Gaussian differential-privacy mechanism.
• src/medintelos/audit.py — The SHA-256 hash-chained, in-memory audit log.
• src/medintelos/security.py — The constant-time API-key authentication dependency.
• contracts/ — The Solidity consent-manager and audit-ledger contracts.
• contract-tests/ — Hardhat/Viem TypeScript tests for the consent contracts.
• tests/ — Python unit and API tests covering FHIR lifecycle, CDSS thresholds, aggregation math, audit chaining, and authentication.
• docs/ — Architecture, threat model, and deployment documentation.

3.3 Design Goals as Stated by the Maintainers

The project's own architecture documentation frames its design goal as separating interoperability, decision-support, model-coordination, audit, and consent concerns "so each can be tested or replaced independently," favoring "explicit boundaries over hidden integration." The architecture observed in source is consistent with that stated goal: there is no module in the Python package that reaches into another module's private state, every domain object is a plain dataclass or Pydantic model rather than a framework-coupled ORM entity, and the FastAPI application factory (create_app) accepts an injected Settings object rather than reading global configuration, which is what makes the module boundary testable rather than merely aspirational.

---

Previous: ← Standards and Research Context · Next: FHIR R5 Interoperability Layer →