💊 MedSync AI

A full-stack, open-source medication adherence assistant that combines a modern React frontend with an Express.js backend, AI health agents, real-time notifications, and multilingual report analysis.

Built for real-world usability to tackle the global issue of medication non-adherence.

---

📢 Announcements & Updates

All important project updates, rules, and timelines are shared in the GitHub Discussions → Announcements section.

➡️ Please make sure to check it regularly.

---

✨ Core Features & Recent Updates

Thanks to our amazing community, MedSync AI is packed with cutting-edge health-tech features:

• Secure Auth & Dashboard: JWT-based signup/login. View today’s meds, adherence stats, and streaks at a glance.
• Medication Management: Add, update, and track medications. Support for Bulk Medicine Input and scheduling.
• ⚠️ Drug Interaction Checker: Automatically checks for potential conflicts between medications to ensure patient safety.
• 🤖 AI Health Agents: Multi-agent chat for medication info, health guidance, and triage powered by LangChain + LLMs (Groq/Gemini).
• 📄 Report Analysis & Chat: Upload medical PDFs to get AI-driven insights, and chat interactively with your analyzed reports.
• 📅 Google Calendar Sync: Seamlessly push your medication schedules directly to your Google Calendar.
• 📶 Offline Support & Sync: Built-in action queuing and offline database support so users never miss a beat, even with a poor connection.
• 🔔 Real-Time Notifications: Push alerts and reminders powered by Socket.IO and automated email services.

🌍 Comprehensive Multilingual & Accessibility System

MedSync AI features a robust translation and accessibility engine to support diverse users:

• Native Language Support: Full UI and AI translation for English (en), Spanish (es), and Hindi (hi).
• Auto-Translation: Medication instructions and AI report analyses are automatically translated into the user's preferred language, preserving critical medical terminology.
• Readability Checker (Flesch-Kincaid): Analyzes the complexity of medical texts, scores them (Green/Yellow/Red), and provides actionable simplification suggestions to ensure patients understand their health data.

---

🧩 Tech Stack

Frontend (client/)

• React (Vite), Tailwind CSS, React Router
• Axios, React Context API
• Socket.IO Client, Recharts, Lucide React

Backend (server/)

• Node.js, Express.js
• MongoDB + Mongoose
• JWT Auth, bcrypt
• LangChain with Groq/Gemini (LLMs)
• Socket.IO for real-time notifications
• Google Calendar API (OAuth2)
• Translation APIs & custom Medical Readability utilities

(For a deep dive into the system architecture, please see ARCHITECTURE.md)

---

🗂️ Repository structure

MedSync-AI/
├─ client/                  # React app
│  ├─ src/pages             # Views (Dashboard, Login, addMedication, agents, etc.)
│  ├─ src/components        # Reusable components (ProtectedRoute, Navbar, etc.)
│  ├─ src/context           # Contexts (medication, notification, socket, calendarSync)
│  └─ src/App.jsx           # Routing setup
└─ server/                  # Express API
   ├─ src/routes            # Route definitions (e.g., medicineRoutes.js)
   ├─ src/api               # Controllers (e.g., addMedicineController.js)
   ├─ src/models            # Mongoose schemas (User, medicineModel, HealthProfile, ...)
   ├─ src/utils             # AI handlers, utilities (medical_model.js, emergency_model.js, ...)
   ├─ src/middlewares       # Middleware (authMiddleware.js)
   └─ src/index.js          # App + Socket.IO entry point

---

🏁 Getting started

Prerequisites

• Node.js (LTS recommended)
• npm
• MongoDB connection URI
• API keys for Groq/Gemini (and any other LLM providers you use)
• Google OAuth2 credentials (if using Calendar sync)

Quick dev (two terminals)

• Terminal A: cd server && npm install && npm run dev (starts API on 8080)
• Terminal B: cd client && npm install && npm run dev (starts web on 5173)

Useful scripts

• Frontend: npm run dev, npm run build, npm run lint, npm run preview
• Backend: npm run dev, npm start

1) Clone

git clone https://github.com/tirth-patel06/MedSync-AI.git
cd MedSync-AI

2) Frontend setup

cd client
npm install
npm run dev
# App at http://localhost:5173

3) Backend setup

cd server
npm install
# Create .env (see below) with your own keys
npm run dev
# Server at http://localhost:8080

---

🔐 Environment variables (server)

Create server/.env with your own (do NOT commit secrets):

PORT=8080
MONGO_URI=your_mongo_uri
JWT_SECRET=your_jwt_secret

GROQ_API_KEY=your_groq_key
GEMINI_API_KEY=your_gemini_key
HUGGINGFACEHUB_API_KEY=your_hf_key

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=your_redirect_uri

REPORT_API=your_report_service_api_key
REPORT_TEMPLATE_ID=5b077b23e86a4726

# Multilingual & Translation (Phase 2)
GOOGLE_TRANSLATE_API_KEY=your_google_translate_api_key
TRANSLATION_CACHE_TTL=86400
DEFAULT_LANGUAGE=en
SUPPORTED_LANGUAGES=en,es,hi
TRANSLATION_PROVIDER=google

If you use report-generation/analysis services, add those keys/IDs here too.

Security note: Never commit real keys. If any were exposed, rotate them immediately and scrub from history.

Translation setup:

• Obtain a Google Translate API key from Google Cloud Console.
• Add GOOGLE_TRANSLATE_API_KEY to your .env file.
• TRANSLATION_CACHE_TTL: Cache duration in seconds (default 86400 = 24 hours).
• TRANSLATION_PROVIDER: Currently supports google (libretranslate support coming in Phase 2.2).

Frontend .env (client)

Add a client/.env to point the React app at your backend and OAuth endpoints:

VITE_API_BASE_URL=http://localhost:8080
VITE_SOCKET_URL=http://localhost:8080
VITE_GOOGLE_OAUTH_LOGIN=http://localhost:8080/api/oauth/login

If you change backend ports/hosts, update these values. Align VITE_SOCKET_URL with your Socket.IO server.

---

🧪 Running the apps together

• Start backend first: npm run dev in server/.
• Start frontend: npm run dev in client/.
• Configure frontend .env (if applicable) to point to the backend API and Socket.IO endpoints.

---

🧠 Key features

• Secure auth: JWT-based signup/login with protected routes.
• Medication management: CRUD for meds, schedule tracking.
• Notifications & reminders: Scheduler + real-time alerts via Socket.IO.
• AI agents: Multi-agent chat for medication info, health guidance, triage (LangChain + LLMs).
• Report analysis & chat: Upload PDFs, get AI-driven insights, and chat with analyzed reports.
• Google Calendar sync: Optional calendar integration for medication schedules.
• Dashboard: Today’s meds, adherence stats, and streaks at a glance.

Multilingual Phase 1 (schema & API updates)

• User schema now includes preferredLanguage (enum: en, es, hi; default: en). APIs that return user objects should surface this, and clients can send it during signup/update.
• Report schema stores translatedAnalysis (Map of language code → text), originalLanguage (default en), and readabilityScore ({ fleschKincaid, fleschReadingEase, readingLevel, grade }). These fields are optional and safe for existing documents.
• Medication schema adds originalInstructions and translatedInstructions (es, hi) to hold multilingual dosage directions; these are optional.
• Migration/backfill guidance: fields are non-breaking with defaults. If you want to backfill existing data, run a one-time script such as:

// From a Mongo shell or script with Mongoose connected
db.reports.updateMany({ originalLanguage: { $exists: false } }, { $set: { originalLanguage: "en" } });
db.users.updateMany({ preferredLanguage: { $exists: false } }, { $set: { preferredLanguage: "en" } });
db.medications.updateMany(
   { originalInstructions: { $exists: false } },
   { $set: { originalInstructions: "" } }
);

These changes complete Phase 1 of the multilingual implementation plan and keep existing data intact.

Multilingual Phase 2 (Translation Service Integration)

Phase 2 provides translation capabilities for multilingual content:

• Translation Service (server/src/services/translationService.js): Wraps Google Translate API with caching (via node-cache), batch translation, language detection, retry logic, and medical terminology preservation.

• Language Configuration (server/src/utils/languageConfig.js): Central configuration for supported languages (English, Spanish, Hindi) with utilities for validation and reading level mappings.

• Medical Terminology Dictionary (server/src/utils/medicalTerminology.js): Maps medical terms to accurate translations across languages (e.g., ibuprofen → ibuprofeno/इबुप्रोफेन), ensuring clinical accuracy.

• Translation Service API:

  • translateText(text, targetLang, context) — Translate a single text.
  • translateBatch(texts[], targetLang) — Batch translate multiple texts.
  • detectLanguage(text) — Detect the language of given text.
  • getSupportedLanguages() — List supported languages.
  • invalidateCache(key) — Clear cache for a specific key or all.

• Caching: Translations are cached with a TTL to reduce API calls (default 24 hours, configurable via TRANSLATION_CACHE_TTL).

• Error handling: Translation failures gracefully fall back to the original text; no crashes.

• Medical Context: When translating medical content, the service preserves medical terminology and can apply specialized dictionaries for accuracy.

Install dependencies with npm install in the server/ directory after adding Phase 2 files.

---

Multilingual Phase 3 (Readability Checker Implementation)

Phase 3 implements text readability analysis for medical content across multiple languages:

• Readability Checker (server/src/utils/readabilityChecker.js): Analyzes text readability using:

  • Flesch-Kincaid Grade Level — Estimates US grade level required to understand text (0-16+)
  • Flesch Reading Ease — Scores text on 0–100 scale (higher = easier to read)
  • Language-specific adaptation — Adjusted algorithms for English, Spanish, and Hindi
  • Syllable counting — Implements multi-language syllable detection
  • Recommendations — Generates actionable simplification suggestions

• Readability Configuration (server/src/utils/readabilityConfig.js): Defines:

  • Complexity thresholds for medical content (simple/moderate/complex)
  • Reading level categories with Flesch scores and grade mappings
  • Language-specific targets (e.g., optimal words per sentence)
  • Color coding for UI indicators (green/yellow/red)
  • Simplification suggestion templates

• API Response Format:

{
  fleschKincaid: 8.5,        // Grade level
  fleschReadingEase: 65.2,   // 0-100 ease score
  readingLevel: 'high',      // Category key
  readingLevelLabel: 'High School',
  grade: 8,                  // Rounded grade
  isTooComplex: false,       // Above threshold?
  statistics: {
    wordCount: 150,
    sentenceCount: 8,
    syllableCount: 250,
    averageWordsPerSentence: 18.75,
    averageSyllablesPerWord: 1.67
  },
  recommendations: [
    "✓ Text is at appropriate reading level for medical content",
    "📌 Consider shorter sentences...",
    "💡 Medical terms are acceptable..."
  ]
}

• Language support: English (standard Flesch-Kincaid), Spanish (adapted coefficients), Hindi (Devanagari-aware syllable counting)
• Accessibility: Color-coded complexity assessment, detailed metrics, and specific improvement suggestions

Install dependencies with npm install in the server/ directory (includes syllable package for enhanced syllable counting).

---

Multilingual Phase 4 (Backend API Endpoints)

Phase 4 exposes translation, language preference, and report readability/translation APIs:

• Translation API (/api/translate):

  • POST /api/translate — Translate a single text (text, targetLanguage, context = medical/general).
  • POST /api/translate/batch — Batch translate array texts[] to targetLanguage.
  • GET /api/translate/supported — List supported languages.

• Language Preference API (/api/languages):

  • GET /api/languages/user — Fetch user preferred language + supported list.
  • PUT /api/languages/user — Update preferred language (body: { language }).
  • GET /api/languages/supported — List supported languages.

• Report Analysis & Readability (/api/report):

  • POST /api/report/analyze — Analyze an uploaded report; saves analysis with readability + optional translation (uses language param or user preference).
  • POST /api/report/chat — Chat over a stored report (requires reportId, question).
  • GET /api/report/:id/translate/:language — On-demand translation of stored analysis with caching in the document.
  • GET /api/report/:id/readability — Returns readability metrics; backfills if missing.

• Behavior:

  • Auto-detects source language; auto-translates to requested language or user preference when provided.
  • Stores translatedAnalysis, originalLanguage, and readabilityScore in Report documents.
  • Graceful fallbacks: translation errors return original text; readability always returns a score.

Run npm install in server/ if you haven’t added dependencies yet.

---

Multilingual Phase 5 (Frontend UI Components)

Phase 5 provides React components, context, and hooks for multilingual UX on the client:

• Language Context (client/src/context/languageContext.jsx): Global state management

  • Fetches user's preferred language from the backend on mount
  • Methods: setLanguage(code), translateText(text, lang?, context?), translateBatch(texts[], lang?)
  • Gracefully handles API failures (fallback to defaults)

• useTranslation Hook (client/src/hooks/useTranslation.js): Custom hook to access:

  • language — Current language code
  • setLanguage — Update preference
  • supportedLanguages — List of available languages
  • translateText — Translate a single text
  • translateBatch — Batch translate multiple texts
  • loading, error — State and error tracking

• LanguageSwitcher Component (client/src/components/LanguageSwitcher.jsx):

  • Dropdown button in Navbar showing current language (native name, e.g., "Español")
  • Displays all supported languages with native names
  • Accessible (ARIA labels, keyboard navigation)
  • Updates backend user preference on selection
  • Styled with Tailwind (blue gradient, icons via lucide-react)

• ReadabilityIndicator Component (client/src/components/ReadabilityIndicator.jsx):

  • Badge showing Flesch-Kincaid grade level with color coding:
    • 🟢 Green: Grades 1–6 (easy)
    • 🟡 Yellow: Grades 7–12 (moderate)
    • 🔴 Red: Grade 13+ (complex)
  • Interactive tooltip with grade details on hover
  • Optional showDetails and showRecommendations props
  • Displays actionable suggestions for simplification

• TranslationBadge Component (client/src/components/TranslationBadge.jsx):

  • Shows "Originally [Language]" indicator when text is translated
  • Optional button to toggle back to original language
  • Subtle blue styling; hidden if not translated
  • Accessible labels for screen readers

• Integration:

  • LanguageSwitcher added to Navbar
  • LanguageProvider wraps app in App.jsx
  • All components use Tailwind CSS + lucide-react icons
  • Built-in loading states and error handling

---

Multilingual Phase 6 (Report Pages Integration)

Phase 6 integrates multilingual and readability features into patient-facing report pages:

• Reports Page (client/src/pages/Reports.jsx):

  • Added language selector dropdown before generating adherence report
  • Passes selected language to backend report generation API
  • Uses Tailwind + lucide-react for styling
  • Report PDF generated in selected language

• ReportAnalysis Page (client/src/pages/ReportAnalysis.jsx):

  • Language selector: Choose report analysis language before uploading
  • Auto-translation: Automatically translates analysis to selected language after upload
  • Readability badge: Displays Flesch-Kincaid grade with color coding (green/yellow/red)
  • Translation badge: Shows "Originally English" with toggle to view/hide translation
  • Original/Translated toggle: Button to switch between original and translated text
  • Translation loading state: Shows spinner while translating
  • Persistent readability score: Stored and fetched from backend

• ReportChat Page (client/src/pages/ReportChat.jsx):

  • Language selector: Choose language for chat conversation (separate from UI language)
  • Auto-translate questions: User's questions are translated to English before sending to AI
  • Auto-translate replies: AI responses translated to user's selected language
  • Message language tag: Shows message language in chat history
  • Translation loading: "Translating question..." indicator
  • Graceful fallback: If translation fails, original text is used; conversation continues

• Features:

  • Client-side translation via language context (caches translations)
  • Readability scores displayed prominently with actionable suggestions
  • Seamless language switching without page reload
  • All UI feedback (loading, errors) integrated
  • Responsive design for mobile and desktop

---

Multilingual Phase 7 (Medication Instructions Translation)

Phase 7 brings multilingual support to medication instructions for improved patient safety:

• Backend Auto-Translation (server/src/api/addMedicineController.js):

  • Automatically translates pillDescription to Spanish (es) and Hindi (hi) when medication is added
  • Uses translationService.translateBatch() for efficient parallel translation
  • Stores original English in originalInstructions field
  • Stores translations in translatedInstructions object: { es: "...", hi: "..." }
  • Graceful fallback: If translation fails, original text stored for all languages
  • Medical context preserved via terminology dictionary

• Dashboard Display (client/src/pages/Dashboard.jsx):

  • Displays medication instructions in user's preferredLanguage automatically
  • Language toggle button: Switch between original English and translated version
  • Translation indicator: Shows "Translated from English" badge when viewing translations
  • Icon badges: Languages icon shows current language (EN/ES/HI)
  • Per-medication toggle state (can view different languages for different medications)
  • Seamless integration with existing medication cards

• Add Medication Preview (client/src/pages/addMedication.jsx):

  • Live translation preview: As user types instructions, see translations in real-time
  • Debounced translation: 1-second delay prevents excessive API calls
  • Multi-language preview grid: Shows Spanish and Hindi translations side-by-side
  • Loading indicators: "Translating..." state during translation
  • Info message: Clarifies translations are auto-saved with medication
  • Native language names displayed (Español, हिन्दी)

• API Response (server/src/api/todaysMedicineController.js):

  • Fetches user's preferredLanguage from User model
  • Returns displayInstructions field with appropriate translation
  • Includes userLanguage field in response for frontend toggle logic
  • Original and translations still available in response for toggle functionality
  • Falls back to English if translation not available

• User Experience:

  • Patient safety: Instructions always available in patient's primary language
  • Transparency: Easy toggle to verify original English instructions
  • Preview confidence: Users see translations before saving medication
  • Automatic workflow: No manual translation step required
  • Accessibility: Supports non-English-speaking users and caregivers

---

Multilingual Phase 8 (Settings & User Preferences)

Phase 8 implements a comprehensive settings page where users can configure language and readability preferences:

• Settings Page (client/src/pages/Settings.jsx):

  • Preferred Language Selector: Choose from English, Spanish, Hindi with native language names
  • Auto-translate Toggle: Automatically translate all AI responses and analysis
  • Show Readability Scores Toggle: Display/hide reading level badges on medical content
  • Target Reading Level Selector: Choose comfort level (All/College/HS/Middle/Elementary)
  • Reset to Defaults: Quick button to restore default settings
  • Save/Changed Indicator: Visual feedback for unsaved changes
  • Success/Error Messages: Clear feedback on save operations

• Language Settings Component (client/src/components/LanguageSettings.jsx):

  • Quick language switcher dropdown in Navbar
  • Shows current language with native name
  • Instant language switching without page reload
  • Auto-saves to backend and localStorage
  • Loading state during save

• Backend Preferences Controller (server/src/api/preferencesController.js):

  • GET /api/preferences: Fetch user's current settings
  • PUT /api/preferences: Update any/all preference fields
  • POST /api/preferences/reset: Reset to defaults
  • Validates all input (language codes, reading levels)
  • Auth-required endpoints (JWT middleware)

• User Model Extensions (server/src/models/User.js):

  • Added autoTranslateAll (Boolean, default: false)
  • Added showReadabilityScores (Boolean, default: true)
  • Added targetReadingLevel (Enum, default: "highschool")
  • Maintains backward compatibility with existing data

• Features:

  • Persistent Preferences: Settings sync across browser sessions
  • Cross-device Sync: User preferences stored in backend database
  • LocalStorage Fallback: Client-side caching for instant load
  • Real-time Updates: Changes apply immediately across app
  • Accessible UI: Keyboard navigation, clear labels, color-coded toggles
  • Responsive Design: Works on mobile, tablet, desktop

• User Experience:

  • Settings accessible from Navbar settings icon
  • Changes don't require page reload
  • Clear validation messages
  • Unsaved changes warning
  • Info card explaining each setting
  • Gradients and animations for engagement

---

Multilingual Phase 9 (Testing & Quality Assurance)

Phase 9 implements comprehensive testing coverage for all multilingual features ensuring reliability and performance:

• Backend Unit Tests (>85% coverage):

  • Translation Service (server/test/translation.test.js): EN→ES/HI translation, medical terminology preservation, caching (>85% hit rate), retry logic, batch operations, edge cases (empty, long text 10K+ chars, special chars), language detection
  • Readability Checker (server/test/readability.test.js): Flesch-Kincaid/Reading Ease scoring, multi-language support (EN/ES/HI), syllable counting, reading level classification, performance (<100ms standard, <500ms large texts)
  • Translation Controller (server/test/translationController.test.js): REST API endpoints, auth middleware, concurrent requests (10+), <500ms response, error handling

• Frontend Component Tests (>75% coverage):

  • LanguageSwitcher (client/src/components/__tests__/LanguageSwitcher.test.jsx): Dropdown interaction, API calls, localStorage persistence, keyboard accessibility, loading states, error fallback
  • ReadabilityIndicator (client/src/components/__tests__/ReadabilityIndicator.test.jsx): Color coding (green/yellow/red), score display, tooltips, ARIA labels, edge cases, <50ms render, memoization

• E2E Tests (100% critical paths):

  • client/src/__tests__/e2e/translation.spec.js: Language switching (settings + navbar), medication translation + toggle, report analysis in selected language, chat translation, persistence, keyboard navigation, mobile responsive (375px), performance (<500ms)

• Test Infrastructure:

  • Vitest (client/vitest.config.js): jsdom, 75% coverage thresholds, HTML/JSON reports
  • Playwright (client/playwright.config.js): Chrome/Firefox/Safari + mobile, screenshots on failure, CI/CD ready
  • Mocks (client/src/__tests__/setup.js): matchMedia, localStorage, IntersectionObserver

• Quality Metrics Achieved:

  • ✅ Backend: >85% coverage | ✅ Controllers: >80% | ✅ React: >75%
  • ✅ Translation: <500ms | ✅ Readability: <100ms | ✅ Cache hit: >85%
  • ✅ No memory leaks | ✅ WCAG 2.1 AA compliant

• Run Tests:

  # Backend
  cd server && npm test && npm run test:coverage
  # Frontend
  cd client && npm test && npm run test:coverage
  # E2E
  cd client && npm run test:e2e

---

🤝 How to contribute

1. Pick an issue: Start with “good first issue” or “help wanted,” or open a discussion if unsure.
2. Discuss: Comment to get assigned/confirm approach.
3. Fork & branch: git checkout -b feature/your-feature
4. Code & test: Add/adjust tests if applicable.
5. Lint/format: Match project conventions (React/Tailwind/Node).
6. PR: Submit with a clear description, screenshots (for UI), and testing notes.

Need ideas?

• Improve docs and onboarding.
• Add frontend tests (e.g., components/contexts) or backend tests (routes/controllers/utils).
• Enhance error handling, validations, or UX polish.
• Expand AI prompts/agents or add safety/guardrails.
• Improve accessibility or responsiveness.
• Add CI checks or Docker dev setup.

---

🧭 Project flow (conceptual)

1. Auth -> JWT -> protected routes.
2. Dashboard fetches schedule/adherence via API.
3. Medication CRUD updates MongoDB.
4. Scheduler + Socket.IO deliver reminders.
5. AI routes call LangChain handlers for health Q&A.
6. Reports are parsed and analyzed; chat endpoint uses the analyzed context.
7. Optional calendar sync pushes schedules to Google Calendar.

---

🎉 Social Winter of Code (SWOC) - Thank You!

We are incredibly proud to announce that the Social Winter of Code phase for MedSync AI has officially concluded!

A massive THANK YOU to every single contributor who participated. Because of your hard work, late-night commits, and brilliant ideas, MedSync AI transformed from a baseline concept into a feature-rich, multilingual, offline-capable application. You tackled complex issues like integrating AI agents, building the Flesch-Kincaid readability checkers, designing the multilingual schemas, and setting up real-time WebSockets.

You have all made a real impact in building an open-source tool that can genuinely help improve global medication adherence. We couldn't have done it without you! 🚀

---

💖 Contributors

To all the amazing developers, designers, and testers who have spent their time improving MedSync AI—this section is dedicated to you. Thank you for your code, your bug reports, and your enthusiasm!

(Want to see your face here? Check out our CONTRIBUTING.md guidelines and grab an open issue!)

---

📜 License

Open-source. See LICENSE for details.

---

📣 Community & support

• Open an issue or discussion with questions or proposals.
• PRs welcome—please keep them focused and well-described.
• For security issues, privately disclose first; do not file public issues containing secrets.