🏥 CareLink

AI-Powered Healthcare Platform

A comprehensive healthcare solution combining AI symptom triage, telemedicine, digital health records, and emergency response

Features • Tech Stack • Getting Started • Documentation • Contributing

📋 Table of Contents

Overview
Features
Tech Stack
Architecture
Prerequisites
Getting Started
Running the Application
API Documentation
Testing
Deployment
Project Structure
Contributing
License
Disclaimer

🌟 Overview

CareLink is an enterprise-grade, AI-powered healthcare platform that bridges the gap between patients and medical care. It combines cutting-edge machine learning, natural language processing, and telemedicine capabilities to provide:

🤖 Intelligent symptom triage with ML-based risk assessment (LOW/MEDIUM/HIGH)
🩺 Medical image analysis using Vision-Language Models (VLM)
👨‍⚕️ Telemedicine consultations (video, audio, text)
📋 Digital health records management with HIPAA-compliant storage
🚨 Emergency response system with GPS hospital location and first-aid guidance
💊 Medicine & pharmacy search with price comparison
🌐 Multilingual support (English, Spanish, French)

✨ Features

🏥 AI-Powered Symptom Triage

Free-text symptom input with NLP extraction
Machine learning risk classification (LOW/MEDIUM/HIGH)
Clinical safety rule engine with 8+ deterministic rules
Confidence-based escalation for quality control
Patient-friendly explanations in multiple languages
Emergency flag auto-detection
Complete audit trail for compliance

🤖 Medical Image Analysis

Medical photo capture and upload
AI-powered image analysis using MedGemma 4B-IT Vision-Language Model
Severity assessment from medical images
Finding extraction and labeling
Non-diagnostic reference with compliance disclaimers

👨‍⚕️ Telemedicine Consultations

Video consultations with real-time video streaming
Audio consultations for phone-based support
Text consultations via secure chat
Doctor authentication and verification
Digital prescriptions and referrals
Appointment scheduling and reminders
Consultation history tracking

📋 Digital Health Records

Complete health profile management
Medical history, immunizations, test reports
Medication tracking with adherence monitoring
Trend analysis for health metrics (BP, glucose, weight)
QR code sharing for emergency access
Data access audit logs (HIPAA-compliant)
Export in standard formats

🚨 Emergency Response System

One-tap SOS emergency activation
GPS-based nearest hospital location
Automatic emergency contact notification
AI-guided first-aid instructions
Crisis navigation with step-by-step guidance
Post-emergency follow-up reminders

💊 Medicine & Pharmacy Search

Comprehensive medicine database search
GPS-based pharmacy locator
Real-time price comparison across pharmacies
Generic alternative suggestions
Digital prescription upload
Purchase tracking

🔔 Smart Notifications

Appointment reminders
Medication schedules and adherence alerts
Health alerts for unusual readings
Test result notifications
Telemedicine updates

🌐 Multilingual Support

English, Spanish, French
Real-time language switching
AI responses in user's preferred language

🛠️ Tech Stack

Frontend (Mobile App)

Component	Technology	Version	Purpose
Framework	React Native	0.83.2	Cross-platform mobile development
Build System	Expo	~55.0.4	Development & build toolchain
UI Library	React	19.2.0	Component architecture
Navigation	React Navigation	7.x	Screen navigation
State Management	Context API	-	Global state management
Backend Client	Supabase JS	2.98.0	Database & auth integration
Storage	AsyncStorage	2.2.0	Local data persistence

Key Expo Modules:

expo-camera - Medical image capture
expo-image-picker - Image/file uploads
expo-local-authentication - Biometric security
expo-location - GPS for hospital location
expo-print & expo-sharing - Document export
expo-updates - Over-the-air updates

Backend (AI Service)

Component	Technology	Version	Purpose
API Framework	FastAPI	0.109.0	RESTful microservice
Server	Uvicorn	0.27.0	ASGI application server
ML Framework	Scikit-Learn	1.4.0	Risk classification
Boosting Model	XGBoost	2.0.3	Enhanced predictions
NLP Engine	spaCy	3.7.2	Entity extraction & tokenization
LLM Framework	HuggingFace Transformers	4.50+	Vision-Language Models
Model Optimization	BitsAndBytes	0.43+	4-bit quantization for GPU
VLM Model	MedGemma 4B-IT	Latest	Medical image analysis
Data Processing	Pandas + NumPy	Latest	Feature engineering

Security & Monitoring:

JWT authentication with python-jose
Password hashing with passlib[bcrypt]
Prometheus metrics export
Structured JSON logging

Database & Storage

Component	Technology	Purpose
Primary Database	Supabase (PostgreSQL)	User data, health records, chat history
Local Database	SQLite	Audit trails, prediction cache
ORM	SQLAlchemy	Database abstraction layer
File Storage	Supabase Storage	Medical images, test reports

Infrastructure

Component	Technology	Purpose
Containerization	Docker	Backend deployment
Orchestration	Docker Compose	Local development
CI/CD	GitHub Actions	Automated testing & deployment
Mobile Deployment	Expo EAS	Android/iOS builds

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Mobile App (React Native)               │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────────┐ │
│  │ Symptom │  │   Tele   │  │ Health  │  │  Emergency   │ │
│  │  Triage │  │ Medicine │  │ Records │  │   Response   │ │
│  └────┬────┘  └────┬─────┘  └────┬────┘  └──────┬───────┘ │
└───────┼────────────┼─────────────┼───────────────┼─────────┘
        │            │             │               │
        └────────────┴─────────────┴───────────────┘
                            │
                    ┌───────▼────────┐
                    │  API Gateway   │
                    └───────┬────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
┌───────▼────────┐  ┌───────▼────────┐  ┌──────▼──────┐
│  AI Microservice│  │    Supabase    │  │  External   │
│   (FastAPI)     │  │   PostgreSQL   │  │   APIs      │
│                 │  │                │  │             │
│ ┌─────────────┐ │  │ ┌────────────┐ │  │ - Maps      │
│ │ ML Model    │ │  │ │ Users      │ │  │ - Pharmacy  │
│ │ Triage      │ │  │ │ Health Rec │ │  │ - Translation│
│ └─────────────┘ │  │ │ Chat Hist  │ │  └─────────────┘
│ ┌─────────────┐ │  │ │ Appts      │ │
│ │ VLM Model   │ │  │ └────────────┘ │
│ │ MedGemma 4B │ │  │                │
│ └─────────────┘ │  │ ┌────────────┐ │
│ ┌─────────────┐ │  │ │  Storage   │ │
│ │ NLP Engine  │ │  │ │  (Images)  │ │
│ │ spaCy       │ │  │ └────────────┘ │
│ └─────────────┘ │  └────────────────┘
│ ┌─────────────┐ │
│ │ Rules Engine│ │
│ │ Clinical    │ │
│ └─────────────┘ │
└─────────────────┘

Request Flow (Symptom Triage Example)

User Input → NLP Processing → Feature Engineering → ML Classification
    ↓              ↓                  ↓                    ↓
Symptom Text   Entity Extract    Feature Vector      Risk Prediction
    ↓              ↓                  ↓                    ↓
                Clinical Rules Engine Override (if triggered)
                              ↓
                   Confidence Controller Check
                              ↓
                   Explanation Generation (LLM)
                              ↓
                    JSON Response to Mobile

📋 Prerequisites

Before you begin, ensure you have the following installed:

For Frontend Development

Node.js >= 16.x (Download)
npm or yarn (comes with Node.js)
Expo CLI (install via npm install -g expo-cli)
Android Studio (for Android development) or Xcode (for iOS development)
Expo Go app on your mobile device (for testing)

For Backend Development

Python >= 3.11 (Download)
pip (Python package manager)
virtualenv or venv for virtual environments
Docker & Docker Compose (optional, for containerized deployment)
CUDA-capable GPU (optional, for VLM model - falls back to CPU)

For Database

Supabase Account (Sign up free)
Supabase CLI (optional, for local development)

🚀 Getting Started

Backend (AI Service) Setup

Navigate to AI service directory
```
cd ai-service
```

Create Python virtual environment

python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

Install dependencies
```
pip install -r requirements.txt
```
Download spaCy language model
```
python -m spacy download en_core_web_sm
```

Set up environment variables

Create a .env file in the ai-service directory:

# Environment
ENVIRONMENT=development
DEBUG=true
LOG_LEVEL=INFO

# Server Configuration
HOST=0.0.0.0
PORT=8000
CORS_ORIGINS=http://localhost:3000,http://localhost:19006

# Model Configuration
MODEL_VERSION=v1.0.0
CONFIDENCE_THRESHOLD=0.6
ESCALATION_THRESHOLD=0.75

# Security
API_KEY_ENABLED=false
API_KEY=your-secret-api-key-here

# Monitoring
ENABLE_METRICS=true
ENABLE_AUDIT_LOGGING=true

Generate training data and train ML model

# Generate synthetic training data
python data/synthetic_generator.py

# Train the ML model
python training/train_model.py

Run the AI service

# Development mode with auto-reload
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Or use Docker
docker-compose up -d

Verify installation

Open your browser and navigate to:
- API Documentation: http://localhost:8000/docs
- Health Check: http://localhost:8000/health
- Metrics: http://localhost:8000/api/v1/metrics

Frontend (Mobile App) Setup

Navigate to mobile app directory
```
cd CareLink
```
Install dependencies
```
npm install
# or
yarn install
```

Configure Supabase

Create a src/config/supabase.js file:

export const SUPABASE_URL = 'https://your-project.supabase.co';
export const SUPABASE_ANON_KEY = 'your-anon-key-here';

Get these values from your Supabase Dashboard.

Configure AI Service endpoint

Update src/services/aiService.js with your backend URL:
```
const AI_SERVICE_URL = 'http://localhost:8000'; // or your deployed URL
```
Run database migrations
```
npm run db:push
```
Seed initial data (optional)
```
npm run seed
```
Start the development server
```
npm start
# or
expo start
```
Run on device/emulator
- Press a for Android emulator
- Press i for iOS simulator (macOS only)
- Scan QR code with Expo Go app on your physical device

Database Setup

Option 1: Cloud Supabase (Recommended)

Create a Supabase project
- Go to Supabase Dashboard
- Click "New Project"
- Note your project URL and anon key
Run database migrations
```
cd supabase
npx supabase db push
```
Set up storage buckets

In Supabase Dashboard → Storage, create buckets:
- medical-images (for medical photos)
- health-reports (for test results, PDFs)
- profile-pictures (for user avatars)

Option 2: Local Supabase (Development)

Install Supabase CLI
```
npm install -g supabase
```
Initialize Supabase locally
```
cd supabase
supabase start
```
Access local services
- API: http://localhost:54321
- Studio: http://localhost:54323
- Database: postgresql://postgres:postgres@localhost:54322/postgres

🎯 Running the Application

Full Stack (Recommended)

Terminal 1 - Backend AI Service

cd ai-service
source venv/bin/activate  # On Windows: venv\Scripts\activate
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 - Mobile App
```
cd CareLink
npm start
```
Terminal 3 - Supabase (if local)
```
cd supabase
supabase start
```
Open Expo Go on your mobile device and scan the QR code

Docker Deployment (Production-like)

# From ai-service directory
docker-compose up -d

# Verify services
docker-compose ps
docker-compose logs -f carelink-ai

Building Mobile App

Development Build

cd CareLink
eas build --profile development --platform android

Production Build

# Android
eas build --profile production --platform android

# iOS (requires Apple Developer account)
eas build --profile production --platform ios

📡 API Documentation

Base URL

http://localhost:8000/api/v1

Key Endpoints

1. Symptom Triage Prediction

POST /triage/predict
Content-Type: application/json

{
  "symptoms_text": "I have chest pain and shortness of breath",
  "age": 45,
  "duration_days": 1,
  "chronic_conditions": ["diabetes", "hypertension"],
  "language": "en"
}

Response:

{
  "prediction": "HIGH",
  "probabilities": {
    "low": 0.05,
    "medium": 0.15,
    "high": 0.80
  },
  "confidence": 0.89,
  "rules_triggered": ["CHEST_PAIN_CARDIOVASCULAR"],
  "explanation": "Based on your symptoms, immediate medical attention is recommended...",
  "emergency_flag": true,
  "escalated": false,
  "model_version": "v1.0.0",
  "request_id": "req_abc123",
  "timestamp": "2024-01-15T10:30:00Z"
}

2. Medical Image Analysis

POST /triage/analyze-image
Content-Type: multipart/form-data

image: <binary file>
clinical_question: "What does this rash look like?"

3. AI Chat

POST /triage/chat
Content-Type: application/json

{
  "message": "What should I do for a headache?",
  "context": {
    "previous_messages": [],
    "user_profile": {}
  },
  "language": "en"
}

4. Health Check

GET /health

5. Metrics (Prometheus)

GET /api/v1/metrics/prometheus

Interactive API Documentation

Once the backend is running, visit:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

🧪 Testing

Backend Tests

cd ai-service

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest tests/ --cov=app --cov-report=html

# Run specific test file
pytest tests/test_routes.py -v

# View coverage report
open htmlcov/index.html  # On macOS

Frontend Tests

cd CareLink

# Run tests (when configured)
npm test

# Run linting
npm run lint

Manual Testing Checklist

🚢 Deployment

Backend Deployment

Docker (Recommended)

cd ai-service

# Build image
docker build -t carelink-ai:latest .

# Run container
docker run -d \
  -p 8000:8000 \
  -e ENVIRONMENT=production \
  -e API_KEY_ENABLED=true \
  -e API_KEY=your-production-key \
  --name carelink-ai \
  carelink-ai:latest

Cloud Platforms

AWS EC2 / Google Cloud / Azure VM:

Set up virtual machine with Python 3.11+
Clone repository
Install dependencies
Configure systemd service
Set up reverse proxy (Nginx)
Configure SSL with Let's Encrypt

Heroku:

heroku create carelink-ai
git subtree push --prefix ai-service heroku main

Railway / Render:

Connect GitHub repository
Set build command: pip install -r requirements.txt
Set start command: uvicorn app.main:app --host 0.0.0.0 --port $PORT

Frontend Deployment

Expo EAS Build

cd CareLink

# Configure EAS
eas build:configure

# Build for Android
eas build --platform android --profile production

# Build for iOS
eas build --platform ios --profile production

# Submit to stores
eas submit --platform android
eas submit --platform ios

Web Deployment (Expo Web)

npm run web

# Build for production
expo build:web

# Deploy to Netlify/Vercel
netlify deploy --dir=web-build --prod

Database Deployment

Supabase automatically handles:

Database backups
Scaling
Security updates
SSL encryption

For production:

Upgrade to Supabase Pro plan (if needed)
Set up database backups
Configure row-level security (RLS) policies
Enable Point-in-Time Recovery (PITR)

📁 Project Structure

CareLink-/
├── CareLink/                      # Mobile app (React Native + Expo)
│   ├── src/
│   │   ├── components/           # Reusable UI components
│   │   ├── context/              # Context providers (Auth, Language)
│   │   ├── i18n/                 # Internationalization (EN/ES/FR)
│   │   ├── navigation/           # React Navigation setup
│   │   ├── screens/              # All app screens
│   │   │   ├── ai/               # AI chat screens
│   │   │   ├── auth/             # Login, signup, onboarding
│   │   │   ├── emergency/        # Emergency response
│   │   │   ├── health/           # Health records
│   │   │   ├── home/             # Home dashboard
│   │   │   ├── medicine/         # Medicine search
│   │   │   ├── notifications/    # Notifications
│   │   │   ├── settings/         # Settings
│   │   │   ├── symptomChecker/   # Symptom triage
│   │   │   └── telemedicine/     # Telemedicine
│   │   ├── services/             # API services
│   │   │   ├── aiService.js      # AI backend integration
│   │   │   ├── supabase.js       # Supabase client
│   │   │   ├── medicineService.js
│   │   │   └── translationService.js
│   │   └── theme/                # UI theming
│   ├── assets/                   # Images, fonts, icons
│   ├── App.js                    # Root component
│   ├── app.json                  # Expo configuration
│   ├── eas.json                  # EAS Build configuration
│   └── package.json              # Dependencies
│
├── ai-service/                    # Backend AI microservice (FastAPI)
│   ├── app/
│   │   ├── api/                  # API routes & schemas
│   │   ├── core/                 # Configuration, logging, security
│   │   ├── services/             # Business logic
│   │   │   ├── triage_service.py      # ML triage
│   │   │   ├── rule_engine.py         # Clinical rules
│   │   │   ├── confidence_controller.py
│   │   │   └── explanation_service.py # LLM explanations
│   │   ├── models/               # ML model artifacts
│   │   ├── nlp/                  # NLP preprocessing
│   │   ├── monitoring/           # Metrics & audit logs
│   │   └── main.py               # FastAPI app
│   ├── data/                     # Training data
│   │   └── synthetic_generator.py
│   ├── training/                 # Model training scripts
│   │   └── train_model.py
│   ├── tests/                    # Test suite
│   ├── Dockerfile                # Docker configuration
│   ├── docker-compose.yml        # Local deployment
│   ├── requirements.txt          # Python dependencies
│   └── README.md                 # AI service docs
│
├── supabase/                      # Database & backend
│   ├── migrations/               # Database migrations
│   ├── config.toml               # Supabase configuration
│   └── seed.sql                  # Initial data
│
├── original_assets/              # Design assets
├── PRESENTATION_ANALYSIS.md      # Technical documentation
└── README.md                     # This file

🤝 Contributing

We welcome contributions to CareLink! Here's how you can help:

Development Workflow

Fork the repository

git clone https://github.com/yourusername/carelink.git
cd carelink

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Write clean, documented code
- Follow existing code style
- Add tests for new features
- Update documentation as needed

Test your changes

# Backend tests
cd ai-service && pytest tests/ -v

# Frontend linting
cd CareLink && npm run lint

Commit your changes
```
git add .
git commit -m "feat: add new feature description"
```
Use conventional commits:
- feat: new feature
- fix: bug fix
- docs: documentation
- style: formatting
- refactor: code restructuring
- test: adding tests
- chore: maintenance

Push and create Pull Request

git push origin feature/your-feature-name

Code Standards

Frontend: Follow React Native best practices, use functional components
Backend: Follow PEP 8, use type hints, document functions
Commit Messages: Use conventional commits format
Testing: Aim for >80% code coverage
Documentation: Update README and inline comments

Areas for Contribution

🐛 Bug fixes
✨ New features
📝 Documentation improvements
🌐 Translations (add new languages)
🎨 UI/UX enhancements
⚡ Performance optimizations
🧪 Test coverage improvements

📄 License

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

MIT License

Copyright (c) 2024 CareLink Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

⚠️ Disclaimer

IMPORTANT: THIS SOFTWARE IS FOR EDUCATIONAL AND DEMONSTRATION PURPOSES ONLY

🚨 Not for Clinical Use

CareLink is a demonstration project and is NOT intended for actual clinical use without proper:

✅ Medical device regulatory approval (FDA, CE, etc.)
✅ Clinical validation studies
✅ HIPAA compliance certification
✅ Professional liability insurance
✅ Medical oversight and governance
✅ Data security audits
✅ Legal review in your jurisdiction

Medical Disclaimer

This application does NOT replace professional medical advice
Always consult a qualified healthcare provider for medical concerns
The AI predictions are probabilistic and may be inaccurate
Do NOT use for emergency medical situations - call emergency services (911, etc.)
The application is provided "AS IS" without warranty of any kind

Data Privacy

Implement proper PHI (Protected Health Information) safeguards before production use
Ensure compliance with HIPAA, GDPR, and local healthcare data regulations
Use end-to-end encryption for sensitive data
Obtain proper informed consent from users

Liability

The developers and contributors assume NO liability for:

Medical decisions made based on this application
Data breaches or security incidents
Regulatory violations
Any damages arising from use of this software

For production healthcare deployment, consult with:

Healthcare legal experts
Medical device regulatory consultants
HIPAA compliance specialists
Licensed medical professionals

📞 Support & Contact

Community

Quick Links

🙏 Acknowledgments

MedGemma - Medical Vision

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
CareLink		CareLink
ai-service		ai-service
original_assets		original_assets
supabase		supabase
.gitignore		.gitignore
PRESENTATION_ANALYSIS.md		PRESENTATION_ANALYSIS.md
PROJECT_UNDERSTANDING_REPORT.md		PROJECT_UNDERSTANDING_REPORT.md
README.md		README.md
SYSTEM_DESIGN_DEVOPS_DOCUMENTATION.md		SYSTEM_DESIGN_DEVOPS_DOCUMENTATION.md
SYSTEM_REQUIREMENTS_DOCUMENT.md		SYSTEM_REQUIREMENTS_DOCUMENT.md
android-icon-background.png		android-icon-background.png
android-icon-foreground.png		android-icon-foreground.png
android-icon-monochrome.png		android-icon-monochrome.png
carelink_icon.png		carelink_icon.png
carelink_icon_1024.png		carelink_icon_1024.png
color-schemes.md		color-schemes.md
commands.txt		commands.txt
favicon.png		favicon.png
icon.png		icon.png
pdr for stjoseph.docx		pdr for stjoseph.docx
pdr for stjoseph.pdf		pdr for stjoseph.pdf
pdr for stjoseph_ocr.pdf		pdr for stjoseph_ocr.pdf
pdr_text.txt		pdr_text.txt
splash-icon.png		splash-icon.png
temp_meds_old.js		temp_meds_old.js

Folders and files

Latest commit

History

Repository files navigation