NFC MediCard

A secure clinical data portal built to accompany the NFC MediCard FYP report. Three role-based portals (Patient, Doctor, Admin) built on:

• Frontend: React (Vite) + Tailwind CSS + React Router + Recharts, with dark mode, a mobile-responsive nav drawer, toast notifications, and PDF record export.
• Backend: Node.js + Express + Supabase (service role client)
• Data/Auth/Storage: Supabase — Postgres database, Supabase Auth, and Supabase Storage. Fully hosted, so there's nothing to run locally besides your own Node processes (no Java, no emulators).
• NFC scanning: real hardware support via the Web NFC API on Android Chrome (tap a physical card, no app install needed), with a QR code fallback (any phone camera) for iOS/desktop, and manual Card UID entry as a last resort. All three paths hit the same backend lookup.
• Testing/CI: Vitest + Supertest backend test suite, run automatically on every push via GitHub Actions (.github/workflows/ci.yml).
• Mobile: the same web app packages into a native Android app via Capacitor — see Packaging as an Android app below. iOS isn't supported from this setup (requires a Mac + Xcode).

Demo videos

Video	What it shows
Overview (1:30)	What NFC MediCard is and how it works, in one compilation
Patient demo (1:32)	A patient's journey: card registration, check-in, the doctor's tap, and the patient app
Doctor walkthrough (1:18)	Dashboard, appointments, admissions and discharge, medication renewals, labs and imaging, referrals, and the tablet + USB reader
Admin walkthrough (1:12)	Hospital dashboard, adding patients and assigning cards, check-in queue and rooms, doctor accounts, data entry, reports, and the audit log

Prerequisites

• Node.js 18+
• A free Supabase project

1. Set up the Supabase project

1. Create a project at supabase.com (or use an existing one).
2. Open the SQL Editor, paste the contents of supabase/schema.sql, and run it. This creates all the tables (profiles, patients, doctors, medical_history, lab_results, radiology, messages, appointments, vitals, audit_log) with Row Level Security enabled and no client-facing policies — all access goes through the backend's service-role key.
   • Already ran an older version of this schema? Just run supabase/migration_002_audit_and_unread.sql instead to pick up the new audit_log table and the messages.read column.
3. Go to Settings → API and copy three values: the Project URL, the anon / public key, and the service_role key (keep this one secret — it's never used in the frontend).
4. Under Authentication → Providers, make sure Email sign-in is enabled (it is by default).
5. Under Authentication → Settings, make sure "Confirm email" is turned ON. Patients and doctors registered through the app (admin/doctor "Add Patient", "Register New Card") are created unconfirmed and sent a real verification email — they can't log in until they click it. Demo accounts from npm run seed are still pre-confirmed regardless of this setting, so seeding and local testing aren't affected either way.
   • Supabase's built-in email sending is rate-limited on the free tier (a handful of emails per hour) and may land in spam. If a real email doesn't arrive, you can manually confirm a user from Authentication → Users → select the user → "Confirm email" as a fallback.

Storage buckets (lab-results, radiology) are created automatically the first time the backend starts — no manual setup needed.

2. Configure environment variables

cd server && cp .env.example .env

Edit server/.env and fill in SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.

cd ../client && cp .env.example .env

Edit client/.env and fill in VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY (the anon key, not the service role key).

3. Install dependencies

cd server && npm install
cd ../client && npm install

4. Seed demo data

From /server, with your .env filled in:

npm run seed

This creates demo accounts and sample clinical data directly in your Supabase project. Demo logins (password for all: password123):

Role	Email	Notes
Admin	[email protected]
Doctor	[email protected]	Dr. Sarah Jenkins — Cardiology
Doctor	[email protected]	Dr. Robert Chan — Endocrinology
Patient	[email protected]	Card UID: 0443FADB3D0289
Patient	[email protected]	Card UID: 07D8E9F0

5. Run the app (2 terminals)

Terminal 1 — Backend (from /server):

npm run dev

Runs on http://localhost:4001.

Terminal 2 — Frontend (from /client):

npm run dev

Runs on http://localhost:5173. Log in with any of the demo accounts above.

Trying the NFC flow

• On Android Chrome (real hardware): the Doctor "Scan NFC Card" and Admin "Register New Card" pages detect Web NFC support automatically and show a "Tap NFC Card" button — tap a real card and it looks the patient up (or starts registration) by the card's actual hardware UID.
• Everywhere else (desktop, iOS): falls back to manual entry —
  • Doctor → Scan NFC Card: enter 0443FADB3D0289 to pull up the seeded patient's full record.
  • Admin → Register New Card: enter any new UID (e.g. AABBCCDD) to register a brand-new patient and bind it to that "card".
• Admin/Doctor → Add Patient / Register Patient: register a patient with no card at all — a card can be issued to them later.

Feature tour

• Dark mode — toggle in the sidebar (🌙/☀️), persisted per-browser.
• Mobile nav — hamburger-triggered drawer with backdrop on small screens.
• PDF export — "Export PDF" button on the Doctor's patient detail page and the Patient's own Profile page, generates a full record summary client-side (jspdf).
• Audit log — Admin → Audit Log shows who did what (registrations, NFC scans/registrations, record/lab/imaging additions) and when.
• Unread message badge — Patient nav shows an unread count for messages from doctors, auto-clears when the Messages page is opened.
• Doctor dashboard chart — weekly record-logging activity, backed by /api/doctor/stats.
• Search/filter — on Medical History, Lab Results, and Imaging (patient + doctor views).
• Appointment calendar — Patient and Doctor both have an "Appointments" page with a month-view calendar; appointments are created from a doctor's "Update Record" form.
• QR code fallback — Admin's card registration screen generates a printable QR code for the physical card; Doctor's scan page can read it back with the device camera.
• Email verification — patients/doctors registered through the app must confirm their email before they can log in (seeded demo accounts are exempt for convenience).
• Forgot / reset password — password reset by email from the login page.
• Registration desk — Admin scans a card at check-in and hands the patient a queue number and room, shown in a "Today's Queue" list, without opening their full record.
• Assign a card to an existing account — for patients added without a card; their login and records are kept.
• Admissions — doctors admit a patient to a ward/room and discharge them later; history is grouped by admission.
• Medication renewal cycles — prescriptions can renew weekly or monthly; expired ones are flagged "Needs renewal" with a one-click Renew.
• Lab and imaging details — lab results can be flagged abnormal; imaging covers X-ray, MRI, CT scan, and wound-care photos.
• Referrals — a record update can be sent to another doctor/department with photos attached.
• My QR Code — patients can show their card's QR code from the portal if they forget the card.
• USB desk reader — the Android app supports a USB NFC desk reader (e.g. on a tablet).

Running tests

From /server:

npm test

Runs the Vitest + Supertest suite (auth middleware, patient CRUD, NFC lookup) against a mocked Supabase client — no real database or network access needed. The same command runs automatically on every push/PR via GitHub Actions.

Project structure

nfc-medicard/
├── .github/workflows/ci.yml              # Runs backend tests + frontend build on push/PR
├── docs/videos/                          # Overview, patient demo, doctor and admin walkthroughs
├── supabase/
│   ├── schema.sql                        # Full schema + RLS (fresh setup)
│   └── migration_002_audit_and_unread.sql # Incremental migration (existing projects)
├── server/                  # Express API (Supabase service-role client)
│   ├── test/                # Vitest + Supertest suite, mocked Supabase client
│   └── src/
│       ├── routes/          # patients, medical-history, lab-results, radiology,
│       │                    # messages, nfc, appointments, admin, doctor, audit, users
│       ├── middleware/auth.js   # verifies Supabase JWTs
│       ├── lib/              # supabase client, storage upload helper, audit log helper
│       └── seed.js
└── client/                  # React app
    └── src/
        ├── pages/{patient,doctor,admin}/
        ├── components/{MonthCalendar,QrCodeCard,QrScannerView}.jsx
        ├── context/{AuthContext,ThemeContext,ToastContext,UnreadContext}.jsx
        └── lib/{supabase.js,api.js,webNfc.js,exportPdf.js}

Security model

All data access goes through the Express backend, which uses the Supabase service role key (bypasses Row Level Security). The frontend only ever holds the anon key, used solely for Supabase Auth (sign-in), and calls the backend with the resulting access token in the Authorization: Bearer <token> header. The backend's own middleware (requireAuth / requireRole) enforces who can see and modify what. Key mutating actions (registrations, NFC scans, record/lab/imaging additions) are recorded to audit_log for accountability.

Deploying the app online (Vercel + Render)

This deploys the frontend to Vercel (free) and the backend to Render (free tier), both connected to a GitHub repo so every push auto-deploys.

0. Push this project to GitHub

git init   # if not already a repo
git add .
git commit -m "Initial commit"

Create a new empty repository on github.com/new, then:

git remote add origin <your-repo-url>
git branch -M main
git push -u origin main

1. Deploy the backend to Render

1. Go to render.com → New → Web Service → connect this repo.
2. Set Root Directory to server.
3. Build command npm install, start command npm start (or let Render auto-detect from package.json).
4. Under Environment, add:
   • SUPABASE_URL
   • SUPABASE_SERVICE_ROLE_KEY
   • CLIENT_ORIGIN — set this after step 2 below, to your Vercel URL (comma-separate if you add more origins later, e.g. https://app.vercel.app,https://yourdomain.com)
   • Render sets PORT automatically — no need to add it.
5. Deploy. Render's free tier sleeps after ~15 minutes of inactivity and takes a few seconds to wake back up on the next request. Once live, copy the generated https://<something>.onrender.com URL — that's your VITE_API_URL base for the frontend (append /api).

2. Deploy the frontend to Vercel

1. Go to vercel.com → Add New Project → import the same GitHub repo.
2. Set Root Directory to client.
3. Framework preset should auto-detect as Vite. Build command npm run build, output dist (defaults are correct).
4. Under Environment Variables, add:
   • VITE_SUPABASE_URL
   • VITE_SUPABASE_ANON_KEY
   • VITE_API_URL — https://<your-render-app>.onrender.com/api
5. Deploy. Copy the resulting https://<something>.vercel.app URL.

3. Close the loop

Go back to Render and set CLIENT_ORIGIN to the Vercel URL from step 2 (this is what CORS checks against), then redeploy the backend service so the change takes effect.

Your site is now live at the Vercel URL — share that with anyone to let them use the app.

Packaging as an Android app (Capacitor)

The same React codebase can be wrapped into a native Android app with Capacitor — no rewrite, no separate mobile codebase. The website keeps working exactly as before; this just adds an installable .apk on top. (iOS isn't covered here — building an iOS app requires Xcode, which only runs on macOS.)

Already set up in this repo:

• client/capacitor.config.json — app id com.medicard.nfc, web dir dist.
• client/.env.production — overrides VITE_API_URL to point at the deployed Render backend (instead of localhost) whenever npm run build runs, so the packaged app talks to production.
• client/android/ — the generated native Android project (gitignored: .gradle/, build/, local.properties, and any local JDK under .tools/).

Prerequisites

• Android Studio (bundles its own JDK and Android SDK — use this rather than a bare command-line JDK/Gradle setup, which is version-sensitive).

Build the APK

cd client
npm run build        # bundles the app with the production API URL baked in
npx cap sync android  # copies the fresh web build into the native project

Then open the client/android folder in Android Studio, let Gradle sync, and go to Build → Build Bundle(s) / APK(s) → Build APK(s). The resulting .apk can be sideloaded directly onto any Android device — no Play Store submission needed.

CORS note

Capacitor's Android WebView serves the app from the origin https://localhost. Add that to the backend's CLIENT_ORIGIN environment variable on Render (comma-separated alongside the Vercel URL) so the packaged app's API calls aren't rejected by CORS:

https://nfc-medicard-5y8u.vercel.app,https://localhost

Offline demo mode (presentation backup)

For presenting somewhere with unreliable or no internet, there's a fully self-contained offline build — no Supabase, no Render, no Vercel, nothing outside your own laptop:

cd client && npm run build:offline   # builds client/dist-offline against a local API
cd ../server && npm run offline      # serves the app + a canned in-memory dataset on one port

Open http://localhost:4444 — same demo accounts as above ([email protected], [email protected], [email protected] / password123, card UID 0443FADB3D0289). You can disconnect Wi-Fi entirely and it keeps working: server/offline-server.js is a single Express process serving both the built frontend and an in-memory stand-in for the API, seeded with the same demo data as npm run seed. It's for a local demo only — the auth "token" it issues has no real security, so never deploy this file or expose it beyond your own machine.

Known limitations / next steps

• Web NFC scanning only works on Android Chrome/Edge over HTTPS (or localhost) — iOS and desktop browsers automatically use the manual UID fallback, which is the same code path either way.
• Storage buckets are created public for simplicity (matches the original demo behavior). For a real deployment with sensitive clinical files, switch to private buckets and generate short-lived signed URLs per request instead (supabase.storage.from(bucket).createSignedUrl()).
• The automated tests cover the backend (mocked Supabase); the frontend is verified by manual end-to-end testing.