# iaxcel-ai/gaia architecture

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

- Interactive diagram: https://gitdiagram.com/iaxcel-ai/gaia
- Repository: https://github.com/iaxcel-ai/gaia

## Overview

Gaia connects rural health facilities through resource visibility and a referral workflow. Staff log in, inspect facility resources, create referrals, and receiving facilities accept, decline, or complete them; district administrators review reports and manage staff. The frontend also receives referral events in real time, while the backend records referral activity and falls back to a logged SMS stub when no receiving-facility socket is present. The graph preserves documented capabilities, but several route implementations and report details are represented only by their indexed paths; their internal interactions are omitted where evidence is limited.

Main entry points: [`client/src/App.jsx`](https://github.com/iaxcel-ai/gaia/blob/main/client/src/App.jsx) (Page routing), [`server/src/routes/admin.js`](https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/admin.js) (Account administration), [`server/src/db.js`](https://github.com/iaxcel-ai/gaia/blob/main/server/src/db.js) (PostgreSQL access), [`server/src/routes/auth.js`](https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/auth.js) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Staff web app"]
  node_app["Page routing<br/>[App.jsx]"]
  node_authui["Login state<br/>[AuthContext.jsx]"]
  node_dashboard["Resource dashboard<br/>[Dashboard.jsx]"]
  node_resourceview["Resource display<br/>[ResourceCard.jsx]"]
  node_referralform["Referral creation<br/>[ReferralForm.jsx]"]
  node_referrallist["Referral actions<br/>[Referrals.jsx]"]
  node_referralapi["Referral API client<br/>[referrals.js]"]
  node_socketui["Live event listener<br/>[SocketContext.jsx]"]
  node_reportsui["District reports"]
  node_adminui["Staff accounts<br/>[AdminUsers.jsx]"]
  node_authapi["Authentication API<br/>[auth.js]"]
  node_facilityapi["Facility API client<br/>[facilities.js]"]
  node_reportsapi["Reports API client<br/>[reports.js]"]
end

subgraph group_server["Referral services"]
  node_authroutes["Authentication routes<br/>[auth.js]"]
  node_facilityroutes["Facility resources<br/>[facilities.js]"]
  node_referralroutes["Referral workflow<br/>[referrals.js]"]
  node_reportroutes["District reporting<br/>[reports.js]"]
  node_adminroutes["Account administration<br/>[admin.js]"]
  node_authservice["Token and passwords<br/>[authService.js]"]
  node_authguard["Authentication guard<br/>[requireAuth.js]"]
  node_rolecheck["Role guard<br/>[requireRole.js]"]
end

subgraph group_data["Persistence and alerts"]
  node_audit["Audit logging<br/>[auditService.js]"]
  node_notify["Referral notifications"]
  node_socketserver["Socket rooms<br/>[socket.js]"]
  node_db[("PostgreSQL access<br/>[db.js]")]
end

node_staff(("Facility staff"))
node_adminuser(("District admin"))
node_sms["SMS stub"]

node_staff -->|"uses"| node_app
node_adminuser -->|"uses"| node_app
node_app -->|"provides auth"| node_authui
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_referralform
node_app -->|"routes to"| node_referrallist
node_app -->|"admin route"| node_reportsui
node_app -->|"admin route"| node_adminui
node_authui -->|"requests login"| node_authapi
node_dashboard -->|"loads resources"| node_facilityapi
node_dashboard -->|"renders resources"| node_resourceview
node_referralform -->|"loads facilities"| node_facilityapi
node_referralform -->|"creates referral"| node_referralapi
node_referrallist -->|"loads and responds"| node_referralapi
node_referrallist -->|"refreshes on event"| node_socketui
node_socketui -->|"uses token"| node_authui
node_reportsui -->|"loads facilities"| node_facilityapi
node_reportsui -->|"loads report"| node_reportsapi
node_adminui -->|"loads facilities"| node_facilityapi
node_adminui -->|"manages accounts"| node_adminroutes
node_referralapi -.->|"HTTP requests"| node_referralroutes
node_authapi -.->|"HTTP requests"| node_authroutes
node_facilityapi -.->|"HTTP requests"| node_facilityroutes
node_reportsapi -.->|"HTTP requests"| node_reportroutes
node_authroutes -->|"queries users"| node_db
node_authroutes -->|"checks and issues tokens"| node_authservice
node_authroutes -->|"guards reset"| node_authguard
node_authroutes -->|"checks admin role"| node_rolecheck
node_authguard -->|"verifies token"| node_authservice
node_facilityroutes -->|"queries resources"| node_db
node_referralroutes -->|"stores referrals"| node_db
node_referralroutes -->|"records actions"| node_audit
node_referralroutes -->|"sends alerts"| node_notify
node_audit -->|"writes audit"| node_db
node_notify -->|"emits to room"| node_socketserver
node_notify -->|"fallback message"| node_sms
node_notify -->|"records channel"| node_db
node_socketui -.->|"listens for events"| node_socketserver
node_adminroutes -->|"queries accounts"| node_db
node_adminroutes -->|"hashes passwords"| node_authservice
node_adminroutes -->|"records changes"| node_audit
node_adminroutes -->|"requires login"| node_authguard
node_adminroutes -->|"checks role"| node_rolecheck
node_reportroutes -->|"queries report data"| node_db

click node_app "https://github.com/iaxcel-ai/gaia/blob/main/client/src/App.jsx"
click node_authui "https://github.com/iaxcel-ai/gaia/blob/main/client/src/context/AuthContext.jsx"
click node_dashboard "https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/Dashboard.jsx"
click node_resourceview "https://github.com/iaxcel-ai/gaia/blob/main/client/src/components/ResourceCard.jsx"
click node_referralform "https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/ReferralForm.jsx"
click node_referrallist "https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/Referrals.jsx"
click node_referralapi "https://github.com/iaxcel-ai/gaia/blob/main/client/src/api/referrals.js"
click node_socketui "https://github.com/iaxcel-ai/gaia/blob/main/client/src/context/SocketContext.jsx"
click node_reportsui "https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/DistrictReports.jsx"
click node_adminui "https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/AdminUsers.jsx"
click node_authapi "https://github.com/iaxcel-ai/gaia/blob/main/client/src/api/auth.js"
click node_facilityapi "https://github.com/iaxcel-ai/gaia/blob/main/client/src/api/facilities.js"
click node_reportsapi "https://github.com/iaxcel-ai/gaia/blob/main/client/src/api/reports.js"
click node_authroutes "https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/auth.js"
click node_facilityroutes "https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/facilities.js"
click node_referralroutes "https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/referrals.js"
click node_reportroutes "https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/reports.js"
click node_adminroutes "https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/admin.js"
click node_authservice "https://github.com/iaxcel-ai/gaia/blob/main/server/src/services/authService.js"
click node_authguard "https://github.com/iaxcel-ai/gaia/blob/main/server/src/middleware/requireAuth.js"
click node_rolecheck "https://github.com/iaxcel-ai/gaia/blob/main/server/src/middleware/requireRole.js"
click node_audit "https://github.com/iaxcel-ai/gaia/blob/main/server/src/services/auditService.js"
click node_notify "https://github.com/iaxcel-ai/gaia/blob/main/server/src/services/notificationService.js"
click node_socketserver "https://github.com/iaxcel-ai/gaia/blob/main/server/src/socket.js"
click node_db "https://github.com/iaxcel-ai/gaia/blob/main/server/src/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_authui,node_dashboard,node_resourceview,node_referralform,node_referrallist,node_referralapi,node_socketui,node_reportsui,node_adminui,node_authapi,node_facilityapi,node_reportsapi toneBlue
class node_authroutes,node_facilityroutes,node_referralroutes,node_reportroutes,node_adminroutes,node_authservice,node_authguard,node_rolecheck toneAmber
class node_audit,node_notify,node_socketserver,node_db toneMint
class node_staff,node_adminuser,node_sms toneIndigo
```

## Components

### Staff web app

- [Page routing](https://github.com/iaxcel-ai/gaia/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Login state](https://github.com/iaxcel-ai/gaia/blob/main/client/src/context/AuthContext.jsx): `client/src/context/AuthContext.jsx`
- [Resource dashboard](https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/Dashboard.jsx): `client/src/pages/Dashboard.jsx`
- [Resource display](https://github.com/iaxcel-ai/gaia/blob/main/client/src/components/ResourceCard.jsx): `client/src/components/ResourceCard.jsx`
- [Referral creation](https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/ReferralForm.jsx): `client/src/pages/ReferralForm.jsx`
- [Referral actions](https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/Referrals.jsx): `client/src/pages/Referrals.jsx`
- [Referral API client](https://github.com/iaxcel-ai/gaia/blob/main/client/src/api/referrals.js): `client/src/api/referrals.js`
- [Live event listener](https://github.com/iaxcel-ai/gaia/blob/main/client/src/context/SocketContext.jsx): `client/src/context/SocketContext.jsx`
- [District reports](https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/DistrictReports.jsx): `client/src/pages/DistrictReports.jsx`
- [Staff accounts](https://github.com/iaxcel-ai/gaia/blob/main/client/src/pages/AdminUsers.jsx): `client/src/pages/AdminUsers.jsx`
- [Authentication API](https://github.com/iaxcel-ai/gaia/blob/main/client/src/api/auth.js): `client/src/api/auth.js`
- [Facility API client](https://github.com/iaxcel-ai/gaia/blob/main/client/src/api/facilities.js): `client/src/api/facilities.js`
- [Reports API client](https://github.com/iaxcel-ai/gaia/blob/main/client/src/api/reports.js): `client/src/api/reports.js`

### Referral services

- [Authentication routes](https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/auth.js): `server/src/routes/auth.js`
- [Facility resources](https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/facilities.js): `server/src/routes/facilities.js`
- [Referral workflow](https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/referrals.js): `server/src/routes/referrals.js`
- [District reporting](https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/reports.js): `server/src/routes/reports.js`
- [Account administration](https://github.com/iaxcel-ai/gaia/blob/main/server/src/routes/admin.js): `server/src/routes/admin.js`
- [Token and passwords](https://github.com/iaxcel-ai/gaia/blob/main/server/src/services/authService.js): `server/src/services/authService.js`
- [Authentication guard](https://github.com/iaxcel-ai/gaia/blob/main/server/src/middleware/requireAuth.js): `server/src/middleware/requireAuth.js`
- [Role guard](https://github.com/iaxcel-ai/gaia/blob/main/server/src/middleware/requireRole.js): `server/src/middleware/requireRole.js`

### Persistence and alerts

- [Audit logging](https://github.com/iaxcel-ai/gaia/blob/main/server/src/services/auditService.js): `server/src/services/auditService.js`
- [Referral notifications](https://github.com/iaxcel-ai/gaia/blob/main/server/src/services/notificationService.js): `server/src/services/notificationService.js`
- [Socket rooms](https://github.com/iaxcel-ai/gaia/blob/main/server/src/socket.js): `server/src/socket.js`
- [PostgreSQL access](https://github.com/iaxcel-ai/gaia/blob/main/server/src/db.js): `server/src/db.js`

### Other components

- **Facility staff**
- **District admin**
- **SMS stub**

## Connections

- Facility staff → Page routing: uses (evidence: `client/src/App.jsx`)
- District admin → Page routing: uses (evidence: `client/src/App.jsx`)
- Page routing → Login state: provides auth (evidence: `client/src/App.jsx`)
- Page routing → Resource dashboard: routes to (evidence: `client/src/App.jsx`)
- Page routing → Referral creation: routes to (evidence: `client/src/App.jsx`)
- Page routing → Referral actions: routes to (evidence: `client/src/App.jsx`)
- Page routing → District reports: admin route (evidence: `client/src/App.jsx`)
- Page routing → Staff accounts: admin route (evidence: `client/src/App.jsx`)
- Login state → Authentication API: requests login (evidence: `client/src/context/AuthContext.jsx`)
- Resource dashboard → Facility API client: loads resources (evidence: `client/src/pages/Dashboard.jsx`)
- Resource dashboard → Resource display: renders resources (evidence: `client/src/pages/Dashboard.jsx`)
- Referral creation → Facility API client: loads facilities (evidence: `client/src/pages/ReferralForm.jsx`)
- Referral creation → Referral API client: creates referral (evidence: `client/src/pages/ReferralForm.jsx`)
- Referral actions → Referral API client: loads and responds (evidence: `client/src/pages/Referrals.jsx`)
- Referral actions → Live event listener: refreshes on event (evidence: `client/src/pages/Referrals.jsx`)
- Live event listener → Login state: uses token (evidence: `client/src/context/SocketContext.jsx`)
- District reports → Facility API client: loads facilities (evidence: `client/src/pages/DistrictReports.jsx`)
- District reports → Reports API client: loads report (evidence: `client/src/pages/DistrictReports.jsx`)
- Staff accounts → Facility API client: loads facilities (evidence: `client/src/pages/AdminUsers.jsx`)
- Staff accounts → Account administration: manages accounts (evidence: `client/src/pages/AdminUsers.jsx`)
- Referral API client → Referral workflow: HTTP requests
- Authentication API → Authentication routes: HTTP requests
- Facility API client → Facility resources: HTTP requests
- Reports API client → District reporting: HTTP requests
- Authentication routes → PostgreSQL access: queries users (evidence: `server/src/routes/auth.js`)
- Authentication routes → Token and passwords: checks and issues tokens (evidence: `server/src/routes/auth.js`)
- Authentication routes → Authentication guard: guards reset (evidence: `server/src/routes/auth.js`)
- Authentication routes → Role guard: checks admin role (evidence: `server/src/routes/auth.js`)
- Authentication guard → Token and passwords: verifies token (evidence: `server/src/middleware/requireAuth.js`)
- Facility resources → PostgreSQL access: queries resources (evidence: `server/src/routes/facilities.js`)
- Referral workflow → PostgreSQL access: stores referrals (evidence: `server/src/routes/referrals.js`)
- Referral workflow → Audit logging: records actions (evidence: `server/src/routes/referrals.js`)
- Referral workflow → Referral notifications: sends alerts (evidence: `server/src/routes/referrals.js`)
- Audit logging → PostgreSQL access: writes audit (evidence: `server/src/services/auditService.js`)
- Referral notifications → Socket rooms: emits to room (evidence: `server/src/services/notificationService.js`)
- Referral notifications → SMS stub: fallback message (evidence: `server/src/services/notificationService.js`)
- Referral notifications → PostgreSQL access: records channel (evidence: `server/src/services/notificationService.js`)
- Live event listener → Socket rooms: listens for events
- Account administration → PostgreSQL access: queries accounts (evidence: `server/src/routes/admin.js`)
- Account administration → Token and passwords: hashes passwords (evidence: `server/src/routes/admin.js`)
- Account administration → Audit logging: records changes (evidence: `server/src/routes/admin.js`)
- Account administration → Authentication guard: requires login (evidence: `server/src/routes/admin.js`)
- Account administration → Role guard: checks role (evidence: `server/src/routes/admin.js`)
- District reporting → PostgreSQL access: queries report data (evidence: `server/src/routes/reports.js`)
