# 5erax/sep490_fe_medicalaiassistant architecture

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

- Interactive diagram: https://gitdiagram.com/5erax/sep490_fe_medicalaiassistant
- Repository: https://github.com/5erax/sep490_fe_medicalaiassistant

## Overview

#### 1. Purpose and Runtime
MediMate AI is a React SPA for pre-visit medical guidance: symptom intake/AI assistance, provider discovery, lab and medication workflows, subscriptions, and role-specific patient, staff, doctor, and admin workspaces. It runs on React 19/Vite and deploys to Vercel. Browser entry and application composition begin at `src/main.jsx`, `src/App.jsx`, and `src/SpaRoot.jsx`.

#### 2. Routing, Identity, and Access Boundary
The SPA route manifest directs public, authenticated, and workspace screens; role/access logic and intended-return handling are centralized rather than embedded in pages. Key paths: `src/router/routes.js`, `src/router/access.js`, `src/router/returnIntent.js`. Authentication—including account login and Google OAuth—is mediated by `src/services/authService.js` and `src/services/googleOAuthConfig.js`. Pages such as `src/pages/AuthPages.jsx` and `src/pages/WorkspaceRedirect.jsx` are entry/transition surfaces.

#### 3. API Integration Layer
UI code should follow the enforced flow: Page/Component → domain service → centralized endpoints → API client → backend. Shared transport, error treatment, and endpoint declarations live in `src/services/apiClient.js`, `src/services/api.js`, and `src/services/endpoints.js`. Domain services isolate backend contracts for clinical, account, facility, and payment operations, e.g. `src/services/symptomAnalysisService.js`, `src/services/facilityService.js`, and `src/services/subscriptionService.js`. The backend is an external MediMate API; Vite/Vercel proxy `/api/*` requests through `api/proxy.js`.

#### 4. Patient Clinical Journey
The core patient flow collects symptoms, sends them to symptom/chat APIs, presents guidance/history, and transitions toward suitable facilities or further care workflows. The main UI/service boundaries are `src/pages/SymptomAnalysisPage.jsx`, `src/components/patient/SymptomChatBox.jsx`, `src/hooks/useSymptomIntake.js`, `src/services/symptomChat.js`, and `src/services/consultationSessionService.js`. Medical records, lab indicators, and self-reported medication information are distinct patient domains via `src/pages/MedicalRecordPage.jsx`, `src/pages/MedicationScanPage.jsx`, `src/services/labTestService.js`, and `src/services/userMedicationService.js`.

#### 5. Discovery and Care Coordination
Facility/department/doctor discovery is presented through list/map UI and backend catalog services. Geographic rendering uses MapLibre GL/React Map GL, centered in `src/pages/NearbyClinicPage.jsx`, `src/components/nearbyClinic/FacilityMap.jsx`, and `src/components/nearbyClinic/FacilityList.jsx`; data access is through `src/services/facilityService.js` and `src/services/doctorService.js`. Recovery plans have both REST and realtime integration boundaries: `src/pages/RecoveryPlanPage.jsx`, `src/services/recoveryPlanService.js`, and `src/services/recoveryPlanRealtime.js`, using the configured backend hub origin.

#### 6. Workspace and Administration
Workspace shells separate personalized patient operation from staff/admin management. Patient onboarding and profile completion are coordinated by `src/components/workspace/UserWorkspaceShell.jsx`, `src/components/workspace/PatientOnboardingAssistant.jsx`, and `src/services/patientProfileSetup.js`. Admin management is consolidated in `src/pages/AdminWorkspacePage.jsx` and domain sections such as `src/components/adminAIConfigs/AdminAIConfigsSection.jsx` and `src/components/adminClinicalData/AdminClinicalCatalogSection.jsx`, backed by administrative service modules including `src/services/aiConfigManagement.js`.

#### 7. External Services and Deployment
External integrations are Google OAuth, Cloudinary direct uploads, PayOS-backed subscription/payment results, MapLibre map rendering, and backend realtime recovery-plan updates. Relevant adapters include `src/services/cloudinaryUploadService.js`, `src/pages/PaymentResultPage.jsx`, and `src/services/recoveryPlanRealtime.js`. Environment values select API, realtime, OAuth, and Cloudinary origins; production Vercel behavior is configured through `vercel.json`, with SPA routing and `/api` proxying.

Main entry points: [`src/router/routes.js`](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/router/routes.js) (Route manifest), [`src/services/apiClient.js`](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/apiClient.js) (API integration), [`src/pages/NearbyClinicPage.jsx`](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/NearbyClinicPage.jsx) (Facility discovery), [`src/App.jsx`](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/App.jsx) (App composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_spa["React SPA"]
  node_entry["Browser entry<br/>React bootstrap<br/>[main.jsx]"]
  node_app["App composition<br/>SPA shell<br/>[App.jsx]"]
  node_root["SPA root<br/>application root<br/>[SpaRoot.jsx]"]
  node_routes["Route manifest<br/>routing<br/>[routes.js]"]
  node_access["Access control<br/>route authorization<br/>[access.js]"]
  node_clinical["Clinical journey<br/>patient UI"]
  node_records["Records and medications<br/>patient UI"]
  node_discovery["Facility discovery<br/>map and list UI"]
  node_recovery["Recovery plans<br/>patient UI"]
  node_workspace["Patient workspace<br/>workspace shell"]
  node_admin["Admin workspace<br/>management UI"]
  node_payments["Subscription payments<br/>payment UI and service"]
end

subgraph group_services["Integration services"]
  node_auth["Authentication<br/>identity service<br/>[authService.js]"]
  node_symptom["Symptom domain<br/>clinical service<br/>[symptomChat.js]"]
  node_caredata["Patient care data<br/>clinical services<br/>[labTestService.js]"]
  node_facility["Care catalog<br/>facility service<br/>[facilityService.js]"]
  node_realtime["Recovery realtime<br/>realtime service"]
  node_adminservice["AI config management<br/>admin service"]
  node_api["API integration<br/>HTTP client and endpoints<br/>[apiClient.js]"]
end

subgraph group_external["External systems"]
  node_proxy{{"Vercel API proxy<br/>serverless proxy<br/>[proxy.js]"}}
  node_backend[("MediMate API<br/>external backend")]
  node_google(("Google OAuth<br/>external identity"))
  node_maps(("MapLibre<br/>map renderer"))
end

node_entry -->|"mounts"| node_app
node_app -->|"composes"| node_root
node_root -->|"loads routes"| node_routes
node_routes -->|"guards routes"| node_access
node_access -->|"checks identity"| node_auth
node_auth -->|"OAuth"| node_google
node_routes -->|"renders"| node_clinical
node_routes -->|"renders"| node_discovery
node_routes -->|"renders"| node_workspace
node_routes -->|"renders"| node_admin
node_clinical -->|"symptom requests"| node_symptom
node_records -->|"patient data"| node_caredata
node_discovery -->|"catalog queries"| node_facility
node_discovery -->|"renders map"| node_maps
node_recovery -->|"live updates"| node_realtime
node_admin -->|"manages configs"| node_adminservice
node_symptom -->|"uses"| node_api
node_caredata -->|"uses"| node_api
node_facility -->|"uses"| node_api
node_adminservice -->|"uses"| node_api
node_api -->|"/api requests"| node_proxy
node_proxy -->|"forwards"| node_backend
node_realtime -.->|"hub connection"| node_backend
node_payments -->|"payment result"| node_backend

click node_entry "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/main.jsx"
click node_app "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/App.jsx"
click node_root "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/SpaRoot.jsx"
click node_routes "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/router/routes.js"
click node_access "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/router/access.js"
click node_auth "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/authService.js"
click node_clinical "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/SymptomAnalysisPage.jsx"
click node_symptom "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/symptomChat.js"
click node_records "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/MedicalRecordPage.jsx"
click node_caredata "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/labTestService.js"
click node_discovery "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/NearbyClinicPage.jsx"
click node_facility "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/facilityService.js"
click node_recovery "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/RecoveryPlanPage.jsx"
click node_realtime "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/recoveryPlanRealtime.js"
click node_workspace "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/components/workspace/UserWorkspaceShell.jsx"
click node_admin "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/AdminWorkspacePage.jsx"
click node_adminservice "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/aiConfigManagement.js"
click node_payments "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/PaymentResultPage.jsx"
click node_api "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/apiClient.js"
click node_proxy "https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/api/proxy.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_entry,node_app,node_root,node_routes,node_access,node_clinical,node_records,node_discovery,node_recovery,node_workspace,node_admin,node_payments toneBlue
class node_auth,node_symptom,node_caredata,node_facility,node_realtime,node_adminservice,node_api toneAmber
class node_proxy,node_backend,node_google,node_maps toneMint
```

## Components

### React SPA

- [Browser entry](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/main.jsx): React bootstrap · `src/main.jsx`
- [App composition](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/App.jsx): SPA shell · `src/App.jsx`
- [SPA root](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/SpaRoot.jsx): application root · `src/SpaRoot.jsx`
- [Route manifest](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/router/routes.js): routing · Defines public, authenticated, and workspace screens. · `src/router/routes.js`
- [Access control](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/router/access.js): route authorization · Applies roles and return intent. · `src/router/access.js`
- [Clinical journey](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/SymptomAnalysisPage.jsx): patient UI · Symptom guidance and consultation flow. · `src/pages/SymptomAnalysisPage.jsx`
- [Records and medications](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/MedicalRecordPage.jsx): patient UI · Medical records, labs, and medication intake. · `src/pages/MedicalRecordPage.jsx`
- [Facility discovery](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/NearbyClinicPage.jsx): map and list UI · Nearby facility and doctor discovery. · `src/pages/NearbyClinicPage.jsx`
- [Recovery plans](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/RecoveryPlanPage.jsx): patient UI · Care-plan viewing and updates. · `src/pages/RecoveryPlanPage.jsx`
- [Patient workspace](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/components/workspace/UserWorkspaceShell.jsx): workspace shell · Coordinates onboarding and profile completion. · `src/components/workspace/UserWorkspaceShell.jsx`
- [Admin workspace](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/AdminWorkspacePage.jsx): management UI · AI configuration and clinical catalog management. · `src/pages/AdminWorkspacePage.jsx`
- [Subscription payments](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/pages/PaymentResultPage.jsx): payment UI and service · Subscription results and payment workflows. · `src/pages/PaymentResultPage.jsx`

### Integration services

- [Authentication](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/authService.js): identity service · Login and Google OAuth mediation. · `src/services/authService.js`
- [Symptom domain](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/symptomChat.js): clinical service · Chat and symptom-analysis backend contracts. · `src/services/symptomChat.js`
- [Patient care data](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/labTestService.js): clinical services · Lab and user-medication contracts. · `src/services/labTestService.js`
- [Care catalog](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/facilityService.js): facility service · Facility and doctor data access. · `src/services/facilityService.js`
- [Recovery realtime](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/recoveryPlanRealtime.js): realtime service · Receives backend hub updates. · `src/services/recoveryPlanRealtime.js`
- [AI config management](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/aiConfigManagement.js): admin service · `src/services/aiConfigManagement.js`
- [API integration](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/src/services/apiClient.js): HTTP client and endpoints · Central transport, errors, and endpoint declarations. · `src/services/apiClient.js`

### External systems

- [Vercel API proxy](https://github.com/5erax/sep490_fe_medicalaiassistant/blob/main/api/proxy.js): serverless proxy · Proxies browser /api requests. · `api/proxy.js`
- **MediMate API**: external backend · Clinical, account, facility, and payment backend.
- **Google OAuth**: external identity
- **MapLibre**: map renderer

## Connections

- Browser entry → App composition: mounts
- App composition → SPA root: composes
- SPA root → Route manifest: loads routes
- Route manifest → Access control: guards routes
- Access control → Authentication: checks identity
- Authentication → Google OAuth: OAuth
- Route manifest → Clinical journey: renders
- Route manifest → Facility discovery: renders
- Route manifest → Patient workspace: renders
- Route manifest → Admin workspace: renders
- Clinical journey → Symptom domain: symptom requests
- Records and medications → Patient care data: patient data
- Facility discovery → Care catalog: catalog queries
- Facility discovery → MapLibre: renders map
- Recovery plans → Recovery realtime: live updates
- Admin workspace → AI config management: manages configs
- Symptom domain → API integration: uses
- Patient care data → API integration: uses
- Care catalog → API integration: uses
- AI config management → API integration: uses
- API integration → Vercel API proxy: /api requests
- Vercel API proxy → MediMate API: forwards
- Recovery realtime → MediMate API: hub connection
- Subscription payments → MediMate API: payment result