README.md

metadata

title: Medisync
emoji: 🏆
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: apache-2.0

AI-Powered Medicine Dispenser System · Backend

Backend-for-frontend that powers authentication, AI-assisted medicine management, reminders, analytics, payments, and admin tooling for the MediSync platform. It is built with FastAPI and MongoDB, orchestrates background reminder workers, and integrates with OpenAI, SerpAPI, Twilio, Gmail, and Stripe.

---

Highlights

• Full CRUD for medicines, reminders, adherence analytics, and dashboard metrics (routers/medicine.py, routers/dashboard.py, routers/analysis.py).
• AI co-pilot that reads prescriptions/images/audio, persists chat sessions, and can auto-create medicines via LangGraph tools (routers/ai_agent.py, ai_agent.py).
• Secure auth with JWT, Google OAuth tokens, trial handling, and admin login utilities (routers/auth.py, utils/auth_utils.py).
• Communication layer for email + SMS notifications such as verifications, reminders, and preorder confirmations (utils/email_utils.py, utils/sms_utils.py).
• Monetization hooks for Stripe checkout sessions and subscription lifecycle updates (routers/subscription.py).
• Background workers that continuously schedule reminders and mark missed doses at startup.

app = FastAPI(...)
app.include_router(auth.router)
app.include_router(user.router)
app.include_router(dashboard.router)
app.include_router(medicine.router)
app.include_router(session.router)
app.include_router(analysis.router)
app.include_router(ai_agent.router)
app.include_router(preorder.router)
app.include_router(admin.router)
app.include_router(contact.router)
app.include_router(subscription.router)

---

Tech Stack

• FastAPI + Uvicorn (REST APIs, startup workers, static file serving)
• MongoDB via Motor/PyMongo (async + sync access patterns)
• LangChain / LangGraph / OpenAI GPT-4o-mini (AI agent + tooling)
• Stripe SDK (subscription checkout + webhook-less reconciliation)
• Twilio + SMTP (SMS/Email comms)
• JWT Auth (python-jose, bcrypt), Pydantic models, python-dotenv configuration

---

Project Structure

• main.py – FastAPI application factory, middleware, router registration, reminder workers.
• db.py – Mongo connection helper exposed via dependency injection.
• models/ – Pydantic schemas and helper persistence methods (user.py, medicine.py, etc.).
• routers/ – Route handlers grouped by domain (auth, medicine, analysis, ai_agent, subscription, ...).
• utils/ – Cross-cutting helpers (auth, email/SMS templates, GPT integrations, reminders, URL helpers).
• Cloudinary – Dynamic storage for user-provided audio/image assets (replaces local /uploads).

---

Getting Started

1. Prerequisites

   • Python 3.11+
   • MongoDB 5+ (local or hosted)
   • OpenAI + SerpAPI + Twilio + Gmail + Stripe accounts (for full functionality)

2. Install dependencies

   cd Backend
   python -m venv .venv && .venv\Scripts\activate  # Windows (use `source .venv/bin/activate` on macOS/Linux)
   pip install -U fastapi uvicorn[standard] motor pymongo python-dotenv python-multipart \
       "python-jose[cryptography]" bcrypt pillow twilio stripe openai serpapi langchain langgraph \
       speechrecognition gTTS requests
   

   Maintain a requirements.txt with the packages above for reproducible installs.

3. Configure environment

   • Copy .env.example (create one if needed) to .env and fill the variables from the table below.

4. Run the API

   uvicorn main:app --reload --host 0.0.0.0 --port 8000
   

   Startup automatically mounts /uploads, enables CORS+GZip, and kicks off reminder workers.

---

Environment Variables

Name	Required	Description
MONGODB_URI, DB_NAME	✅	Connection info for MongoDB (db.py, ai_agent.py).
JWT_SECRET	✅	Symmetric signing key for access tokens (utils/auth_utils.py).
FRONTEND_URL, BACKEND_URL	➖	Overrides used when building links for emails & redirects (utils/url_utils.py).
GMAIL_USER, GMAIL_PASS	✅ (email)	SMTP credentials for verification, reminders, preorder emails (utils/email_utils.py).
TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_NUMBER	✅ (SMS)	Used for SMS alerts (utils/sms_utils.py).
OPENAI_API_KEY	✅ (AI)	Required for chat, extraction, and health advisor tools (ai_agent.py, routers/medicine.py).
SERPAPI_API_KEY	✅ (AI search)	Enables medicine pricing and pharmacy lookup tools (ai_agent.py).
STRIPE_SECRET_KEY	✅ (billing)	Needed for subscription checkout + updates (routers/subscription.py).
GOOGLE_CLIENT_ID	➖	Validates Google OAuth tokens for auth flows (routers/auth.py).
AWS_CONTAINER_URL, ECS_CONTAINER_METADATA_URI_V4, WEBSITE_HOSTNAME, AZURE_CONTAINER_URL, PUBLIC_URL, BASE_URL, APP_URL	Optional	Auto-detection hooks for hosted frontend URLs (utils/url_utils.py).

Tip: Keep secrets out of source control and mirror them in your deployment provider’s secret manager.

---

API Surface (Summary)

Router	Purpose	Key Endpoints
auth	Local + Google auth, verification, password utilities	/auth/register, /auth/login, /auth/google/*, /auth/verify
user	Profile + account maintenance	/user/me, /user/me/update, /user/update-phone, /user/me/delete, /user/forgot-password
dashboard	Slot utilization + medicine snapshots	/dashboard/slots, /dashboard/available-medicine, /dashboard/today-medicine, /dashboard/upcoming-medicines
medicine	CRUD, AI extraction, reminders, adherence tracking	/medicine/add, /medicine/all, /medicine/{id}/update, /medicine/{id}/take, /medicine/reminders, /medicine/extract-details
session	Lightweight chat history separate from AI agent	/session/create, /session/all, /session/{id}/chat
ai-agent	Unified chat/image/audio endpoints + session mgmt	/ai-agent/send-image-chat, /ai-agent/send-audio, /ai-agent/session/{id} (GET/PUT/DELETE)
analysis	Reports + adherence summaries	/analysis/medicine-summary, /analysis/report/csv, /analysis/report/pdf
preorder	Store hardware preorder submissions w/ notifications	POST /preorder
contact	General contact form intake	POST /contact
subscription	Stripe checkout + entitlement updates	/subscription/create-checkout-session, /subscription/update-subscription, /subscription/cancel
admin	Simple password-gated admin dashboard	/admin/login, /admin/dashboard, /admin/preorder/{id}

See the corresponding routers/*.py file for request/response schemas implemented with Pydantic models under models/.

---

Background Jobs & Notifications

• utils.reminders.reminder_worker & mark_missed_doses_worker run immediately after startup to send reminders and flag missed doses.
• utils.email_utils contains high-fidelity HTML templates for account lifecycle, medicines, reminders, misses, password resets, preorder confirmations, and payment receipts.
• utils.sms_utils mirrors key events over SMS (verification codes, reminder nudges, preorder confirmations).
• utils.gpt_utils, utils.drug_db_utils, and ai_agent.py centralize OpenAI + SerpAPI powered reasoning, extraction, and knowledge lookups used across routers.

---

Testing the API

• Swagger UI: Visit http://localhost:8000/docs for interactive testing.
• Postman / Thunder Client: Set {{baseUrl}} = http://localhost:8000, authenticate via /auth/login, and reuse Authorization: Bearer <token> headers.
• File uploads: Use multipart/form-data (e.g., /medicine/add, /ai-agent/send-audio). Uploaded assets are persisted under /uploads and exposed via StaticFiles.
• Next.js proxy routes: The frontend contains /app/api/ai_agent/* handlers that proxy directly to these endpoints—handy when diagnosing CORS issues.

---

Troubleshooting

• 401 errors – Ensure Authorization headers use the latest JWT issued by /auth/login. Tokens expire daily by default.
• Email/SMS not sending – Double-check SMTP/Twilio credentials and enable app passwords for Gmail if 2FA is enforced.
• AI extraction issues – Verify OPENAI_API_KEY/SERPAPI_API_KEY rate limits and inspect worker logs for LangGraph tool errors.
• Reminder jobs – They run in-process; if you deploy multiple replicas, ensure only one instance executes the reminder workers or extract them into a dedicated worker pod/queue.
• Stripe checkout – /subscription/create-checkout-session expects PKR pricing data; confirm the amount posted from the frontend matches Stripe’s expectations (smallest currency unit).

Happy building! 🎯