# ahlem-phantom/ai-healthcare-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/ahlem-phantom/ai-healthcare-assistant
- Repository: https://github.com/ahlem-phantom/ai-healthcare-assistant

## Overview

1. **Overall shape**
   This repository is a multi-part healthcare platform, not a single app. The main production path is a React frontend talking to a Node/Express backend, with additional subsystems for AI/ML, chat/appointments, and a separate blockchain-oriented ledger package.

2. **React client as the user-facing shell**
   `react-app/` is the primary UI. It contains role-based pages for public users, patients, doctors, and registration flows, plus shared layout components, record views, chat UI, and Redux state for user/appointment/chat data. This is where most product navigation and orchestration happens.

3. **Client-side ML assets and inference**
   The frontend ships TensorFlow model artifacts in `react-app/public/TFJS` and `react-app/public/XRAY`. That means at least some AI features are designed to run in the browser, especially face login/register and X-ray classification, rather than round-tripping everything to the server.

4. **Express backend as the core application API**
   `server/app/` is the main backend service. It follows a typical Express layering: routes, controllers, models, and middlewares. The backend exposes domains for auth, users, appointments, records, blogs, contacts, products, payments, OAuth, scraping, and chat. This is the central integration point for the application.

5. **Backend data model and persistence boundary**
   The backend is MongoDB-centric. Models exist for users, roles, appointments, records, blogs, contacts, products, chatbot talks, and locations. From an architecture diagram perspective, MongoDB is the main system of record for operational app data, while the backend controllers mediate all persistence access.

6. **Authentication and identity flows**
   The auth subsystem supports multiple entry paths: standard auth, LinkedIn OAuth, and role-aware registration/login flows. The backend has JWT middleware and signup verification middleware, while the frontend has separate pages for login, face login, role selection, and registration steps. This is a distinct security boundary in the system.

7. **AI/chatbot and appointment orchestration**
   The app has a symptom/appointment chatbot path centered around `server/app/Appointment_chatbot/` and related chat controllers/routes. The README describes Dialogflow-driven symptom triage and appointment booking; in the codebase, this appears as a backend chatbot integration that coordinates with appointment logic rather than a standalone service.

8. **Medical records and clinical workflows**
   Records are a first-class domain in both frontend and backend. The UI has doctor-facing record management screens, and the backend has record models/controllers/routes. The README also frames records as blockchain-backed, so the architecture should show records as a protected domain with stronger integrity requirements than ordinary app data.

9. **Blockchain subsystem**
   `blockchain/` is a separate Node package with a ledger core, server, and chain validation script. It looks like a dedicated blockchain/ledger component rather than part of the Express monolith. The README advertises Ethereum smart contracts, but the checked-in code here is more of a Node-based ledger service/validator, so treat that subsystem as distinct and somewhat legacy.

10. **External integrations that materially shape the architecture**
   The backend and frontend integrate with Stripe for payments, Nodemailer for email, Google Maps for location-based doctor search, Dialogflow for chatbot intelligence, LinkedIn OAuth for login, and Nanonets OCR for ID verification. These are not incidental—they define major business flows and should appear as external service boundaries in any diagram.

11. **Python/ML sidecar**
   `py side/` is a separate Python area with a notebook and `run.py`, implying experimental or auxiliary ML work. Based on the README, it likely supports facial recognition or model experimentation rather than serving as the main app backend. It should be shown as an adjacent ML component, not the primary runtime.

12. **Operational/deployment structure**
   The repo is organized as multiple deployable surfaces: the React SPA, the Express backend, the blockchain package, and the Python AI area. The presence of `Procfile`, `.env` templates, and route/controller separation suggests the backend is meant to be deployed independently, with the frontend consuming it over HTTP and the AI/ledger pieces plugged in where needed.

Main entry points: [`react-app/src/App.js`](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/App.js) (React app), [`react-app/src/routes.js`](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/routes.js) (Routes), [`server/server.js`](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/server.js) (Express app), [`server/app/controllers/appointment.controller.js`](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/controllers/appointment.controller.js) (Core domains)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_react_shell["React app<br/>SPA shell<br/>[App.js]"]
  node_react_routes["Routes<br/>client routing<br/>[routes.js]"]
  node_auth_pages["Auth pages<br/>login and signup<br/>[Login.js]"]
  node_doctor_portal["Doctor portal<br/>clinician workspace<br/>[dashboard.js]"]
  node_patient_portal["Patient portal<br/>patient workspace<br/>[dashboard.js]"]
  node_public_site["Public site<br/>marketing and entry<br/>[Home.js]"]
  node_record_ui["Records UI<br/>clinical records<br/>[MedicalRecord.js]"]
  node_chat_ui["Chat UI<br/>messaging UI<br/>[Chat.js]"]
  node_redux_store["Redux store<br/>client state<br/>[store.js]"]
  node_api_client["API client<br/>http services<br/>[auth.service.js]"]
end

subgraph group_backend["Express backend"]
  node_express_api["Express app<br/>api server<br/>[server.js]"]
  node_auth_domain["Auth domain<br/>identity flow<br/>[auth.controller.js]"]
  node_core_domains["Core domains<br/>business controllers"]
  node_mongo_models[("Mongo models<br/>persistence models<br/>[index.js]")]
  node_external_services["External services<br/>third-party APIs<br/>[stripe.js]"]
end

subgraph group_ml["AI sidecars"]
  node_client_ml["Browser ML<br/>tfjs models<br/>[model.json]"]
  node_chatbot_orchestrator["Chatbot<br/>dialogflow flow<br/>[chatbot.js]"]
  node_python_sidecar["Python sidecar<br/>ml experiment<br/>[run.py]"]
end

subgraph group_ledger["Blockchain package"]
  node_blockchain_ledger["Ledger core<br/>blockchain ledger"]
  node_chain_validator["Chain validator<br/>validation script<br/>[validate-chain.js]"]
end

node_react_shell -->|"renders"| node_react_routes
node_react_routes -->|"loads"| node_auth_pages
node_react_routes -->|"loads"| node_doctor_portal
node_react_routes -->|"loads"| node_patient_portal
node_react_routes -->|"loads"| node_public_site
node_doctor_portal -->|"uses"| node_record_ui
node_patient_portal -->|"uses"| node_record_ui
node_react_shell -->|"contains"| node_chat_ui
node_react_shell -->|"syncs"| node_redux_store
node_react_shell -->|"calls"| node_api_client
node_react_shell -->|"loads models"| node_client_ml
node_api_client -->|"http"| node_express_api
node_express_api -->|"routes"| node_auth_domain
node_express_api -->|"routes"| node_core_domains
node_core_domains -->|"persists"| node_mongo_models
node_express_api -->|"integrates"| node_external_services
node_chatbot_orchestrator -->|"coordinates"| node_core_domains
node_chatbot_orchestrator -->|"uses"| node_external_services
node_core_domains -.->|"records"| node_blockchain_ledger
node_blockchain_ledger -->|"checks"| node_chain_validator
node_python_sidecar -.->|"supports"| node_client_ml

click node_react_shell "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/App.js"
click node_react_routes "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/routes.js"
click node_auth_pages "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/pages/auth/Login.js"
click node_doctor_portal "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/pages/doctor/dashboard.js"
click node_patient_portal "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/pages/patient/dashboard.js"
click node_public_site "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/pages/public/Home.js"
click node_record_ui "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/components/records/MedicalRecord.js"
click node_chat_ui "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/components/chat/Chat.js"
click node_redux_store "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/store/store.js"
click node_client_ml "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/public/TFJS/model.json"
click node_api_client "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/services/auth.service.js"
click node_express_api "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/server.js"
click node_auth_domain "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/controllers/auth.controller.js"
click node_core_domains "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/controllers/appointment.controller.js"
click node_mongo_models "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/models/index.js"
click node_chatbot_orchestrator "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/Appointment_chatbot/chatbot.js"
click node_external_services "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/config/stripe.js"
click node_blockchain_ledger "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/blockchain/src/core/blockchain-ledger.js"
click node_chain_validator "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/blockchain/src/scripts/validate-chain.js"
click node_python_sidecar "https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/py side/run.py"

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_react_shell,node_react_routes,node_auth_pages,node_doctor_portal,node_patient_portal,node_public_site,node_record_ui,node_chat_ui,node_redux_store,node_api_client toneBlue
class node_express_api,node_auth_domain,node_core_domains,node_mongo_models,node_external_services toneAmber
class node_client_ml,node_chatbot_orchestrator,node_python_sidecar toneMint
class node_blockchain_ledger,node_chain_validator toneRose
```

## Components

### React client

User-facing SPA with role-based flows, chat, records, and browser ML assets.

- [React app](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/App.js): SPA shell · Primary UI and navigation layer for public, patient, doctor, and registration flows. · `react-app/src/App.js`
- [Routes](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/routes.js): client routing · Role-aware page routing and screen composition for the frontend. · `react-app/src/routes.js`
- [Auth pages](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/pages/auth/Login.js): login and signup · Login, registration, face login, password reset, and role selection screens. · `react-app/src/pages/auth/Login.js`
- [Doctor portal](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/pages/doctor/dashboard.js): clinician workspace · Doctor dashboard, appointments, records, blogs, and symptom review screens. · `react-app/src/pages/doctor/dashboard.js`
- [Patient portal](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/pages/patient/dashboard.js): patient workspace · Patient dashboard, booking, profile, records, upload, and follow-up screens. · `react-app/src/pages/patient/dashboard.js`
- [Public site](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/pages/public/Home.js): marketing and entry · Public pages for home, contact, shop, pricing, blog, and map discovery. · `react-app/src/pages/public/Home.js`
- [Records UI](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/components/records/MedicalRecord.js): clinical records · Shared medical record views and edit forms used by patient and doctor flows. · `react-app/src/components/records/MedicalRecord.js`
- [Chat UI](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/components/chat/Chat.js): messaging UI · Frontend chat experience and message rendering for appointment guidance. · `react-app/src/components/chat/Chat.js`
- [Redux store](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/store/store.js): client state · Shared user, appointment, and chat state management across the app. · `react-app/src/store/store.js`
- [API client](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/src/services/auth.service.js): http services · Frontend service layer for auth and user API calls. · `react-app/src/services/auth.service.js`

### Express backend

Main application API, domain controllers, persistence, and integrations.

- [Express app](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/server.js): api server · Main Node backend that exposes application domains and integrates services. · `server/server.js`
- [Auth domain](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/controllers/auth.controller.js): identity flow · Authentication, signup verification, JWT middleware, and OAuth entry points. · `server/app/controllers/auth.controller.js`
- [Core domains](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/controllers/appointment.controller.js): business controllers · User, appointment, record, chat, blog, contact, product, payment, and scrape controllers/routes. · `server/app/controllers/appointment.controller.js`
- [Mongo models](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/models/index.js): persistence models · Operational data models for users, roles, appointments, records, chats, locations, and products. · `server/app/models/index.js`
- [External services](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/config/stripe.js): third-party APIs · Stripe, email, LinkedIn OAuth, Google Maps, Dialogflow, and OCR integrations. · `server/app/config/stripe.js`

### AI sidecars

Browser and Python ML components plus chatbot orchestration.

- [Browser ML](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/react-app/public/TFJS/model.json): tfjs models · TensorFlow.js face and x-ray model assets served directly to the browser. · `react-app/public/TFJS/model.json`
- [Chatbot](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/server/app/Appointment_chatbot/chatbot.js): dialogflow flow · Symptom triage and appointment booking orchestration around the chatbot integration. · `server/app/Appointment_chatbot/chatbot.js`
- [Python sidecar](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/HEAD/py%20side/run.py): ml experiment · Auxiliary Python facial-recognition and model experimentation area. · `py side/run.py`

### Blockchain package

Separate ledger-oriented Node package with chain validation.

- [Ledger core](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/blockchain/src/core/blockchain-ledger.js): blockchain ledger · Separate blockchain-oriented ledger implementation and chain state logic. · `blockchain/src/core/blockchain-ledger.js`
- [Chain validator](https://github.com/ahlem-phantom/ai-healthcare-assistant/blob/main/blockchain/src/scripts/validate-chain.js): validation script · Standalone script for validating the blockchain ledger. · `blockchain/src/scripts/validate-chain.js`

## Connections

- React app → Routes: renders · The SPA is organized through client-side routing and page composition.
- Routes → Auth pages: loads · Routes direct users into auth and registration flows.
- Routes → Doctor portal: loads · Routes surface clinician workspace screens.
- Routes → Patient portal: loads · Routes surface patient workspace screens.
- Routes → Public site: loads · Routes expose the public entry pages.
- Doctor portal → Records UI: uses · Doctor workflows rely on shared record views and edits.
- Patient portal → Records UI: uses · Patient workflows also consume record views.
- React app → Chat UI: contains · The client embeds messaging and symptom chat screens.
- React app → Redux store: syncs · User, appointment, and chat state are coordinated centrally.
- React app → API client: calls · The UI talks to the backend through service wrappers.
- React app → Browser ML: loads models · Browser-side ML assets support face and x-ray features.
- API client → Express app: http · Frontend services invoke the backend API.
- Express app → Auth domain: routes · Authentication is handled as a distinct backend boundary.
- Express app → Core domains: routes · Main business flows are exposed through controllers and routes.
- Core domains → Mongo models: persists · Controllers mediate access to the Mongo-backed operational models.
- Express app → External services: integrates · The backend connects to payment, email, OAuth, maps, Dialogflow, and OCR services.
- Chatbot → Core domains: coordinates · Chatbot triage feeds appointment and chat domain logic.
- Chatbot → External services: uses · Dialogflow and related services drive the chatbot experience.
- Core domains → Ledger core: records · Clinical record workflows are associated with the separate ledger subsystem.
- Ledger core → Chain validator: checks · The ledger package includes a dedicated validation path.
- Python sidecar → Browser ML: supports · Python ML experimentation complements browser-based model use.