How to Architect a Patient-Centric Health Data Wallet

A patient-centric health data wallet is a self-sovereign identity (SSI) application that gives individuals control over their medical records, test results, and wellness data. Unlike traditional electronic health records (EHRs) siloed within provider networks, this architecture uses decentralized identifiers (DIDs) and verifiable credentials (VCs) to create a portable, user-owned data layer. The core components are a secure local or cloud-based wallet (the holder), issuers like hospitals or labs, and verifiers such as insurance companies or new care providers. This model shifts the paradigm from institutional data hoarding to patient-mediated data sharing, enabling interoperability across disparate health systems.

The technical foundation relies on W3C Verifiable Credentials data model and DID methods like did:ethr or did:key. A user's wallet generates a DID, which serves as their cryptographic identifier. When a healthcare provider issues a credential—for example, a COVID-19 vaccination record—they sign a JSON-LD document containing the claim with their private key, binding it to the patient's DID. The patient stores this signed VC in their wallet. To share this data, they do not send the raw credential; instead, they generate a verifiable presentation, which can use zero-knowledge proofs (ZKPs) to selectively disclose only necessary attributes (e.g., "over 18" without revealing birthdate).

For persistent, immutable record-keeping and to establish trust in issuers, the architecture integrates with blockchain networks. Ethereum Attestation Service (EAS) or Verax are protocols for making on-chain attestations about DIDs. A hospital's DID can be registered on-chain as a trusted issuer for specific credential schemas. When they issue a VC, they can also create an on-chain attestation that serves as a public, tamper-proof proof of issuance. This allows any verifier to cryptographically check the credential's provenance against the blockchain without accessing the personal health data itself, which remains off-chain in the user's wallet or on decentralized storage like IPFS or Ceramic.

A patient-centric health data wallet is a self-sovereign identity (SSI) application that gives individuals ownership and granular control over their medical records. Unlike centralized health databases, this architecture uses decentralized identifiers (DIDs) and verifiable credentials (VCs) to create a portable, interoperable, and privacy-preserving system. The core prerequisites include understanding key Web3 primitives: blockchain for anchoring trust, cryptographic key management for user sovereignty, and standardized data formats like W3C's Verifiable Credentials Data Model for interoperability across healthcare providers.

The technical stack begins with a blockchain layer for decentralized trust. While public chains like Ethereum offer strong security, their public nature can conflict with healthcare privacy laws like HIPAA. Permissioned chains (e.g., Hyperledger Fabric) or zero-knowledge rollups (e.g., zkSync) are often better suited, providing auditability while keeping sensitive data off-chain. This layer's primary role is to manage DIDs—cryptographic identities—and record the issuance and revocation status of credentials without storing the health data itself, which remains under the patient's control.

Data storage and access control are critical. The actual health records—lab results, imaging reports, prescriptions—should be stored off-chain in encrypted form. Solutions include decentralized storage networks like IPFS or Arweave for persistence, or encrypted cloud storage. Access is governed by smart contracts or access control lists that execute patient consent. For example, a user could grant a specialist temporary, read-only access to a specific record via a signed cryptographic permission, revocable at any time. This ensures data minimization and purpose-bound usage.

For the user interface, a mobile or web wallet application acts as the user's agent. It must securely manage the user's private keys (often via secure enclaves or hardware modules), present and store verifiable credentials, and facilitate data-sharing interactions. Frameworks like React Native or Flutter are common for cross-platform development. The wallet must integrate with healthcare providers' systems using standard APIs, such as FHIR (Fast Healthcare Interoperability Resources), to request and receive credentials in a structured, machine-readable format that can be cryptographically signed and verified.

The foundation of a patient-centric architecture is decentralized identity. Instead of accounts on a central server, users control a Decentralized Identifier (DID) anchored on a blockchain, like Ethereum or a purpose-built ledger such as Sovrin. This DID, managed via a private key in the user's wallet, serves as their global, persistent identifier. Associated with this DID are Verifiable Credentials (VCs), which are tamper-evident digital claims issued by trusted entities like hospitals or labs. A lab result, vaccination record, or insurance membership becomes a cryptographically signed VC that the patient can store and share.

The system's data flow follows a holder-issuer-verifier model. The patient is the holder. An institution, acting as the issuer, signs and issues a VC to the holder's wallet. When access is needed—for example, at a new clinic—the patient (holder) presents the VC to the service (verifier). The verifier checks the credential's cryptographic signature against the issuer's public DID on the blockchain to confirm its authenticity and validity without contacting the issuer directly. This model enables selective disclosure, where a user can prove they are over 18 from a driver's license VC without revealing their exact birth date or address.

For storing and exchanging sensitive data, the architecture must separate metadata from personal health information (PHI). The DID and VC metadata (issuer, schema, issuance date) are written to the blockchain for verification. The actual PHI payload (e.g., MRI images, detailed diagnosis) should never be stored on-chain. Instead, it is encrypted by the user's key and stored in a personal encrypted data vault, which could be a cloud storage service (like IPFS or AWS S3) or a local device. The VC contains only a secure pointer (a URI) and a hash of this encrypted data, allowing the user to grant time-limited, auditable access tokens to specific parties.

Interoperability is critical. The architecture should adopt established W3C Verifiable Credentials data models and DID Core specifications. For healthcare-specific data, integrate with existing standards like FHIR (Fast Healthcare Interoperability Resources). A credential schema registry defines the structure for different VC types (e.g., BloodTestV1), ensuring all parties understand the data. Furthermore, the user interface must include a consent manager, a clear dashboard where users can see all access requests, grant or revoke permissions, and view an audit log of who accessed which data and when.

A robust backend requires several key services. An issuer API allows healthcare providers to create and sign VCs. A verifier service handles the logic for validating presented credentials. A credential wallet SDK (often a React Native or Flutter library) provides the core cryptographic functions—key management, credential storage, and secure presentation—for the mobile or web app. For higher security, consider integrating hardware security modules (HSMs) for institutional key management and using zero-knowledge proof circuits (e.g., with Circom) to enable privacy-preserving proofs from the user's data without revealing the underlying information.

A patient-centric health data wallet is a digital application that allows individuals to aggregate, manage, and share their medical records from multiple sources. Unlike traditional EHR portals controlled by providers, the wallet is owned by the patient. The core architectural challenge is securely ingesting data from disparate hospital and clinic systems. The FHIR (Fast Healthcare Interoperability Resources) API has become the de facto standard for this, providing a RESTful interface to access structured clinical data like Patient, Observation, and Condition resources. Architecting around FHIR ensures interoperability across thousands of healthcare systems.

The foundation of your architecture is the FHIR API client. You must first register your application with each EHR system's authorization server, typically following the SMART on FHIR OAuth 2.0 framework. A robust client will handle authentication flows, token management, and rate limiting. For data retrieval, you'll call endpoints like GET [base]/Patient/[id] and GET [base]/Observation?patient=[id]. It's critical to implement incremental synchronization using FHIR's _since parameter to fetch only new or updated records, minimizing API load and ensuring data freshness in the wallet.

Once data is retrieved, you face the data normalization problem. Different EHRs may use varying code systems (e.g., LOINC vs. SNOMED CT) for the same lab result. Your backend must include a normalization layer to map these codes to a consistent internal schema. Furthermore, sensitive data requires end-to-end encryption before storage. A best practice is to encrypt data with a key derived from the user's own passphrase or hardware key, ensuring only the patient can decrypt it, even if your database is compromised. This aligns with the zero-knowledge storage principle.

The user interface must provide clear consent management. When a user wants to share records with a new clinic or researcher, the wallet should generate a granular, auditable consent receipt. Technically, this can be implemented using OAuth 2.0 scopes (e.g., patient/Observation.rs) or UMA (User-Managed Access) protocols. The shareable data package itself is often a FHIR Bundle resource. For a developer, implementing a verifiable credential layer on top of this, using standards like W3C Verifiable Credentials, can provide cryptographic proof of the data's origin and integrity, enabling trustless sharing.

Finally, consider the off-chain/on-chain hybrid model common in Web3. The bulk of medical data should remain in secure, performant off-chain storage (like IPFS or a private cloud), with only cryptographic hashes (e.g., SHA-256) and access permissions written to a blockchain. This creates an immutable audit trail of data provenance and consent events without storing sensitive data on a public ledger. A smart contract can act as a permissions registry, allowing users to grant and revoke data access programmatically. This architecture combines FHIR's interoperability with blockchain's trust and patient agency.

You now have a blueprint for a patient-centric health data wallet built on core Web3 primitives. The architecture leverages self-custodial wallets for identity, decentralized storage (like IPFS or Arweave) for data, and smart contracts on a privacy-focused chain (such as Polygon or a zk-rollup) for access control. The key is ensuring the patient's private key is the sole key to their encrypted data vault, with granular, revocable permissions granted via verifiable credentials or token-gating.

For implementation, start with a robust frontend using a framework like React or Next.js, integrated with wallet connection via WalletConnect or a similar protocol. Use libraries like ethers.js or viem to interact with your access control smart contracts. For handling medical data formats, consider adopting the FHIR (Fast Healthcare Interoperability Resources) standard for structuring records before encryption and storage, which facilitates future interoperability with traditional healthcare systems.

To move beyond a prototype, focus on these next steps: 1) Conduct a formal security audit of your smart contracts and key management flow. 2) Implement zero-knowledge proofs (ZKPs) using a SDK like Circuits or a service like Sindri to allow data verification without exposure (e.g., proving you are over 18 without revealing your birthdate). 3) Explore integration with DePIN networks like Helium for IoT health device data or oracle networks like Chainlink to bring verified off-chain medical events on-chain.

The long-term vision involves your wallet becoming a universal health identity. This requires building bridges to legacy Electronic Health Record (EHR) systems via approved APIs and participating in emerging health data marketplaces that allow patients to monetize anonymized datasets for research. Success depends on relentless focus on user experience, transparent data governance, and adherence to regulations like HIPAA through technological enforcement, not just policy.