System Architecture
Complete overview of MediPact's multi-layer architecture and component interactions.
Architecture Overview
Components
| Component | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 15, TypeScript, Tailwind CSS | Patient/Hospital/Researcher/Admin portals |
| Backend | Express.js, Node.js, SQLite/PostgreSQL | REST API, patient identity (UPI), marketplace |
| Adapter | Node.js, FHIR R4 | Processes EHR data, anonymizes PII, submits to HCS |
| Smart Contracts | Solidity (Hedera EVM) | ConsentManager & RevenueSplitter |
Frontend Layer
Next.js 15 Application
Built with Next.js 15 App Router, TypeScript, and Tailwind CSS. Provides role-based dashboards for:
- Patients: Dashboard, earnings, wallet, consent management
- Hospitals: Patient registration, data upload, revenue tracking
- Researchers: Dataset catalog, purchases, analytics
- Admins: System management, verification, analytics
Backend Layer
Express.js REST API
RESTful API providing endpoints for:
- User authentication and authorization
- Patient identity management (UPI system)
- Dataset creation and querying
- Revenue distribution
- Hedera account management
- Payment verification
- Wallet balance queries
- Withdrawal processing
- Exchange rate management
Database
SQLite for development, PostgreSQL for production. Stores:
- Patient records with UPI (Universal Patient Identifier)
- Hospital and researcher profiles
- Consent records and verification status
- Dataset metadata and query results
- Hedera account IDs and encrypted keys
- Payment methods and withdrawal settings
- Withdrawal history and transaction logs
- Exchange rate cache
Processing Layer
Adapter Service
The adapter is responsible for processing raw EHR data:
- FHIR R4 Parsing: Validates and parses FHIR-compliant medical records
- PII Anonymization: Removes personally identifiable information
- Demographic Preservation: Maintains research-valuable demographics (age range, country, gender)
- K-Anonymity Enforcement: Ensures minimum 5 records per demographic group
- HCS Submission: Submits consent and data proof hashes to Hedera Consensus Service
- Smart Contract Integration: Records consent on ConsentManager contract
Hedera Network Integration
HCS Topics
Immutable storage for consent proofs and data hashes. Each message is cryptographically signed and timestamped.
EVM Contracts
ConsentManager for consent registry and RevenueSplitter for automated revenue distribution.
Hedera Accounts
Native accounts (0.0.xxxxx) for all users, created during registration for hospitals, researchers, and patients.
HBAR
Native cryptocurrency for micropayments and revenue distribution with low transaction fees.
Security Architecture
Key Security Features
- Encrypted Private Keys: All Hedera private keys are encrypted before storage
- Role-Based Access Control: API endpoints protected by role-based authentication
- PII Anonymization: No personally identifiable information stored on-chain
- Consent Validation: Database and smart contract level enforcement
- Immutable Audit Trail: All consent and data proofs stored on HCS
- K-Anonymity: Privacy protection through demographic grouping
- Payment Data Encryption: Bank accounts and mobile money numbers encrypted at rest
- Production Logging: Structured JSON logs with security event tracking
- Environment Validation: Startup validation of required configuration
- Security Headers: Production security headers (HSTS, XSS protection, etc.)