Healthbridge

Problem

Healthcare interoperability is a demanding backend exercise: strict contracts, authorization boundaries, asynchronous processing, safe retries, traceability, and explicit handling of sensitive information. I wanted an implementation whose engineering choices could be inspected without pretending to be a clinical product.

My role and ownership

I designed and implemented the reference system, including API contracts, FHIR validation, event flow, identity integration, persistence behavior, observability, containerized development, tests, and CI.

Constraints

• The demonstration must use synthetic data only and never imply production clinical readiness.
• Authentication must fail closed outside an explicit local-development mode.
• At-least-once delivery can create duplicate events.
• Operational telemetry must not expose resource bodies or patient identifiers.
• A reviewer should be able to run the whole system locally and inspect failure behavior.

Architecture or walkthrough

FHIR clients authenticate through Keycloak and send resources to FastAPI. SMTP and MCP connectors provide additional synthetic input paths. Accepted work enters Redpanda; a validation worker parses the FHIR R4 resource before an idempotent MongoDB upsert. OpenTelemetry, Prometheus, and Grafana observe the path without collecting clinical payloads.

Important decisions

1. Identity fails closed

Context: Local demos benefit from easy startup, but permissive authentication can accidentally escape into a deployed environment.

Choice: Use OIDC discovery, cached JWKS, RSA-only verification, and explicit scopes; bypass behavior exists only behind a deliberate local setting.

Reason: Secure failure is the right default when configuration is missing or identity infrastructure is unavailable.

Tradeoff: Local setup requires more moving parts than a hardcoded token.

2. Ingestion and validation are asynchronous

Context: Validation, enrichment, and persistence should not extend the client request or couple producers to storage availability.

Choice: Acknowledge accepted input at the API boundary and move processing through Redpanda.

Reason: The event boundary absorbs bursts and gives retry, replay, and dead-letter behavior a clear home.

Tradeoff: Clients receive acceptance before final persistence and need a separate way to observe processing status.

3. Persistence is idempotent

Context: At-least-once delivery means the same resource may be handled more than once.

Choice: Upsert against stable resource identity and make repeated processing safe.

Reason: Duplicate delivery should not create duplicate clinical records or require perfect broker behavior.

Tradeoff: Identity and update semantics become part of the data contract.

4. Synthetic-only is an architectural boundary

Context: A polished healthcare demo can be mistaken for a compliant clinical platform.

Choice: Keep fixtures synthetic, state the boundary in the repository and interface, and exclude resource bodies from telemetry.

Reason: Demonstrating sound engineering is compatible with being precise about what has not been validated.

Tradeoff: The project cannot claim production healthcare experience or compliance.

Defensible outcome

The public repository demonstrates an end-to-end authenticated ingestion path, asynchronous validation, idempotent persistence, retries and dead-letter handling, metrics, traces, dashboards, automated tests, and CI using synthetic FHIR R4 data.

What I would improve

A production path would require managed infrastructure, TLS throughout, production identity configuration, formal threat modeling, disaster recovery, audit-retention policy, load testing, and review by healthcare security and domain specialists.