---
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.

```18:44:Backend/main.py
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**
   ```bash
   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**
   ```bash
   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! 🎯