# geo211/researcha architecture

> Architecture diagram of the GitHub repository geo211/researcha, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geo211/researcha
- Repository: https://github.com/geo211/researcha

## Overview

CareLink is a role-based health referral system. Staff manage patients, referrals and queues; patients and the public can follow care status, while staff have dashboard and analytics views. The main path runs from the React client through the Express API to Supabase-backed persistence, with referral and queue actions able to trigger SMS. The graph includes documented AI insights, administration and offline support; their detailed implementations or wiring are not fully shown in the excerpts, so uncertain connections are omitted.

Main entry points: [`server/src/app.js`](https://github.com/geo211/researcha/blob/main/server/src/app.js) (API application), [`client/src/App.jsx`](https://github.com/geo211/researcha/blob/main/client/src/App.jsx) (CareLink app), [`server/src/lib/supabase/store.js`](https://github.com/geo211/researcha/blob/main/server/src/lib/supabase/store.js) (Supabase data store), [`server/src/services/smsService.js`](https://github.com/geo211/researcha/blob/main/server/src/services/smsService.js) (SMS notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["CareLink app<br/>[App.jsx]"]
  node_clientapi["API and offline client<br/>[api.js]"]
  node_offline["Offline queue and cache<br/>[offline.js]"]
  node_patientviews["Patient management<br/>[Patients.jsx]"]
  node_referralviews["Referral management<br/>[Referrals.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_analytics["Analytics<br/>[Analytics.jsx]"]
  node_tracking["Public tracking"]
end

subgraph group_api["API workflows"]
  node_spa["API application<br/>[app.js]"]
  node_auth["Authentication and RBAC<br/>[auth.js]"]
  node_patients["Patient records<br/>[patientRoutes.js]"]
  node_referrals["Referral workflow<br/>[referralRoutes.js]"]
  node_queue["Queue management<br/>[queueRoutes.js]"]
  node_adminroutes["Admin and settings<br/>[userRoutes.js]"]
  node_publicroutes["Public endpoints<br/>[publicRoutes.js]"]
  node_analyticsroutes["Analytics endpoints<br/>[analyticsRoutes.js]"]
  node_aienpoints["AI insights endpoint<br/>[aiRoutes.js]"]
end

subgraph group_services["Domain services"]
  node_insights["AI insights<br/>[insights.py]"]
  node_audit["Audit logging<br/>[auditService.js]"]
  node_sms["SMS notifications<br/>[smsService.js]"]
  node_rbac["Role permissions<br/>[rbac.js]"]
end

subgraph group_persistence["Data and access"]
  node_store[("Supabase data store<br/>[store.js]")]
  node_query["SQL query layer<br/>[query.js]"]
  node_dbconfig["Database connection<br/>[db.js]"]
end

node_staff(("Staff user"))
node_patient(("Patient user"))
node_public(("Public visitor"))
node_unisms["UniSMS API"]
node_supabase[("Supabase PostgreSQL")]

node_staff -->|"uses"| node_app
node_patient -->|"uses"| node_app
node_public -.->|"opens tracking"| node_app
node_app -->|"requests data"| node_clientapi
node_app -->|"renders"| node_patientviews
node_app -->|"renders"| node_referralviews
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_analytics
node_app -.->|"renders"| node_tracking
node_clientapi -->|"caches and queues"| node_offline
node_clientapi -.->|"sends API requests"| node_spa
node_spa -->|"routes requests"| node_patients
node_spa -->|"routes requests"| node_referrals
node_spa -->|"routes requests"| node_queue
node_spa -->|"routes requests"| node_adminroutes
node_spa -->|"routes requests"| node_publicroutes
node_spa -->|"routes requests"| node_analyticsroutes
node_spa -->|"routes requests"| node_aienpoints
node_spa -->|"checks connection"| node_dbconfig
node_patients -->|"reads and writes"| node_store
node_patients -->|"records changes"| node_audit
node_referrals -->|"reads and updates"| node_store
node_referrals -->|"records actions"| node_audit
node_referrals -->|"sends notifications"| node_sms
node_queue -->|"reads and updates"| node_store
node_queue -->|"sends notifications"| node_sms
node_sms -->|"reads patient and settings"| node_store
node_sms -->|"writes SMS logs"| node_store
node_sms -->|"sends SMS"| node_unisms
node_audit -.->|"persists audit"| node_store
node_auth -->|"checks permissions"| node_rbac
node_store -->|"executes queries"| node_query
node_query -->|"uses pool"| node_dbconfig
node_dbconfig -.->|"connects to"| node_supabase
node_aienpoints -->|"reads care data"| node_store
node_aienpoints -.->|"invokes insights"| node_insights

click node_app "https://github.com/geo211/researcha/blob/main/client/src/App.jsx"
click node_clientapi "https://github.com/geo211/researcha/blob/main/client/src/api.js"
click node_offline "https://github.com/geo211/researcha/blob/main/client/src/lib/offline.js"
click node_patientviews "https://github.com/geo211/researcha/blob/main/client/src/pages/Patients.jsx"
click node_referralviews "https://github.com/geo211/researcha/blob/main/client/src/pages/Referrals.jsx"
click node_dashboard "https://github.com/geo211/researcha/blob/main/client/src/pages/Dashboard.jsx"
click node_analytics "https://github.com/geo211/researcha/blob/main/client/src/pages/Analytics.jsx"
click node_tracking "https://github.com/geo211/researcha/blob/main/client/src/components/ui/public-tracking.jsx"
click node_spa "https://github.com/geo211/researcha/blob/main/server/src/app.js"
click node_auth "https://github.com/geo211/researcha/blob/main/server/src/middleware/auth.js"
click node_patients "https://github.com/geo211/researcha/blob/main/server/src/routes/patientRoutes.js"
click node_referrals "https://github.com/geo211/researcha/blob/main/server/src/routes/referralRoutes.js"
click node_queue "https://github.com/geo211/researcha/blob/main/server/src/routes/queueRoutes.js"
click node_adminroutes "https://github.com/geo211/researcha/blob/main/server/src/routes/userRoutes.js"
click node_publicroutes "https://github.com/geo211/researcha/blob/main/server/src/routes/publicRoutes.js"
click node_analyticsroutes "https://github.com/geo211/researcha/blob/main/server/src/routes/analyticsRoutes.js"
click node_aienpoints "https://github.com/geo211/researcha/blob/main/server/src/routes/aiRoutes.js"
click node_insights "https://github.com/geo211/researcha/blob/main/ai/insights.py"
click node_audit "https://github.com/geo211/researcha/blob/main/server/src/services/auditService.js"
click node_sms "https://github.com/geo211/researcha/blob/main/server/src/services/smsService.js"
click node_rbac "https://github.com/geo211/researcha/blob/main/shared/rbac.js"
click node_store "https://github.com/geo211/researcha/blob/main/server/src/lib/supabase/store.js"
click node_query "https://github.com/geo211/researcha/blob/main/server/src/lib/supabase/query.js"
click node_dbconfig "https://github.com/geo211/researcha/blob/main/server/src/config/db.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_clientapi,node_offline,node_patientviews,node_referralviews,node_dashboard,node_analytics,node_tracking,node_staff,node_patient toneBlue
class node_spa,node_auth,node_patients,node_referrals,node_queue,node_adminroutes,node_publicroutes,node_analyticsroutes,node_aienpoints,node_supabase toneAmber
class node_insights,node_audit,node_sms,node_rbac,node_unisms toneMint
class node_store,node_query,node_dbconfig toneRose
class node_public toneIndigo
```

## Components

### Client experience

- [CareLink app](https://github.com/geo211/researcha/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [API and offline client](https://github.com/geo211/researcha/blob/main/client/src/api.js): `client/src/api.js`
- [Offline queue and cache](https://github.com/geo211/researcha/blob/main/client/src/lib/offline.js): `client/src/lib/offline.js`
- [Patient management](https://github.com/geo211/researcha/blob/main/client/src/pages/Patients.jsx): `client/src/pages/Patients.jsx`
- [Referral management](https://github.com/geo211/researcha/blob/main/client/src/pages/Referrals.jsx): `client/src/pages/Referrals.jsx`
- [Dashboard](https://github.com/geo211/researcha/blob/main/client/src/pages/Dashboard.jsx): `client/src/pages/Dashboard.jsx`
- [Analytics](https://github.com/geo211/researcha/blob/main/client/src/pages/Analytics.jsx): `client/src/pages/Analytics.jsx`
- [Public tracking](https://github.com/geo211/researcha/blob/main/client/src/components/ui/public-tracking.jsx): `client/src/components/ui/public-tracking.jsx`

### API workflows

- [API application](https://github.com/geo211/researcha/blob/main/server/src/app.js): `server/src/app.js`
- [Authentication and RBAC](https://github.com/geo211/researcha/blob/main/server/src/middleware/auth.js): `server/src/middleware/auth.js`
- [Patient records](https://github.com/geo211/researcha/blob/main/server/src/routes/patientRoutes.js): `server/src/routes/patientRoutes.js`
- [Referral workflow](https://github.com/geo211/researcha/blob/main/server/src/routes/referralRoutes.js): `server/src/routes/referralRoutes.js`
- [Queue management](https://github.com/geo211/researcha/blob/main/server/src/routes/queueRoutes.js): `server/src/routes/queueRoutes.js`
- [Admin and settings](https://github.com/geo211/researcha/blob/main/server/src/routes/userRoutes.js): `server/src/routes/userRoutes.js`
- [Public endpoints](https://github.com/geo211/researcha/blob/main/server/src/routes/publicRoutes.js): `server/src/routes/publicRoutes.js`
- [Analytics endpoints](https://github.com/geo211/researcha/blob/main/server/src/routes/analyticsRoutes.js): `server/src/routes/analyticsRoutes.js`
- [AI insights endpoint](https://github.com/geo211/researcha/blob/main/server/src/routes/aiRoutes.js): `server/src/routes/aiRoutes.js`

### Domain services

- [AI insights](https://github.com/geo211/researcha/blob/main/ai/insights.py): `ai/insights.py`
- [Audit logging](https://github.com/geo211/researcha/blob/main/server/src/services/auditService.js): `server/src/services/auditService.js`
- [SMS notifications](https://github.com/geo211/researcha/blob/main/server/src/services/smsService.js): `server/src/services/smsService.js`
- [Role permissions](https://github.com/geo211/researcha/blob/main/shared/rbac.js): `shared/rbac.js`

### Data and access

- [Supabase data store](https://github.com/geo211/researcha/blob/main/server/src/lib/supabase/store.js): `server/src/lib/supabase/store.js`
- [SQL query layer](https://github.com/geo211/researcha/blob/main/server/src/lib/supabase/query.js): `server/src/lib/supabase/query.js`
- [Database connection](https://github.com/geo211/researcha/blob/main/server/src/config/db.js): `server/src/config/db.js`

### Other components

- **Staff user**
- **Patient user**
- **Public visitor**
- **UniSMS API**
- **Supabase PostgreSQL**

## Connections

- Staff user → CareLink app: uses (evidence: `client/src/App.jsx`)
- Patient user → CareLink app: uses (evidence: `client/src/App.jsx`)
- Public visitor → CareLink app: opens tracking (evidence: `README.md`)
- CareLink app → API and offline client: requests data (evidence: `client/src/App.jsx`)
- CareLink app → Patient management: renders (evidence: `client/src/App.jsx`)
- CareLink app → Referral management: renders (evidence: `client/src/App.jsx`)
- CareLink app → Dashboard: renders (evidence: `client/src/App.jsx`)
- CareLink app → Analytics: renders (evidence: `client/src/App.jsx`)
- CareLink app → Public tracking: renders (evidence: `client/src/App.jsx`)
- API and offline client → Offline queue and cache: caches and queues (evidence: `client/src/api.js`)
- API and offline client → API application: sends API requests (evidence: `README.md`)
- API application → Patient records: routes requests (evidence: `server/src/app.js`)
- API application → Referral workflow: routes requests (evidence: `server/src/app.js`)
- API application → Queue management: routes requests (evidence: `server/src/app.js`)
- API application → Admin and settings: routes requests (evidence: `server/src/app.js`)
- API application → Public endpoints: routes requests (evidence: `server/src/app.js`)
- API application → Analytics endpoints: routes requests (evidence: `server/src/app.js`)
- API application → AI insights endpoint: routes requests (evidence: `server/src/app.js`)
- API application → Database connection: checks connection (evidence: `server/src/app.js`)
- Patient records → Supabase data store: reads and writes (evidence: `server/src/routes/patientRoutes.js`)
- Patient records → Audit logging: records changes (evidence: `server/src/routes/patientRoutes.js`)
- Referral workflow → Supabase data store: reads and updates (evidence: `server/src/routes/referralRoutes.js`)
- Referral workflow → Audit logging: records actions (evidence: `server/src/routes/referralRoutes.js`)
- Referral workflow → SMS notifications: sends notifications (evidence: `server/src/routes/referralRoutes.js`)
- Queue management → Supabase data store: reads and updates (evidence: `server/src/routes/queueRoutes.js`)
- Queue management → SMS notifications: sends notifications (evidence: `server/src/routes/queueRoutes.js`)
- SMS notifications → Supabase data store: reads patient and settings (evidence: `server/src/services/smsService.js`)
- SMS notifications → Supabase data store: writes SMS logs (evidence: `server/src/services/smsService.js`)
- SMS notifications → UniSMS API: sends SMS (evidence: `server/src/services/smsService.js`)
- Audit logging → Supabase data store: persists audit (evidence: `server/src/services/auditService.js`)
- Authentication and RBAC → Role permissions: checks permissions (evidence: `server/src/middleware/auth.js`)
- Supabase data store → SQL query layer: executes queries (evidence: `server/src/lib/supabase/store.js`)
- SQL query layer → Database connection: uses pool (evidence: `server/src/lib/supabase/query.js`)
- Database connection → Supabase PostgreSQL: connects to (evidence: `README.md`)
- AI insights endpoint → Supabase data store: reads care data (evidence: `server/src/routes/aiRoutes.js`)
- AI insights endpoint → AI insights: invokes insights