Decentralized Medical Records Exchange (DMRX)

DMRX is an open-source, patient-controlled medical records exchange built around encrypted off-chain storage and Stellar/Soroban auditability.

The core idea: hospitals issue trusted records, patients control access, doctors receive temporary scoped permissions, and every access event is auditable without putting private medical files on-chain.

Google Drive for health records, but patient-owned, encrypted by default, and blockchain-auditable.

Vision

Medical records are often trapped inside hospital systems, shared through slow manual processes, or carried physically by patients. DMRX provides a portable exchange layer where records can be verified across institutions while patients remain in control.

DMRX is designed for hospitals, clinics, doctors, patients, HMOs, NGOs, rural health programs, governments, regulators, and telemedicine platforms.

Why Stellar

Stellar is useful for identity, fast verification, low-cost transactions, and multi-party trust systems. DMRX uses Stellar and Soroban for compact proofs, permission state, identity references, and audit logs.

DMRX does not use the blockchain as file storage. Clinical files stay encrypted off-chain. Stellar stores hashes, grants, revocations, and access proofs.

Core Principles

• Patient-controlled access.
• Medical files encrypted before upload.
• Minimal data on-chain.
• Signed records from verified institutions.
• Temporary and scoped permissions.
• Revocable access.
• Tamper detection with hashes.
• Fully auditable access history.
• Open-source and self-hostable.

Current Status

This repository is an implementation scaffold. It includes frontend app shells, backend service skeletons, starter Soroban contracts, shared TypeScript packages, Prisma metadata models, and monorepo configuration.

It is not production-ready yet. Authentication, deployed contracts, complete storage adapters, full tests, CI, and compliance hardening still need to be completed.

Architecture

Frontend Apps
  Patient Portal
  Hospital Dashboard
  Doctor Dashboard
        |
        v
Backend Services
  Auth Service
  Records Service
  Permissions Service
  Audit Service
        |
        v
---------------------------------------------------------------
| Stellar/Soroban | PostgreSQL | Redis | IPFS/S3/MinIO        |
| Contracts       | Metadata   | Cache | Encrypted files      |
---------------------------------------------------------------

On-Chain vs Off-Chain

Layer	Stores
Stellar/Soroban	record hashes, DID references, permission grants, revocations, access audit events, contract rules
PostgreSQL	actors, record metadata, permission metadata, audit references, chain transaction references
IPFS/S3/MinIO	encrypted PDFs, lab results, imaging files, prescriptions, notes, scans, audio, video

Main Actors

Actor	Capabilities
Patient	view records, grant access, revoke access, review audit logs, share temporary scoped access
Hospital	upload records, encrypt files, sign metadata, anchor hashes, verify authenticity
Doctor	request access, read authorized records, upload consultation notes, sign treatment entries
Regulator/Admin	verify institutions, monitor audits, review abuse reports, investigate emergency access

Repository Structure

dmrx/
  frontend/
    patient-portal/
    hospital-dashboard/
    doctor-dashboard/
  backend/
    auth-service/
    records-service/
    permissions-service/
    audit-service/
  contracts/
    identity/
    access-control/
    audit-log/
  packages/
    shared/
    crypto/
    database/
    stellar-client/
    storage/
  .env.example
  package.json
  pnpm-workspace.yaml
  tsconfig.base.json
  turbo.json

The main product folders are frontend/, backend/, and contracts/. The packages/ folder holds reusable code shared across apps and services.

Frontend Apps

App	Port	Purpose
frontend/patient-portal	3000	patient records, permissions, revocations, audit history
frontend/hospital-dashboard	3001	record upload, encryption, signing, hash anchoring
frontend/doctor-dashboard	3002	access requests, authorized record viewing, consultation notes

Backend Services

Service	Port	Starter endpoints	Responsibility
auth-service	4000	GET /api/auth/health, POST /api/auth/identities	wallet identity, DID profile, roles, sessions, institution verification
records-service	4010	GET /api/records/health, POST /api/records	encryption orchestration, metadata, hashing, storage, chain anchoring
permissions-service	4020	GET /api/permissions/health, POST /api/permissions/grants	grants, revocations, expiration, scoped access, emergency access
audit-service	4030	GET /api/audit/health, POST /api/audit/events	access logs, audit references, patient history, regulator queries

Shared Packages

Package	Purpose
packages/shared	domain types, actor roles, record scopes, audit actions
packages/crypto	hashing, AES encryption helpers, key wrapping interfaces
packages/database	Prisma schema and database client
packages/storage	S3/MinIO storage interface scaffold
packages/stellar-client	Stellar/Soroban client wrapper scaffold

Soroban Contracts

Contract	Purpose
contracts/identity	registers identity references, DID strings, roles, and verification state
contracts/access-control	stores grants, grantees, scopes, record references, expiration, revocation, emergency flags
contracts/audit-log	stores compact access proofs and emits audit events for indexers

Core Flows

Patient Registration

Connect wallet -> create DID profile -> store encrypted profile metadata -> register identity reference on-chain

Hospital Record Upload

Select patient DID -> upload file -> encrypt with AES-256-GCM -> wrap AES key for patient -> upload encrypted file -> save metadata -> anchor hash

Permission Grant

Doctor requests access -> patient reviews scope and duration -> patient approves records -> grant is stored -> grant is anchored through Soroban

Record Access

Doctor opens record -> backend checks active grant -> encrypted file is retrieved -> access event is logged -> audit proof is anchored

Emergency Access

Emergency requested -> multi-party approval required -> time-limited emergency grant created -> all access events marked for review

Security Model

Security is critical because DMRX handles medical data. Required controls include end-to-end encryption, zero-trust service boundaries, role-based access control, patient-controlled grants, time-limited permissions, revocation support, hardware key support, secure key recovery, audit logging, multi-signature emergency access, least-privilege credentials, and no clinical content in public chain data.

Encryption Flow

Record created
  -> generate AES data key
  -> encrypt file with AES-256-GCM
  -> hash original plaintext
  -> wrap AES key for patient public key
  -> upload encrypted file
  -> store encrypted URI and key reference
  -> anchor hash and metadata proof

Tamper Detection

Decrypt file -> calculate SHA-256 hash -> compare with anchored hash -> flag mismatch if hashes differ

This supports fraud detection, insurance disputes, medico-legal evidence, and record authenticity checks.

Data Model

Model	Purpose
Actor	patient, doctor, hospital, or regulator identity
MedicalRecord	encrypted record metadata and chain references
PermissionGrant	scoped patient-approved access
AuditEvent	record access and permission events

Environment Variables

Copy .env.example to .env and fill in local values.

cp .env.example .env

Important variables:

• DATABASE_URL
• REDIS_URL
• STORAGE_PROVIDER
• S3_ENDPOINT
• S3_BUCKET
• STELLAR_NETWORK
• STELLAR_HORIZON_URL
• SOROBAN_RPC_URL
• IDENTITY_CONTRACT_ID
• ACCESS_CONTROL_CONTRACT_ID
• AUDIT_LOG_CONTRACT_ID
• JWT_SECRET
• DID_METHOD

Never commit real secrets.

Local Development

Prerequisites:

• Node.js 20+
• pnpm 9+
• Rust stable
• Soroban CLI
• Docker Desktop or local PostgreSQL

Install dependencies:

pnpm install

Generate Prisma client:

pnpm db:generate

Run all workspace dev tasks:

pnpm dev

Run a single frontend app:

pnpm --filter @dmrx/patient-portal dev
pnpm --filter @dmrx/hospital-dashboard dev
pnpm --filter @dmrx/doctor-dashboard dev

Run a single backend service:

pnpm --filter @dmrx/auth-service dev
pnpm --filter @dmrx/records-service dev
pnpm --filter @dmrx/permissions-service dev
pnpm --filter @dmrx/audit-service dev

Build contracts:

pnpm contracts:build

Useful Commands

Command	Description
pnpm install	Install dependencies
pnpm dev	Run development tasks
pnpm build	Build workspace
pnpm lint	Run lint/type checks
pnpm typecheck	Type-check workspace
pnpm test	Run test scripts
pnpm format	Format supported files
pnpm db:generate	Generate Prisma client
pnpm db:migrate	Run Prisma migrations
pnpm contracts:build	Build Soroban contracts

Testing Direction

DMRX should include frontend workflow tests, backend unit and integration tests, contract tests for identity and permissions, security tests for encryption and access control, and end-to-end tests for patient grant and doctor access flows.

MVP Roadmap

Phase	Goals
Phase 1	patient registration, hospital upload, record hashing, encrypted storage, basic permission sharing
Phase 2	doctor dashboard, audit logs, QR sharing, revocation UX
Phase 3	emergency access, insurance verification, regulator dashboard, mobile responsiveness
Phase 4	AI summaries, medication checks, offline rural sync, interoperability, national identity linkage

Future Extensions

• AI assistant layer for summaries and clinical checks.
• HMO and insurance verification workflows.
• Offline-first rural clinic sync.
• Government institution registry.
• Mobile app.
• Multi-country interoperability.

Compliance Notes

DMRX is a technical scaffold, not a compliance-certified medical product. Before real-world use, teams must review applicable health data laws, security requirements, data residency rules, clinical governance, and operational controls.

Do not use this scaffold with real patient data until security, legal, operational, and clinical reviews are complete.

Contributing

Good first contribution areas include docs, Docker infrastructure, contract tests, Stellar client calls, Prisma migrations, storage adapters, frontend forms, API wiring, and CI checks.

License

This project is licensed under the MIT License. See LICENSE.