Skip to content

README.md

Latest commit

 

History

History
297 lines (246 loc) · 14 KB

README.md

File metadata and controls

297 lines (246 loc) · 14 KB
Raw

MedoraX ⚕️ — Intelligent Clinical Medication Coordinator & AI Health Platform

React TypeScript Vite Tailwind CSS Java Spring Boot Python FastAPI LangChain MySQL License: MIT

MedoraX is a HIPAA-compliant, enterprise-grade medication management and clinical decision-support ecosystem. Built with a high-performance React + Vite frontend, a robust Spring Boot 3 REST API, and a dedicated Python FastAPI AI Service (powered by LangChain + Mistral AI and Google Gemini Vision AI), MedoraX eliminates prescription mismatch risks, calculates patient adherence metrics, and delivers automated medication reminders.

🌐 Live Application: https://medora-x-five.vercel.app
⚙️ Backend Service: http://localhost:8080 / https://medorax-0.onrender.com
🤖 AI Service (FastAPI): http://localhost:8000

🏗️ System Architecture

MedoraX follows a multi-tier microservices architecture combining standard RESTful APIs with decoupled AI inference services.

graph TD
    subgraph ClientLayer ["Client Layer (React 18 + Vite SPA)"]
        UI["User Interface & Dashboard"]
        AuthModule["Auth & OAuth2 Handler"]
        Store["AppContext & Local State"]
        Axios["Axios API Interceptor"]
    end

    subgraph BackendLayer ["Backend API & Gateway (Spring Boot 3)"]
        CORS["CORS Preflight & Origin Filter"]
        JWTFilter["JWT Authentication Filter"]
        Security["Spring Security Chain"]
        AuthCtrl["Auth Controller"]
        MedCtrl["Medicine Controller"]
        ProfileCtrl["Profile Controller"]
        LogCtrl["Analytics & Log Controller"]
        RemCtrl["Reminder Controller"]
        MismatchCtrl["Mismatch & OCR Controller"]
        AiCtrl["AI Integration Controller"]
        FastAiService["FastAiService RestTemplate Proxy"]
    end

    subgraph AiMicroservice ["AI Service Microservice (Python FastAPI)"]
        FastAPIApp["FastAPI Engine"]
        ExplanationChain["LangChain Medicine Explanation Chain"]
        PrescriptionChain["LangChain Prescription Analysis Chain"]
        MistralLLM["Mistral AI LLM (mistral-small-latest)"]
    end

    subgraph ExternalServices ["External Vision & Data Engines"]
        Gemini["Google Gemini Vision API"]
        OCR["Tesseract OCR Engine"]
    end

    subgraph PersistenceLayer ["Persistence Layer"]
        JPA["Spring Data JPA / Hibernate"]
        DB[("MySQL Database")]
    end

    UI --> Store
    Store --> Axios
    Axios --> CORS
    AuthModule --> Security
    CORS --> JWTFilter
    JWTFilter --> Security
    Security --> AuthCtrl
    Security --> MedCtrl
    Security --> ProfileCtrl
    Security --> LogCtrl
    Security --> RemCtrl
    Security --> MismatchCtrl
    Security --> AiCtrl

    AiCtrl --> FastAiService
    FastAiService -->|HTTP POST| FastAPIApp

    FastAPIApp --> ExplanationChain
    FastAPIApp --> PrescriptionChain
    ExplanationChain --> MistralLLM
    PrescriptionChain --> MistralLLM

    MedCtrl --> Gemini
    MismatchCtrl --> OCR
    MismatchCtrl --> Gemini

    AuthCtrl --> JPA
    MedCtrl --> JPA
    ProfileCtrl --> JPA
    LogCtrl --> JPA
    RemCtrl --> JPA
    JPA --> DB
Loading

Data Flow & Request Lifecycle

  1. Authentication: Users log in via JWT credentials (/auth/login) or Google OAuth2 (/oauth2/authorization/google). On OAuth success, the server redirects back to the SPA with signed tokens.
  2. API Interception: All protected frontend requests attach Authorization: Bearer <token> headers via Axios interceptors.
  3. AI Pipeline:
    • FastAPI Microservice (/api/ai/*): Handles natural language medicine queries, prescription breakdowns, and AI assistant chats using LangChain chains with Mistral AI.
    • Multimodal Vision (/api/mismatch/check): OCR extracts text from prescription images, while Gemini AI cross-references physical pill images against user medication profiles.

✨ Key Features

1. 📊 Interactive Dashboard & Adherence Hub

  • Real-Time Streak Tracker: Computes consecutive compliant intake days without missed doses.
  • Daily Compliance Rate: Calculates percentage of completed vs. missed doses dynamically.
  • Weekly Adherence Graph: Interactive Area & Bar charts powered by Recharts.
  • Active Shelf Catalog: Instant overview of current prescriptions, dosage strengths, and remaining pill counts.

2. 📸 AI Prescription Mismatch & OCR Vision Scanner

  • Multimodal AI Analysis: Scans uploaded physical prescription documents alongside pill packaging.
  • Conflict Identification: Automatically flags drug mismatches, improper dosage frequencies, and dangerous drug-drug interactions using Google Gemini 1.5 Flash.
  • Automated Fallbacks: Analyzes raw OCR text if medicine packaging images are omitted.

3. 🤖 MedoraX AI Health Assistant (FastAPI + LangChain)

  • Clinical Copilot Assistant: Interactive AI assistant for answering medical queries, explaining side effects, and verifying food/beverage interactions.
  • Structured Markdown Rendering: Renders clinical headers, warning callout cards (⚠️), and bulleted recommendations cleanly in the UI.
  • FastAPI Proxy: Spring Boot proxies request payloads seamlessly to the Python FastAPI microservice.

4. 🗓️ Intelligent Reminder Timeline & Schedule Engine

  • Horizontal Date Navigator: 7-day calendar strip allowing historical review and future intake planning.
  • Hourly Medication Timeline: Chronological event sequence showing exact dosage times, food constraints (Before Meals, With Food, After Meals), and administration notes.
  • Compliance Toggles: One-click action buttons to mark doses as Taken, Missed, or Reset.

5. 📈 Analytics & Heatmap Visualization

  • GitHub-Style Compliance Heatmap: 6-month density matrix visualizing long-term intake consistency.
  • Per-Medication Adherence Rates: Individual breakdown of compliance percentages across every active treatment.

6. 👤 Patient Profile & Emergency Escalation

  • Demographic Vitals: Blood group, height, weight, and allergy records.
  • Emergency Guardian Contact: Stores emergency contact details for automated alert escalation.

🛠️ Technology Stack

Layer Technologies
Frontend Framework React 18, TypeScript, Vite 6
Styling & Design System Vanilla CSS, Tailwind CSS 3, Glassmorphism, Dark Mode
Animations & UI Components Framer Motion, Lucide Icons, React Hot Toast
Data Visualization Recharts (Area, Bar, & Line Charts)
HTTP & State Management Axios, React Context API, React Hook Form
Backend Framework Java 21, Spring Boot 3.x, Spring MVC, RestTemplate
Security & Auth Spring Security 6, JWT (io.jsonwebtoken), Google OAuth2
AI Microservice Python 3.11+, FastAPI, Uvicorn, LangChain, Pydantic
AI Models & LLMs Mistral AI (mistral-small-latest), Google Gemini 1.5 Flash
Database & ORM MySQL 8.0, Spring Data JPA, Hibernate
Build Tools Maven (Spring Boot), UV / Pip (Python), Vite (React)

📂 Project Directory Structure

MedoraX/
├── README.md                             # Project Overview & Architecture Guide
├── Ai Service/                           # Python FastAPI AI Microservice
├── app/
│   ├── chains/                           # LangChain chains (explanation & prescription)
│   ├── models/                           # Pydantic Request/Response models
│   ├── prompts/                          # Clinical system prompt templates
│   ├── routes/                           # FastAPI APIRouter endpoints
│   ├── services/                         # LLM invocation services
│   └── main.py                           # FastAPI application entrypoint
├── main.py                               # Root FastAPI runner
├── requirements.txt                      # Python dependencies
├── pyproject.toml / uv.lock              # UV package management
│
├── frontend/                             # React + Vite Frontend Application
│   ├── src/
│   │   ├── api/                          # Axios API clients
│   │   │   ├── ai.api.ts                 # FastAPI AI integration client
│   │   │   ├── analytics.api.ts          # Analytics & Heatmap endpoints
│   │   │   ├── auth.api.ts               # Login, Signup, OAuth endpoints
│   │   │   ├── medicine.api.ts           # Medicine CRUD & AI endpoints
│   │   │   └── mismatch.api.ts           # OCR & Prescription Scanner endpoints
│   │   ├── components/                   # UI components (Header, Sidebar, Cards, Badges)
│   │   ├── context/                      # AppContext global state
│   │   ├── pages/                        # AIAssistant, Dashboard, PrescriptionMismatch, etc.
│   │   └── App.tsx / main.tsx
│   ├── .env                              # VITE_API_BASE_URL config
│   └── package.json
│
└── backend/                              # Spring Boot Java Backend Service
    └── medicineRemainder/
        └── medicineRemainder/
            ├── src/main/java/com/project/medicineRemainder/
            │   ├── Security/             # SecurityConfig, JWT Filter, OAuth2 Handler
            │   ├── controller/           # REST API Controllers (AiIntegrationController, etc.)
            │   ├── dto/                  # AiMedicineRequest, AiChatRequest, etc.
            │   ├── Entity/               # JPA Entities (User, Medicine, Reminder, Log)
            │   └── service/              # FastAiService, GeminiServices, OCRservices, etc.
            ├── src/main/resources/
            │   └── application.properties# Environment configurations & database settings
            ├── run-backend.ps1           # Helper script for running Spring Boot with env vars
            └── pom.xml

📡 REST API Reference

🤖 AI Service Integration (/api/ai)

Method Endpoint Description Proxied To
POST /api/ai/chat AI Health Assistant chat FastAPI POST /chat
POST /api/ai/explain Explain medicine details & side effects FastAPI POST /api/medicine/explain
POST /api/ai/prescription Analyze unstructured prescription text FastAPI POST /api/prescription/analyze
GET /api/ai/health FastAPI service health check FastAPI GET /health

🔐 Authentication (/auth, /api/auth)

Method Endpoint Description Auth Required
POST /auth/signup Register a new user account ❌
POST /auth/login Log in and receive JWT token ❌
GET /oauth2/authorization/google Trigger Google OAuth2 Sign-In ❌
GET /api/auth/me Fetch authenticated user details ✅

💊 Medicines (/api/medicines)

Method Endpoint Description Auth Required
GET /api/medicines Get all active medicines for authenticated user ✅
POST /api/medicines Add a new medicine item ✅
PUT /api/medicines/{id}/taken Mark dose as taken today ✅
PUT /api/medicines/{id}/missed Mark dose as missed today ✅

📸 Prescription Scan & Mismatch (/api/mismatch)

Method Endpoint Description Auth Required
POST /api/mismatch/check Analyze prescription image against medicine image or name ❌
POST /api/mismatch/ocr-only Extract raw text via Tesseract OCR ❌

⚡ Local Setup & Execution Guide

1. Clone the Repository

git clone https://github.com/Rohit-code07/MedoraX.git
cd MedoraX

2. Start Python FastAPI AI Service

cd "Ai Service"

# Option A: Using UV (Recommended)
uv run uvicorn app.main:app --port 8000 --reload

# Option B: Using Pip & Virtual Environment
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --port 8000 --reload

AI Service will run on http://localhost:8000.

3. Start Spring Boot Backend

Navigate to the Spring Boot directory:

cd "backend/medicineRemainder/medicineRemainder"

Edit credentials in run-backend.ps1 or export environment variables, then execute:

.\run-backend.ps1

Backend API will run on http://localhost:8080.

4. Start React Frontend Client

Navigate to the frontend folder:

cd frontend
npm install
npm run dev

Frontend app will run on http://localhost:5173.

📜 License & Acknowledgements

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

Developed with ❤️ by Rohit Verma.