Full Stack Architecture Documentation

1. Overview

CareTrack is a staff-only medical records management system for clinics. The public page explains the product and sends authorized staff to the login flow. The protected admin dashboard handles staff directory management, patient registration, diagnosis tracking, schedules, reports, notifications, profile images, and role-based access.

2. System Map

3. Runtime Topologies

Local and VPS runtime

The app can run through the custom Express server with npm run dev or npm start. The server prepares a Next app, applies compression, adds security headers, serves static assets, exposes health/API endpoints, and passes all remaining requests to Next.

Browser -> Express server.js -> Next request handler -> app/ routes
Browser -> /api/* -> Express API middleware -> JSON response or 404
Browser -> Firebase SDK -> Auth / RTDB / Storage / callable Functions

Vercel runtime

vercel.json declares the project as a Next.js app using npm run build. Next route handlers serve /api/health, /robots.txt, /sitemap.xml, and /sw.js when deployed as a standard Next app.

Firebase Functions runtime

Cloud Functions are exported from functions/src/server.js, which sets maxInstances: 10 and exports callable functions from functions/src/app/next.js. These functions use the Firebase Admin SDK for Auth user and custom-claim operations.

4. Frontend Routes

Next.js routes

Admin SPA page keys

Static compatibility pages

The admin/*.html and auth/index.html files load shared scripts from public/assets/js/. They are still precached by sw.js and tested by Playwright, but the Next React app is the newer route surface.

5. Auth and Access

CareTrack uses Firebase Authentication for staff accounts. A Firebase Auth account alone is not enough: the login flow also requires a matching Realtime Database registration record and an active status. Custom claims then drive frontend navigation and security rules.

Login flow

1. Staff submits email/password on /auth.
2. Client signs in using signInWithEmailAndPassword.
3. Client searches RTDB registration paths for the signed-in UID.
4. If no registration exists, or the registration is disabled, the client signs out.
5. Client writes lastLoginAt and lastLoginEmail when allowed.
6. Client calls syncOwnAccessClaims to mirror registration into Firebase Auth custom claims.
7. Client refreshes the ID token and redirects to the requested admin route.

Custom claim schema

Role purpose

Registration lookup paths

registration/admin/{uid}
registration/doctors/{uid}
registration/receptionist/{uid}
registration/clinicks/doctor/{uid}
registration/clinicks/reception/{uid}
access/users/{uid}      # client-side legacy lookup only

6. API Catalogue

HTTP endpoints

Firebase callable functions

These are called with httpsCallable(functions, name). They are not REST routes. All privileged functions rely on Firebase Auth context and the Admin SDK.

API CORS allowlist

Express API CORS allows credentials for origins from API_ALLOWED_ORIGINS or the defaults: https://caretrack.website, https://www.caretrack.website, https://project-xbo8a.vercel.app, http://localhost:3000, and http://localhost:4173.

7. Data Schemas

7.1 Firebase Auth user schema

7.2 Realtime Database schemas

The React admin app uses root-level RTDB collections plus a clinicId field for filtering. Doctor records are stored under registration paths, while patient/diagnosis/schedule/notification/report/settings records are root collections.

7.3 Firestore schemas

Firestore rules define a clinic-scoped document tree under clinics/{clinic}. The static admin script uses this shape via helpers like collection(db, "clinics", state.clinicId, name).

7.4 Firestore composite indexes

7.5 Firebase Storage schemas

8. Data Workflows

Staff creation

1. Admin opens staff or doctor form.
2. Client calls createStaffUser with email, display name, temporary password, staff type, department, active flag, and clinic ID.
3. Function creates/updates Firebase Auth user and removes older registration paths for that UID.
4. Function writes the normalized registration under the correct path and mirrors custom claims.
5. For doctors, the frontend then writes profile fields into registration/doctors/{uid}.

Patient registration

1. Staff chooses or generates a patient record key and public patient ID.
2. Optional profile image uploads to clinics/{clinicId}/patients/{patientId}/profile.{ext}.
3. Frontend writes patients/{patientRecordId} with assignment, demographics, image URL/path, clinic ID, and lifecycle metadata.
4. If assigned doctor changed, frontend writes a patient assignment notification under notifications/{patientId}_{doctorId}_assignment.

Diagnosis creation

1. Admin or assigned doctor opens diagnosis form.
2. Client validates that the doctor can diagnose the selected patient.
3. Client writes a diagnosis record under diagnoses/{diagnosisId}.
4. Client updates the patient summary fields lastDiagnosis, status, updatedAt, and updatedBy.

Notification handling

Doctors see notifications targeted to their UID. The app also derives assignment notifications from patient records if no explicit notification exists. Marking a notification as read updates or creates read: true and readAt.

Reports

The React reports page filters and renders diagnosis records as report rows. Static pages can create Firestore report metadata and render a printable patient diagnosis report.

9. Security Model

Frontend access checks

The admin app checks Firebase Auth state, registration status, custom claims, and per-page role lists. Unauthorized users are redirected to /auth or shown the access-denied page.

Firestore rules summary

Realtime Database rules summary

Storage rules summary

Storage requires active staff claims and same-clinic matching. Patient files are writable by admins, doctors, and receptionists. Doctor files are writable only by admins. Report files are readable/writable by admins and doctors.

Server security headers

Both server.js and next.config.js define security headers including X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy, and a Content Security Policy allowing Firebase, Google APIs, app assets, and Storage image sources.

10. Offline Runtime

CareTrack includes a service worker and runtime script to improve perceived reliability and provide visible connection status.

The service worker ignores non-GET requests and lets Firebase hosts pass through to the network. It only caches same-origin assets and app shell pages.

11. Build and Deployment

NPM scripts

Deployment targets

Firebase configuration

projectId: caretrack-badc5
databaseURL: https://caretrack-badc5-default-rtdb.firebaseio.com
storageBucket: caretrack-badc5.firebasestorage.app
defaultClinicId: default

12. Testing

Playwright tests in tests/e2e/caretrack.spec.js validate core shell/runtime behavior:

• Static assets and sw.js are served.
• Public page shows the real logo and registers the service worker.
• Health checks are driven through the service worker.
• Connectivity overlay appears/disappears when the browser context goes offline/online.
• Auth page loads without the old loader path.
• Protected static admin pages redirect unauthenticated staff to login.
• Access denied page renders without requiring a session.

Run with npm run test:e2e after starting the app according to playwright.config.js.

13. Architecture Notes

14. Source File Map