medminder/README.md

MedMinder

A progressive web app (PWA) for tracking daily medication schedules and receiving push notification reminders.

Features

• Passwordless login via magic link (email)
• Add, edit, and delete medications with dosage, frequency, and reminder times
• Daily dashboard showing today's scheduled doses, with confirmation to mark as taken
• Push notifications at scheduled times (requires Firebase + Appwrite Messaging setup)
• Dark/light theme
• Installable as a PWA on Android and iOS

Tech stack

Layer	Technology
Frontend	React 19 + Vite, TypeScript
UI	shadcn/ui + Tailwind CSS v4
Backend / Auth / Database	Appwrite
Push notifications	Appwrite Messaging + Firebase FCM
PWA	vite-plugin-pwa (Workbox)

Services

Appwrite

Appwrite handles three things in this project:

• Auth — passwordless magic link login. The user enters their email, receives a link, and clicks it to get a real session. No passwords stored.
• Database — two collections: medications (name, dosage, frequency, reminder times, timezone) and logs (a record each time a dose is confirmed as taken). Row-level security ensures users can only access their own records.
• Messaging — sends push notifications to registered devices via FCM. The send-reminders function calls the Appwrite Messaging API to dispatch notifications at the right time.

Firebase (FCM)

Firebase Cloud Messaging (FCM) is the delivery layer for push notifications. Appwrite Messaging uses FCM as a provider to actually route notifications to the browser or device. Firebase itself is not used for auth or storage — only for push delivery.

A Firebase project is required to:

• Generate a VAPID key (used by the browser to subscribe to push)
• Authenticate Appwrite Messaging via a service account JSON

Getting started

1. Clone and install

git clone <repo>
cd medminder
npm install

2. Configure environment variables

Copy .env.example to .env and fill in all values:

cp .env.example .env

Appwrite variables

Variable	Description
VITE_APPWRITE_ENDPOINT	Your Appwrite endpoint (e.g. https://cloud.appwrite.io/v1)
VITE_APPWRITE_PROJECT_ID	Your Appwrite project ID
VITE_APPWRITE_DATABASE_ID	Your Appwrite database ID
VITE_APPWRITE_MEDICATIONS_COLLECTION_ID	Collection ID for medications
VITE_APPWRITE_LOGS_COLLECTION_ID	Collection ID for dose logs
VITE_APPWRITE_FCM_PROVIDER_ID	FCM provider ID from Appwrite Messaging → Providers

Firebase variables

Variable	Description
VITE_FIREBASE_API_KEY	From Firebase project settings
VITE_FIREBASE_AUTH_DOMAIN	From Firebase project settings
VITE_FIREBASE_PROJECT_ID	From Firebase project settings
VITE_FIREBASE_STORAGE_BUCKET	From Firebase project settings
VITE_FIREBASE_MESSAGING_SENDER_ID	From Firebase project settings
VITE_FIREBASE_APP_ID	From Firebase project settings
VITE_FIREBASE_VAPID_KEY	From Firebase → Project Settings → Cloud Messaging → Web Push certificates

3. Set up Appwrite

1. Create a project and database in Appwrite Console
2. Create two collections with Row security enabled:

medications — attributes: name (string), dosage (string), frequency (string), times (string[]), startDate (string), durationDays (integer, optional), timezone (string), userId (string)

logs — attributes: medicationId (string), userId (string), takenAt (string), scheduledDate (string), scheduledTime (string, optional)

3. On both collections set collection-level permissions: Create: Users, Read: Users

4. Deploy the reminder function

The functions/send-reminders directory contains an Appwrite Function that runs every minute and sends push notifications for due medications.

# Pack it
tar -czf send-reminders.tar.gz -C functions/send-reminders .

Deploy in Appwrite Console → Functions → Create → Node.js 18 → upload the tar.gz → set cron to * * * * * → add the environment variables listed in .env.example under the function section.

5. Run locally

npm run dev

Project structure

src/
├── components/
│   ├── layout/       # AppLayout, BottomNav
│   └── ui/           # shadcn/ui components
├── hooks/            # useAuth
├── lib/
│   ├── appwrite.ts   # Appwrite client
│   ├── auth.ts       # Magic link helpers
│   ├── medications.ts # Database queries + types
│   └── notifications.ts # FCM token registration
├── pages/            # Dashboard, Medications, Settings, Login, AuthCallback
└── sw.ts             # Service worker (Workbox + FCM push handler)
functions/
└── send-reminders/   # Appwrite Function — cron-based push dispatcher