A comprehensive full-stack medical platform built with modern web technologies and decentralized identity solutions, designed for production healthcare environments with stringent security, reliability, and compliance requirements.
┌─────────────────────────────────────────────────────────────────────────────┐
│ FRONTEND LAYER │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Svelte 5 │ │ Tailwind CSS │ │ PWA Support │ │
│ │ SPA │◄──►│ Responsive │◄──►│ Offline First │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└────────────────────────────────┬────────────────────────────────────────────┘
│ HTTPS/TLS 1.3
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ API GATEWAY LAYER │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Rate Limiting • Circuit Breaking • Request Validation • Logging │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────┬────────────────────────────────────────────┘
│ Internal API Calls
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ BACKEND SERVICES LAYER │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Fastify API │ │ Auth Service │ │ AI Service │ │
│ │ Routes │◄──►│ DID/Ceramic │◄──►│ BioGPT/Mistral│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Video Call Mgmt │ │ Data Encryption │ │ NotificationSvc │ │
│ │ Agora SDK │◄──►│ AES-256/GCM │◄──►│ WebPush/Firebase│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└────────────────────────────────┬────────────────────────────────────────────┘
│ Database Queries • External API Calls
┌─────────────────▼─────────────────┐
│ DATA & STORAGE LAYER │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ PostgreSQL │ │ MongoDB │ │
│ │ Health Data │ │ Prototyping │ │
│ └─────────────┘ └─────────────┘ │
│ ┌───────────────────────────────┐ │
│ │ IPFS + Ceramic IDX │ │
│ │ Decentralized Medical Records │ │
│ └───────────────────────────────┘ │
└─────────────────┬─────────────────┘
│ External Integrations
┌─────────────────▼─────────────────┐
│ EXTERNAL SERVICES │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Agora.io │ │ HuggingFace │ │
│ │ Video/Audio │ │ AI Models │ │
│ └─────────────┘ └─────────────┘ │
│ ┌───────────────────────────────┐ │
│ │ Email/SMS Gateways │ │
│ │ Twilio, SendGrid, etc. │ │
│ └───────────────────────────────┘ │
└───────────────────────────────────┘
- Zero Trust Security: Every component validates every request
- Data Sovereignty: Patients own and control their medical data
- Regulatory Compliance: Built-in HIPAA, GDPR, and medical device compliance
- High Availability: Multi-region deployment with automatic failover
- Scalable by Design: Horizontal scaling for patient load spikes
- Audit Trail: Immutable logging of all medical data access
Critical Assets: Patient medical records, authentication credentials, video consultation data, AI consultation history
Threat Vectors:
- Data Breach: Unauthorized access to medical records
- Identity Spoofing: Impersonation of patients or doctors
- Man-in-the-Middle: Interception of video consultations
- AI Model Poisoning: Compromised medical AI recommendations
- Denial of Service: Disruption of critical healthcare services
- Regulatory Non-compliance: HIPAA/GDPR violations
- Decentralized Identity: Ceramic DID eliminates centralized credential storage
- Multi-Factor Authentication: Required for doctor accounts and sensitive operations
- Role-Based Access Control: Granular permissions for patients, doctors, admins
- Session Management: Short-lived JWT tokens with automatic rotation
- Certificate Verification: Cryptographic verification of doctor credentials
- Encryption at Rest: AES-256 encryption for all database fields containing PHI
- Encryption in Transit: TLS 1.3 with perfect forward secrecy
- End-to-End Encryption: Video consultations encrypted client-to-client
- Data Minimization: Only collect necessary medical information
- Anonymization: Strip PII from AI training data
- API Gateway: Centralized security enforcement point
- Rate Limiting: Prevent brute force attacks on authentication endpoints
- Input Validation: Comprehensive sanitization of all user inputs
- Content Security Policy: Prevent XSS attacks in web interface
- Secure Headers: HTTP security headers enforced by middleware
- HIPAA Compliance: Business Associate Agreement (BAA) ready architecture
- GDPR Compliance: Right to erasure, data portability, consent management
- Audit Logging: Immutable logs of all data access and modifications
- Data Residency: Configurable data storage regions for regulatory compliance
- Security Monitoring: Real-time threat detection and alerting
- PostgreSQL High Availability: Streaming replication with automatic failover
- MongoDB Replica Sets: Automatic primary election during node failures
- Circuit Breakers: Prevent cascading failures during database outages
- Graceful Degradation: Continue serving cached data during partial outages
- Backup Strategy: Point-in-time recovery with encrypted backups
- Agora.io Outage: Fallback to text-based consultations with notification
- HuggingFace Unavailable: Cache recent AI responses, queue new requests
- IPFS/Ceramic Downtime: Local caching with eventual consistency
- Email/SMS Gateway Failure: Retry with exponential backoff, multiple providers
- Eventual Consistency: CRDTs for distributed medical record updates
- Conflict Resolution: Timestamp-based conflict resolution with manual review
- Offline Mode: PWA supports offline consultation notes with sync on reconnect
- Health Checks: Comprehensive service health monitoring with automatic recovery
- Multi-Region Deployment: Active-active deployment across regions
- RTO/RPO Targets: 15-minute RTO, 5-minute RPO for critical services
- Chaos Engineering: Regular failure injection testing
- Incident Response: Automated rollback and manual intervention procedures
- Business Continuity: Manual override procedures for critical medical functions
- Patient Experience: Consultation success rate, video quality score, response time
- System Health: API error rates, database query performance, external service latency
- Security: Failed login attempts, suspicious activity detection, compliance violations
- Business: Active patients, completed consultations, AI usage patterns
- Critical Alerts: Page on-call engineer (video consultation failures, data breaches)
- Warning Alerts: Slack notification (performance degradation, high error rates)
- Info Alerts: Daily digest (usage statistics, system health summary)
- Structured Logging: JSON format with correlation IDs
- PII Handling: Automatic redaction of sensitive medical information
- Retention Policy: 7 years for audit logs (HIPAA requirement)
- Log Aggregation: Centralized logging with Elasticsearch/Kibana
- Video Consultation Failure: Verify Agora credentials, check network connectivity
- AI Service Unavailable: Switch to cached responses, notify users of delay
- Database Performance Issues: Scale read replicas, optimize slow queries
- Security Incident: Isolate affected components, preserve evidence, notify authorities
- Root Cause Analysis: 5 Whys methodology for all incidents
- Action Items: Track remediation tasks to completion
- Knowledge Sharing: Document lessons learned in internal wiki
- Process Improvement: Update runbooks based on incident learnings
- CPU Utilization: >70% average over 5 minutes triggers scale-out
- Memory Usage: >80% triggers memory optimization or scale-out
- Request Queue: >100 requests queued triggers additional instances
- Database Connections: >80% of max connections triggers connection pooling optimization
- API Response Time: <200ms p95 for all endpoints
- Video Consultation Setup: <3 seconds end-to-end
- AI Response Time: <5 seconds for medical consultation responses
- Database Query Performance: <50ms for critical queries
- API Gateway: Auto-scaling based on request volume
- Authentication Service: Stateless JWT validation enables unlimited scaling
- Notification Service: Queue-based processing with worker scaling
- Database Sharding: Patient ID-based sharding for horizontal database scaling
- Session Management: Redis cluster for distributed session storage
- File Storage: IPFS content addressing enables unlimited storage scaling
- Browser Cache: Static assets with long TTL, service worker for PWA
- CDN Cache: API responses for public endpoints
- Application Cache: Redis for frequently accessed medical records
- Database Cache: PostgreSQL shared buffers and query plan caching
- Time-based: TTL-based expiration for non-critical data
- Event-driven: Real-time invalidation on data updates
- Manual: Administrative cache clearing for emergency situations
- Single Instance: 100 concurrent video consultations, 500 API requests/second
- Scaled Deployment: 1000+ concurrent consultations, 5000+ API requests/second
- Database Performance: 10,000+ patient records with sub-second query response
- Primary Bottleneck: Video bandwidth for high-definition consultations
- Secondary Bottleneck: AI model inference latency during peak usage
- Mitigation Strategy: Adaptive video quality, AI request queuing
- FHIR Server: RESTful API compliant with FHIR R4 specification
- Resource Mapping: Automatic mapping between internal data model and FHIR resources
- Subscription API: Real-time notifications for medical record changes
- Bulk Data Export: Patient data export in FHIR Bundle format
- Epic Integration: SMART on FHIR app framework support
- Cerner Integration: Open bedrock API compatibility
- Custom EHR Connectors: Extensible connector framework for proprietary systems
- Data Synchronization: Bidirectional sync with external EHR systems
- Stripe Integration: Secure payment processing for consultation fees
- Insurance Verification: Real-time insurance eligibility checking
- Billing Automation: Automated invoice generation and payment reminders
- Apple HealthKit: Secure integration with Apple Health data
- Google Fit: Android wearable data integration
- Fitbit API: Fitness tracker data import
- Medical Device APIs: Integration with glucose monitors, blood pressure devices
- SMS Integration: Appointment reminders and consultation notifications
- Email Integration: Secure medical communication with encryption
- Push Notifications: Real-time mobile app notifications
- Calendar Integration: Automatic appointment scheduling with Google Calendar/Outlook
- URL Versioning:
/api/v1/consultationsfor stable contracts - Header Versioning:
Accept: application/vnd.medical.v2+jsonfor content negotiation - Deprecation Policy: 6-month deprecation window with migration guides
- Standard Error Format: Consistent error responses across all endpoints
- HTTP Status Codes: Proper use of 4xx/5xx status codes
- Error Categories: Validation, authentication, authorization, business logic errors
- Retry Guidance: Retry-after headers for transient failures
- Local Docker: Full stack running locally with mock external services
- Feature Branches: Isolated deployments for each feature branch
- Automated Testing: CI pipeline with unit, integration, and E2E tests
- Production Clone: Identical to production with synthetic test data
- Performance Testing: Load testing before production deployment
- Security Scanning: Automated vulnerability scanning and penetration testing
- Blue/Green Deployment: Zero-downtime deployments with automated rollback
- Canary Releases: Gradual rollout to subset of users before full deployment
- Feature Flags: Runtime toggling of new features without redeployment
- VPC Module: Secure network isolation with private subnets
- Database Module: Encrypted PostgreSQL with automated backups
- Kubernetes Module: EKS cluster with auto-scaling node groups
- Monitoring Module: CloudWatch/Prometheus/Grafana stack
- GitHub Actions: Automated build, test, and deployment pipeline
- Security Gates: SAST, DAST, and dependency scanning in pipeline
- Compliance Checks: Automated HIPAA/GDPR compliance validation
- Rollback Automation: Automatic rollback on failed health checks
Decision: Use Ceramic DID for patient authentication Rationale: Eliminates centralized credential storage, provides true data sovereignty, enables cross-platform identity portability Trade-offs: Increased complexity, limited user familiarity, dependency on Ceramic network availability
Decision: PostgreSQL as primary, MongoDB as optional prototyping alternative Rationale: PostgreSQL provides ACID transactions, complex queries, and mature tooling required for medical data integrity Trade-offs: Less flexible schema than MongoDB, higher operational complexity
Decision: Agora SDK for production, WebRTC fallback for cost-sensitive deployments Rationale: Agora provides superior quality, global infrastructure, and medical-grade reliability Trade-offs: Vendor lock-in, ongoing subscription costs, dependency on third-party service
Decision: Separate repositories for frontend and backend Rationale: Enables independent scaling, separate deployment cycles, and focused team ownership Trade-offs: Increased coordination overhead, potential version compatibility issues
- Business Associate Agreement (BAA) with all third-party vendors
- Encryption of ePHI at rest and in transit
- Access controls and audit logging
- Risk analysis and security incident procedures
- Workforce training and security awareness
- Contingency planning and disaster recovery
- Lawful basis for processing (explicit consent)
- Data subject rights (access, rectification, erasure, portability)
- Data protection by design and default
- Data processing agreements with subprocessors
- Data breach notification procedures
- Data protection impact assessments
- FDA SaMD (Software as a Medical Device) classification assessment
- IEC 62304 software lifecycle compliance
- ISO 13485 quality management system
- Clinical validation and verification procedures
- Post-market surveillance and reporting
- Code Splitting: Route-based code splitting for faster initial load
- Image Optimization: WebP format with lazy loading for medical images
- Bundle Analysis: Regular bundle size monitoring and optimization
- Performance Budgets: Enforced limits on page weight and load time
- Query Optimization: Index optimization, query plan analysis, connection pooling
- Caching Strategy: Multi-level caching with intelligent invalidation
- Async Processing: Background job processing for non-critical operations
- Resource Monitoring: Real-time CPU, memory, and I/O monitoring
- Index Strategy: Composite indexes for common query patterns
- Partitioning: Time-based partitioning for consultation history
- Connection Pooling: Optimized connection pool sizing
- Read Replicas: Offload read queries to replica instances
- Unit Tests: 70% coverage of business logic and utility functions
- Integration Tests: 20% coverage of service interactions and API contracts
- End-to-End Tests: 10% coverage of critical user journeys
- Contract Tests: API contract validation between services
- Security Testing: Penetration testing, vulnerability scanning, fuzz testing
- Performance Testing: Load testing, stress testing, spike testing
- Usability Testing: User experience testing with real healthcare professionals
- Compliance Testing: Automated HIPAA/GDPR compliance validation
- Synthetic Data Generation: Realistic medical data without real patient information
- Data Masking: Automatic PII masking in non-production environments
- Test Data Refresh: Regular refresh of test data to maintain realism
- Data Anonymization: Irreversible anonymization for external testing
- Multi-Model Orchestration: Dynamic selection of best AI model for each medical specialty
- Fine-tuned Models: Domain-specific fine-tuning for cardiology, neurology, etc.
- Explainable AI: Transparent reasoning for AI medical recommendations
- Continuous Learning: Feedback loop for AI model improvement
- AR/VR Consultations: Immersive consultation experiences for complex cases
- Remote Patient Monitoring: Real-time vital sign monitoring integration
- Collaborative Consultations: Multi-doctor consultation rooms
- Language Translation: Real-time multilingual consultation support
- International EHR Standards: Support for international medical data standards
- Cross-Border Data Sharing: Secure international patient data exchange
- Regional Compliance: Local regulatory compliance for major markets
- Multi-Currency Support: Global payment processing capabilities
- Risk Stratification: AI-powered patient risk assessment
- Preventive Care Recommendations: Proactive health intervention suggestions
- Population Health Management: Analytics for healthcare provider organizations
- Clinical Trial Matching: Automated matching of patients to relevant trials
- Frontend: Svelte 5 + Tailwind CSS
- Backend: Fastify + TypeScript
- Identity: Ceramic DID (Decentralized Identity)
- Storage: IPFS + Ceramic IDX
- Video Calls: Agora SDK
- AI Models: HuggingFace (BioGPT, Mistral-med)
- Database: PostgreSQL
- Deployment: Vercel (Frontend) + Railway (Backend)
Med/
├── frontend/ # Svelte 5 + Tailwind CSS
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ ├── routes/ # Page routes
│ │ ├── lib/ # Utilities and stores
│ │ └── app.html # Main HTML template
│ ├── static/ # Static assets
│ └── package.json
├── backend/ # Fastify API server
│ ├── src/
│ │ ├── routes/ # API endpoints
│ │ ├── services/ # Business logic
│ │ ├── models/ # Database models
│ │ ├── middleware/ # Auth & validation
│ │ └── utils/ # Helper functions
│ └── package.json
├── docker-compose.yml # Container orchestration
└── README.md # This file
- Node.js 18+
- Docker & Docker Compose
- Git
-
Clone the repository
git clone <repository-url> cd Med
-
Copy environment templates
# Frontend cp frontend/.env.example frontend/.env # Backend cp backend/.env.example backend/.env
-
Configure environment variables
Frontend (.env):
VITE_API_URL=http://localhost:3001 VITE_CERAMIC_API_URL=https://ceramic-clay.3boxlabs.com VITE_AGORA_APP_ID=your_agora_app_id
Backend (.env):
PORT=3001 DATABASE_URL=postgresql://username:password@localhost:5432/medplatform JWT_SECRET=your-super-secret-jwt-key # Ceramic Configuration CERAMIC_API_URL=https://ceramic-clay.3boxlabs.com CERAMIC_SEED=your-ceramic-seed # Agora Configuration AGORA_APP_ID=your_agora_app_id AGORA_APP_CERTIFICATE=your_agora_app_certificate # HuggingFace Configuration HUGGINGFACE_API_KEY=your_huggingface_api_key # IPFS Configuration IPFS_API_URL=https://ipfs.infura.io:5001 IPFS_API_KEY=your_ipfs_api_key IPFS_API_SECRET=your_ipfs_api_secret
# Start all services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose downAccess the application:
- Frontend: http://localhost:5173
- Backend API: http://localhost:3001
- Database: localhost:5432
-
Start the backend
cd backend npm install npm run dev -
Start the frontend
cd frontend npm install npm run dev -
Setup PostgreSQL database
# Using Docker docker run --name medplatform-db -e POSTGRES_PASSWORD=password -e POSTGRES_DB=medplatform -p 5432:5432 -d postgres:15 # Run migrations cd backend npm run migrate
- Decentralized Identity: Ceramic DID-based authentication
- Self-Sovereign Identity: Users control their own data
- Role-based Access: Patient and Doctor roles
- Credential Upload: PDF/image certificate upload
- IPFS Storage: Decentralized document storage
- Verifiable Credentials: Ceramic-based credential issuance
- Verification Status: Visual verification badges
- Multiple AI Models: Support for BioGPT, Mistral-med
- Chat Interface: Real-time conversation UI
- Medical Disclaimers: Appropriate warning messages
- Consultation History: Persistent chat records
- Real-time Video/Audio: Agora SDK integration
- 1:1 Consultations: Patient-doctor video calls
- Call Controls: Mute, video toggle, screen share
- Connection Management: Robust connection handling
- Encrypted Storage: Sensitive data encryption
- Decentralized Records: Health data on Ceramic + IPFS
- GDPR Compliant: User data control and deletion
- Audit Trails: Comprehensive logging
- Health Reminders: Medication and appointment reminders
- Notification System: Real-time updates
- Responsive Design: Mobile-first approach
- Progressive Web App: PWA capabilities
cd frontend
# Install dependencies
npm install
# Start development server
npm run dev
# Build for production
npm run build
# Preview production build
npm run preview
# Run tests
npm run test
# Lint code
npm run lintcd backend
# Install dependencies
npm install
# Start development server
npm run dev
# Build TypeScript
npm run build
# Start production server
npm start
# Run database migrations
npm run migrate
# Run tests
npm run test
# Lint code
npm run lintThe default relational store is PostgreSQL (Knex). A lightweight MongoDB mode is available for rapid prototyping or when you prefer a document model.
- Install and start MongoDB locally (default port 27017) or use a cloud URI.
- In
backend/.envset:DB_CLIENT=mongo MONGO_URL=mongodb://localhost:27017 MONGO_DB=medplatform
- Remove/ignore
DATABASE_URL(it will be unused in mongo mode). - Start the backend:
npm run dev.
The Fastify instance exposes:
fastify.mongo.db // native Db instance
fastify.mongo.getCollection // helper to grab a collection
fastify.db(collectionName) // thin adapter for code paths expecting fastify.dbLimitations (current prototype):
- Knex migrations do NOT run in Mongo mode.
- Existing services that join across tables may need refactors to use aggregation pipelines.
- Some routes still expect SQL schema (e.g., joins in consultations/video). Use Postgres for full functionality until a dual abstraction layer is implemented.
Planned enhancements:
- Abstract repository layer (UserRepository, ConsultationRepository) with dual drivers.
- Automated Mongo index creation on startup.
- Data shape parity tests between Postgres and Mongo backends.
# Run migrations
npm run migrate
# Rollback migration
npm run migrate:rollback
# Reset database
npm run migrate:reset
# Seed database
npm run seed-
Connect repository to Vercel
-
Configure build settings:
- Build Command:
npm run build - Output Directory:
dist - Install Command:
npm install
- Build Command:
-
Set environment variables in Vercel dashboard
-
Connect repository to Railway
-
Configure build settings:
- Build Command:
npm run build - Start Command:
npm start
- Build Command:
-
Add PostgreSQL service
-
Set environment variables in Railway dashboard
# Build images
docker-compose build
# Deploy to production
docker-compose -f docker-compose.prod.yml up -d- All sensitive data is encrypted at rest
- DID-based authentication eliminates password risks
- IPFS ensures data immutability
- Regular security audits recommended
- Rate limiting on all API endpoints
- Input validation and sanitization
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-feature - Commit changes:
git commit -am 'Add new feature' - Push to branch:
git push origin feature/new-feature - Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
For support and questions:
- Create an issue in this repository
- Check the documentation
- Contact the development team
- Integration with more AI medical models
- Dual database abstraction (Postgres + Mongo parity layer)
- Mobile app development (React Native)
- Telemedicine appointment scheduling
- Integration with wearable devices
- Multi-language support
- Advanced analytics dashboard