MedSovereign AI 🛡️

The Patient-Controlled Clinical Intelligence Network

MedSovereign flips the traditional healthcare data model upside down. Instead of scattered silos, patients hold a cryptographic Health Vault, and AI-driven clinical safety guarantees zero-trust interactions.

---

🚀 The Vision

Modern healthcare data is fragmented, siloed, and vulnerable. MedSovereign introduces a Cryptographic Health Vault architecture where the patient acts as the sovereign owner of their medical data. Doctors, hospitals, and pharmacies must request mathematically-enforced access to this data.

Every action is recorded on a tamper-evident Audit Timeline. Before a prescription is finalized, an AI Clinical Safety Agent cross-references the proposed drug against the patient's encrypted vault history to flag contraindications, while a network-level Fraud Radar monitors for systemic abuse.

---

💎 What Makes Us Unique?

• Inverted Data Ownership: The patient is the host, and institutions are the guests. Your health data lives in one central, encrypted vault, not scattered across a dozen hospital databases.
• Zero-Trust by Default: Providers don't get unlimited access to your records. They get cryptographically gated, time-bound consent artifacts that expire.
• AI as a Deterministic Safety Agent: We don't use AI as a chatbot. Our Explainable AI acts as a "safety agent in the loop," deterministically cross-referencing new prescriptions against complex medical histories to prevent deadly drug interactions.
• Verifiable Audit Trail: Every single read, write, and consent approval is hashed and chained. The patient's clinical timeline is mathematically tamper-evident.
• Break-Glass Emergency Protocol: What if you're unconscious? A provider can trigger an emergency override, which instantly alerts your pre-configured Guardians and logs a high-alert audit event.

---

🏗️ High-Level Architecture

Our platform is engineered for security, modularity, and real-time responsiveness.

graph TB
    subgraph Frontend["Frontend (React + TypeScript)"]
        UI[UI Layer<br/>ShadCN + Tailwind + Framer Motion]
        State[State Management<br/>React Context + TanStack Query]
        Router[Routing<br/>React Router v6]
    end

    subgraph Backend["Backend (FastAPI + Python)"]
        API[API Layer<br/>FastAPI Routers]
        Auth[Auth Middleware<br/>JWT + RBAC]
        Services[Service Layer<br/>Business Logic]
        AI[AI Engine<br/>Gemini / OpenRouter]
        Crypto[Crypto Module<br/>AES-256 + SHA-256]
    end

    subgraph Data["Data Layer"]
        ORM[SQLAlchemy ORM]
        DB[(SQLite / PostgreSQL)]
    end

    subgraph External["External Services"]
        GeminiAPI[AI Providers]
    end

    UI --> State --> API
    API --> Auth --> Services
    Services --> AI --> GeminiAPI
    Services --> Crypto
    Services --> ORM --> DB

Loading

---

✨ Core Platform Features

🔐 Cryptographic Health Vault

• Zero-Trust Storage: End-to-end encrypted storage of medical history, allergies, and active medications.
• Sovereign Access: Patients have absolute control over who sees their data and for how long.

🧠 AI Consent Engine

• Data Diffs: See exactly what data a provider is requesting compared to what they already have.
• AI Consent Advisor: Automatically assesses the risk level of data sharing requests and translates complex medical legalese into simple, actionable insights.

⚕️ Clinical Intelligence & Safety

• Prescription Studio: Providers write prescriptions that are instantly verified by an Explainable AI agent against the patient's vault.
• What-If Simulator: A sandbox for providers to test potential medication changes and visualize a "Risk Delta" before finalizing treatment.
• Fraud Radar: Network-wide anomaly detection for institutional users, flagging suspicious patterns like duplicate claims or unusual prescription volumes.

🏛️ Governance & Break-Glass

• Tamper-Evident Audit Trail: Every data access, consent change, and prescription is hash-chained. Users can cryptographically verify the integrity of their clinical timeline.
• Trust Graph: A visual node-based map of all active, expired, and revoked cryptographic connections between the patient and providers.

---

🛠️ Technology Stack

MedSovereign is built on a modern, high-performance stack designed for scale and security:

Component	Technology	Description
Backend Core	FastAPI (Python)	High-performance async API server
Database	SQLite + SQLAlchemy	Relational data mapping & storage
Security	Passlib, bcrypt	Cryptographic hashing & auth
Frontend UI	React 19, TypeScript	Reactive, type-safe user interfaces
Styling	Tailwind CSS v4, ShadCN	Enterprise-grade design system
Animations	Framer Motion	Fluid, hardware-accelerated transitions
Visualizations	React Flow	Interactive node-based data mapping

---

🚦 Quick Start Guide

Get MedSovereign running locally in minutes.

1. Initialize the Backend

cd backend
python -m venv venv

# Windows:
venv\Scripts\activate
# Mac/Linux:
source venv/bin/activate

pip install -r requirements.txt

# The application automatically creates the SQLite database and seeds it with demo data
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

2. Initialize the Frontend

cd frontend
npm install
npm run dev

The platform will be available at http://localhost:5173.

---

🧪 Demo Environment

The development database is pre-seeded with specialized accounts for testing different workflows. Universal Password: password123

Role	Email	Capabilities
Patient	patient@demo.com	Manage vault, approve consents, view trust graph
Doctor	doctor@demo.com	Request access, write prescriptions, use AI safety
Hospital	hospital@demo.com	Institutional access, view fraud radar
Pharmacy	pharmacy@demo.com	Fulfill prescriptions, verify authenticity

---

🗺️ Product Roadmap

• Phase 0: Foundation (Auth, DB, Base UI)
• Phase 1: Core Clinical (Vault, Prescriptions, AI Safety Check)
• Phase 2: Consent Engine (Wallet, AI Advisor, Data Diff)
• Phase 3: Intelligence (Simulator, Fraud Radar)
• Phase 4: Governance (Trust Graph, Audit Timeline, Break-Glass, Guardians)
• Phase 5: Polish & Production Readiness

---

Built for the future of patient-sovereign healthcare.

MohanrajCit / MedSovereign AI