How ahlem-phantom/ai-healthcare-assistant works
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: App.js React app · routes.js Routes · server.js Express app · appointment.controller.js Core domains
Components 20
React client
User-facing SPA with role-based flows, chat, records, and browser ML assets.
- React app · Primary UI and navigation layer for public, patient, doctor, and registration flows.
react-app/src/App.js - Routes · Role-aware page routing and screen composition for the frontend.
react-app/src/routes.js - Auth pages · Login, registration, face login, password reset, and role selection screens.
react-app/src/pages/auth/Login.js - Doctor portal · Doctor dashboard, appointments, records, blogs, and symptom review screens.
react-app/src/pages/doctor/dashboard.js - Patient portal · Patient dashboard, booking, profile, records, upload, and follow-up screens.
react-app/src/pages/patient/dashboard.js - Public site · Public pages for home, contact, shop, pricing, blog, and map discovery.
react-app/src/pages/public/Home.js - Records UI · Shared medical record views and edit forms used by patient and doctor flows.
react-app/src/components/records/MedicalRecord.js - Chat UI · Frontend chat experience and message rendering for appointment guidance.
react-app/src/components/chat/Chat.js - Redux store · Shared user, appointment, and chat state management across the app.
react-app/src/store/store.js - API client · 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 · Main Node backend that exposes application domains and integrates services.
server/server.js - Auth domain · Authentication, signup verification, JWT middleware, and OAuth entry points.
server/app/controllers/auth.controller.js - Core domains · User, appointment, record, chat, blog, contact, product, payment, and scrape controllers/routes.
server/app/controllers/appointment.controller.js - Mongo models · Operational data models for users, roles, appointments, records, chats, locations, and products.
server/app/models/index.js - External services · 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 · TensorFlow.js face and x-ray model assets served directly to the browser.
react-app/public/TFJS/model.json - Chatbot · Symptom triage and appointment booking orchestration around the chatbot integration.
server/app/Appointment_chatbot/chatbot.js - Python sidecar · Auxiliary Python facial-recognition and model experimentation area.
py side/run.py
Blockchain package
Separate ledger-oriented Node package with chain validation.
- Ledger core · Separate blockchain-oriented ledger implementation and chain state logic.
blockchain/src/core/blockchain-ledger.js - Chain validator · Standalone script for validating the blockchain ledger.
blockchain/src/scripts/validate-chain.js
Connections 21
- 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.