CareSync 🏥

CareSync is a highly secure, HIPAA-compliant, biometric-authenticated medical logging and electronic prescription application. It facilitates seamless and secure interactions between Patients, Doctors, Pharmacists, and First Responders.

The platform features a custom, self-hosted facial recognition API powered by ArcFace and pgvector to securely identify patients and release life-saving medical data to first responders in emergency situations.

---

📖 Table of Contents

• System Overview
• Core Features
• Technology Stack
• Documentation Directory
• Quick Start & Installation
• Environment Setup
• Testing & Quality Assurance
• Security & Compliance
• License

---

🔍 System Overview

CareSync bridges patient confidentiality with immediate emergency medical responsiveness.

In a medical crisis, seconds save lives. If a patient is unconscious or incapacitated, first responders need immediate access to critical medical history (allergies, chronic conditions, emergency contacts) without violating privacy regulations during normal operations.

CareSync achieves this through a dual-layer biometric verification system:

1. Local Biometrics (local_auth): Handles local authentication and session lock management.
2. Cloud Biometrics (ArcFace + Supabase pgvector): Compiles 512-dimension vector representations from multi-pose face scans to identify patients in emergency settings.

---

🏗️ System Architecture

graph TD
    %% Frontend Applications %%
    subgraph Frontend [Flutter Client Application]
        UI[UI Screens & Widgets]
        RP[Riverpod State Management]
        Router[GoRouter Navigation]
    end

    %% Services Layer %%
    subgraph Services [Local & Cloud Services Layer]
        BS[Biometric Service - local_auth]
        AS[Auth Controller]
        SS[Secure Storage - encrypted]
        SbS[Supabase Service]
        AFS[Custom Biometric Service]
        PDF[PDF Service]
        OCR[OCR Service]
    end

    %% Backend Layer %%
    subgraph Backend [Supabase Cloud Backend]
        Auth[Supabase Auth]
        DB[(PostgreSQL Database + RLS)]
        Storage[(Supabase Storage Buckets)]
        EF[Edge Functions]
    end

    %% External APIs %%
    subgraph External [External APIs]
        Azure[Custom Biometric API - ArcFace]
    end

    %% Connections %%
    UI --> RP
    RP --> Router
    RP --> Services
    
    BS --> AS
    AS --> SS
    SbS --> Auth
    SbS --> DB
    SbS --> Storage
    
    AFS --> Azure
    
    OCR --> SbS
    PDF --> SbS

Loading

---

👥 Roles & Workflows

CareSync enforces Role-Based Access Controls (RBAC) to segment workflows across four user groups:

flowchart TD
    Start([User Logs In]) --> RoleCheck{Identify User Role}
    
    RoleCheck -->|Patient| PatientWF[Patient Workflow]
    RoleCheck -->|Doctor| DoctorWF[Doctor Workflow]
    RoleCheck -->|Pharmacist| PharmacistWF[Pharmacist WF]
    RoleCheck -->|First Responder| FRWF[First Responder WF]

    subgraph PatientWF [Patient Panel]
        P1[Register Biometrics / Face ID]
        P2[Track Vitals & Appointments]
        P3[Generate Emergency QR Code]
        P4[Upload & Manage Self-Entered Prescriptions]
    end

    subgraph DoctorWF [Doctor Panel]
        D1[Lookup Patients Securely]
        D2[Issue E-Prescription with Auto-Calculation]
        D3[Generate Signed PDFs]
        D4[Chat with Patients]
    end

    subgraph Pharmacist WF [Pharmacist Panel]
        Ph1[Lookup Prescriptions by Patient/ID]
        Ph2[Verify Doctor Signatures]
        Ph3[Mark Medicines as Dispensed]
        Ph4[View Dispensing History]
    end

    subgraph FRWF [Emergency Panel]
        F1[Scan Emergency QR Code]
        F2[Fallback offline decryption]
        F3[Access Critical Vitals & Allergies]
    end

Loading

---

💻 Technology Stack

• Frontend: Flutter 3.7+ (Dart client), Riverpod (state management), and GoRouter (routing).
• Backend BaaS: Supabase (Auth, PostgreSQL DB, Realtime messaging, and Storage).
• Biometrics API: FastAPI + Uvicorn (Python microservice).
• AI Models: ArcFace (via DeepFace) for facial embedding vectors and Google MediaPipe Face Mesh for pose landmarks.

---

📂 Documentation Directory

For detailed documentation, refer to the specialized sub-guides in the docs/ folder:

• Documentation Index: Main Table of Contents mapping all guides.
• System Architecture: Ecosystem maps and cross-subsystem workflows.
• Flutter Client Architecture: Feature folder structure, Riverpod states, and routing.
• Backend Microservice Architecture: FastAPI design, model preloading, and endpoints.
• Biometric Engine Deep-Dive: Embedding generation math, MediaPipe pose calculation, and consensus scoring.
• Database Schema Audit: ER diagrams, table schemas, triggers, indexes, and RPCs.
• API Reference: Request/Response payloads, headers, and Edge Functions parameters.
• Security & HIPAA Compliance: JWTs, RLS rules, offline QR symmetric keys, and audit log immutability.
• Deployment & Infrastructure: Dockerfiles, env var checklists, and Hugging Face space setups.
• Developer Onboarding Guide: Local machine setup instructions, databases setup, and run scripts.
• Testing & Verification Plan: Running Flutter unit/widget tests and python validation suites.
• Troubleshooting Handbook: Common build errors, database recursion fixes, and camera issues.

---

🚀 Quick Start & Installation

Step 1: Clone the Repository

git clone https://github.com/ankurrera/CareSyncMain.git
cd CareSyncMain

Step 2: Configure Environment Variables

Create a .env file in the project root:

SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_ANON_KEY=your-anon-public-key
BIOMETRIC_API_URL=http://localhost:8000
HF_TOKEN=your-optional-huggingface-token

Step 3: Run the Biometric API

1. Navigate to the biometric_api folder and activate a virtual environment:

   cd biometric_api
   python3 -m venv venv
   source venv/bin/activate

2. Install Python dependencies and run the server:

   pip install -r requirements.txt
   python download_models.py
   uvicorn main:app --reload --port 8000

Step 4: Run the Flutter Client

flutter pub get
flutter run

---

🧪 Testing & Quality Assurance

• Flutter Tests:

  flutter test

• Python Biometric Pipeline Tests:

  cd biometric_api
  python -m unittest test_biometric_pipeline.py

---

🛡️ Security & HIPAA Compliance

• Row-Level Security (RLS): Protects all tables in PostgreSQL.
• Tamper-Proof Audit Logging: Database triggers block any edits or deletions on biometric_access_logs.
• 15-Minute Auto-Lock: Automatically locks the app session after 15 minutes of inactivity, requiring local biometric re-authentication.

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.