# anto-remy/remy-care-connect architecture

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

- Interactive diagram: https://gitdiagram.com/anto-remy/remy-care-connect
- Repository: https://github.com/anto-remy/remy-care-connect

## Overview

#### Purpose and Runtime
Remy Care Connect is a role-based maternal-health frontend for mothers, community health workers (CHWs), nurses, and facility staff. It provides registration/authentication, care monitoring, assignments, escalations, appointments, and notifications. The browser SPA is built with React/TypeScript and Vite; Tailwind/PostCSS support styling. The stated backend boundary is a FastAPI/PostgreSQL service, accessed from the frontend rather than present in this repository.

Entry points: `src/main.tsx`, `src/App.tsx`, and `index.html`.

#### Application Composition and Routing
`App.tsx` is the application shell and route composition point. Page-level entry routes separate public landing/auth flows from role-specific application surfaces:
- Public and role selection: `src/pages/LandingPage.tsx`, `src/pages/Login.tsx`, `src/pages/RoleSelector.tsx`
- Mother surfaces: `src/pages/MotherIndex.tsx`, `src/pages/ModernMotherIndex.tsx`
- Worker/facility surfaces: `src/pages/CHWIndex.tsx`, `src/pages/NurseIndex.tsx`, `src/pages/FacilityIndex.tsx`

Protected access is enforced at the UI routing boundary by `src/components/ProtectedRoute.tsx`.

#### Identity, Roles, and Onboarding
Authentication state is centralized in `src/contexts/AuthContext.tsx`; API-facing authentication concerns are isolated in `src/services/authService.ts` and facility-staff-specific auth in `src/services/facilityStaffAuthService.ts`. Registration is role-specific, including `src/pages/RegisterMother.tsx`, `src/pages/RegisterHealthWorker.tsx`, and `src/pages/RegisterFacilityAdmin.tsx`.

OTP, profile-photo, and role-selection dialogs support the identity/onboarding journey: `src/components/VerifyOTPModal.tsx`, `src/components/PhotoOnboardingModal.tsx`, `src/components/ui/RoleSelectionModal.tsx`.

#### Role-Specific Care Workflows
Dashboards are the principal operational views, tailored to each actor:
- Mother self-service, pregnancy status, facility discovery/booking: `src/components/mother/ModernMotherDashboard.tsx`, `src/components/mother/PregnancyJourneyTracker.tsx`, `src/components/mother/FacilityBookingCard.tsx`
- CHW caseload and mother monitoring: `src/components/chw/EnhancedCHWDashboard.tsx`, `src/components/chw/CHWProfile.tsx`
- Nurse supervisory workflow: `src/components/nurse/EnhancedNurseDashboard.tsx`, `src/components/nurse/NurseProfile.tsx`
- Facility operations: `src/components/facility/FacilityDashboard.tsx`

Shared navigation/layout components establish the authenticated application frame: `src/components/layout/Layout.tsx`, `src/components/layout/Navigation.tsx`, `src/components/layout/Sidebar.tsx`.

#### Service and API Boundary
Domain services encapsulate calls to the backend, with common client behavior in `src/lib/apiClient.ts`. Major care-domain boundaries include:
- Mother records and check-ins: `src/services/motherService.ts`, `src/services/checkinService.ts`
- CHW assignment and escalation: `src/services/assignmentService.ts`, `src/services/escalationService.ts`
- Facility appointments and facility escalations: `src/services/appointmentService.ts`, `src/services/facilityAppointmentService.ts`, `src/services/facilityEscalationService.ts`
- Supporting clinical data: `src/services/nutritionService.ts`, `src/services/weightService.ts`, `src/services/ultrasoundService.ts`

The primary flow is UI/dashboard → domain service → `apiClient` → FastAPI/PostgreSQL, with responses driving role-specific state and presentation.

#### Real-Time Notifications and External Services
Socket lifecycle/state is centralized in `src/contexts/SocketContext.tsx`, backed by `src/lib/socketClient.ts`; consumers use `src/hooks/useSocket.ts` and facility-specific `src/hooks/useFacilitySocket.ts`. This is the real-time boundary for alerts and workflow updates, alongside `src/services/notificationService.ts` and `src/components/ConnectionBanner.tsx`.

Firebase is separately integrated through `src/lib/firebaseClient.ts`; the browser push worker is `public/firebase-messaging-sw.js`. This implies Firebase Cloud Messaging for push notification delivery, while sockets serve live in-app updates.

#### UI and Deployment Boundaries
Reusable accessible UI primitives are housed under `src/components/ui/`, while responsive behavior is concentrated in `src/hooks/use-mobile.tsx`, `src/components/ui/HamburgerButton.tsx`, and `src/components/ui/MobileMenuPanel.tsx`. Build/runtime configuration is Vite-based: `vite.config.ts`, `package.json`, and `tailwind.config.ts`. CI and security automation are defined in `.github/workflows/ci.yml` and `.github/workflows/security.yml`.

Main entry points: [`src/contexts/SocketContext.tsx`](https://github.com/anto-remy/remy-care-connect/blob/main/src/contexts/SocketContext.tsx) (Socket state), [`src/components/layout/Layout.tsx`](https://github.com/anto-remy/remy-care-connect/blob/main/src/components/layout/Layout.tsx) (Authenticated layout), [`src/services/motherService.ts`](https://github.com/anto-remy/remy-care-connect/blob/main/src/services/motherService.ts) (Care domain services), [`src/App.tsx`](https://github.com/anto-remy/remy-care-connect/blob/main/src/App.tsx) (App and routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Browser application"]
  node_html["HTML entry<br/>entry point<br/>[index.html]"]
  node_main["React bootstrap<br/>entry point<br/>[main.tsx]"]
  node_app_shell["App and routes<br/>application shell<br/>[App.tsx]"]
  node_protected_route["Protected route<br/>route guard<br/>[ProtectedRoute.tsx]"]
  node_public_auth["Public and auth pages<br/>page flows<br/>[Login.tsx]"]
  node_auth_context["Auth state<br/>React context<br/>[AuthContext.tsx]"]
  node_onboarding["Onboarding dialogs<br/>UI flow<br/>[VerifyOTPModal.tsx]"]
  node_mother_ui["Mother care UI<br/>role dashboard"]
  node_chw_ui["CHW care UI<br/>role dashboard"]
  node_nurse_ui["Nurse care UI<br/>role dashboard"]
  node_facility_ui["Facility operations UI<br/>role dashboard"]
  node_authenticated_layout["Authenticated layout<br/>shared layout<br/>[Layout.tsx]"]
  node_push_worker["Push service worker<br/>browser worker"]
end

subgraph group_services["Frontend service boundary"]
  node_care_services["Care domain services<br/>service layer<br/>[motherService.ts]"]
  node_auth_services["Authentication services<br/>service layer<br/>[authService.ts]"]
  node_api_client["API client<br/>HTTP client<br/>[apiClient.ts]"]
  node_socket_context["Socket state<br/>React context<br/>[SocketContext.tsx]"]
  node_socket_client["Socket client<br/>realtime client<br/>[socketClient.ts]"]
  node_notifications["Notification delivery<br/>notification integration"]
end

subgraph group_external["External platforms"]
  node_fastapi[("FastAPI and PostgreSQL<br/>backend boundary")]
  node_firebase["Firebase Cloud Messaging<br/>push platform<br/>[firebaseClient.ts]"]
end

subgraph group_delivery["Build and delivery"]
  node_ci["CI workflow<br/>automation<br/>[ci.yml]"]
  node_security["Security workflow<br/>automation<br/>[security.yml]"]
end

node_html -->|"loads"| node_main
node_main -->|"mounts"| node_app_shell
node_app_shell -->|"routes public users"| node_public_auth
node_app_shell -->|"guards app routes"| node_protected_route
node_protected_route -->|"admits authenticated users"| node_authenticated_layout
node_authenticated_layout -->|"hosts"| node_mother_ui
node_authenticated_layout -->|"hosts"| node_chw_ui
node_authenticated_layout -->|"hosts"| node_nurse_ui
node_authenticated_layout -->|"hosts"| node_facility_ui
node_public_auth -->|"continues registration"| node_onboarding
node_public_auth -->|"updates identity"| node_auth_context
node_auth_context -->|"authenticates through"| node_auth_services
node_auth_services -->|"uses"| node_api_client
node_mother_ui -->|"care actions"| node_care_services
node_chw_ui -->|"care actions"| node_care_services
node_nurse_ui -->|"care actions"| node_care_services
node_facility_ui -->|"care actions"| node_care_services
node_care_services -->|"uses"| node_api_client
node_api_client -->|"HTTP API"| node_fastapi
node_socket_context -->|"manages"| node_socket_client
node_socket_client -->|"live updates"| node_fastapi
node_socket_context -->|"alerts and updates"| node_mother_ui
node_socket_context -->|"alerts and updates"| node_chw_ui
node_socket_context -->|"alerts and updates"| node_nurse_ui
node_socket_context -->|"alerts and updates"| node_facility_ui
node_notifications -->|"push delivery"| node_firebase
node_firebase -->|"invokes"| node_push_worker

click node_html "https://github.com/anto-remy/remy-care-connect/blob/main/index.html"
click node_main "https://github.com/anto-remy/remy-care-connect/blob/main/src/main.tsx"
click node_app_shell "https://github.com/anto-remy/remy-care-connect/blob/main/src/App.tsx"
click node_protected_route "https://github.com/anto-remy/remy-care-connect/blob/main/src/components/ProtectedRoute.tsx"
click node_public_auth "https://github.com/anto-remy/remy-care-connect/blob/main/src/pages/Login.tsx"
click node_auth_context "https://github.com/anto-remy/remy-care-connect/blob/main/src/contexts/AuthContext.tsx"
click node_onboarding "https://github.com/anto-remy/remy-care-connect/blob/main/src/components/VerifyOTPModal.tsx"
click node_mother_ui "https://github.com/anto-remy/remy-care-connect/blob/main/src/components/mother/ModernMotherDashboard.tsx"
click node_chw_ui "https://github.com/anto-remy/remy-care-connect/blob/main/src/components/chw/EnhancedCHWDashboard.tsx"
click node_nurse_ui "https://github.com/anto-remy/remy-care-connect/blob/main/src/components/nurse/EnhancedNurseDashboard.tsx"
click node_facility_ui "https://github.com/anto-remy/remy-care-connect/blob/main/src/components/facility/FacilityDashboard.tsx"
click node_authenticated_layout "https://github.com/anto-remy/remy-care-connect/blob/main/src/components/layout/Layout.tsx"
click node_care_services "https://github.com/anto-remy/remy-care-connect/blob/main/src/services/motherService.ts"
click node_auth_services "https://github.com/anto-remy/remy-care-connect/blob/main/src/services/authService.ts"
click node_api_client "https://github.com/anto-remy/remy-care-connect/blob/main/src/lib/apiClient.ts"
click node_socket_context "https://github.com/anto-remy/remy-care-connect/blob/main/src/contexts/SocketContext.tsx"
click node_socket_client "https://github.com/anto-remy/remy-care-connect/blob/main/src/lib/socketClient.ts"
click node_notifications "https://github.com/anto-remy/remy-care-connect/blob/main/src/services/notificationService.ts"
click node_firebase "https://github.com/anto-remy/remy-care-connect/blob/main/src/lib/firebaseClient.ts"
click node_push_worker "https://github.com/anto-remy/remy-care-connect/blob/main/public/firebase-messaging-sw.js"
click node_ci "https://github.com/anto-remy/remy-care-connect/blob/main/.github/workflows/ci.yml"
click node_security "https://github.com/anto-remy/remy-care-connect/blob/main/.github/workflows/security.yml"

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_html,node_main,node_app_shell,node_protected_route,node_public_auth,node_auth_context,node_onboarding,node_mother_ui,node_chw_ui,node_nurse_ui,node_facility_ui,node_authenticated_layout,node_push_worker toneBlue
class node_care_services,node_auth_services,node_api_client,node_socket_context,node_socket_client,node_notifications toneAmber
class node_fastapi,node_firebase toneMint
class node_ci,node_security toneRose
```

## Components

### Browser application

React/Vite SPA and role-specific workflows.

- [HTML entry](https://github.com/anto-remy/remy-care-connect/blob/main/index.html): entry point · `index.html`
- [React bootstrap](https://github.com/anto-remy/remy-care-connect/blob/main/src/main.tsx): entry point · `src/main.tsx`
- [App and routes](https://github.com/anto-remy/remy-care-connect/blob/main/src/App.tsx): application shell · Composes public and role-specific route surfaces. · `src/App.tsx`
- [Protected route](https://github.com/anto-remy/remy-care-connect/blob/main/src/components/ProtectedRoute.tsx): route guard · Enforces authenticated UI access. · `src/components/ProtectedRoute.tsx`
- [Public and auth pages](https://github.com/anto-remy/remy-care-connect/blob/main/src/pages/Login.tsx): page flows · Landing, login, role selection, and registration. · `src/pages/Login.tsx`
- [Auth state](https://github.com/anto-remy/remy-care-connect/blob/main/src/contexts/AuthContext.tsx): React context · Centralized identity and role state. · `src/contexts/AuthContext.tsx`
- [Onboarding dialogs](https://github.com/anto-remy/remy-care-connect/blob/main/src/components/VerifyOTPModal.tsx): UI flow · OTP, photo, and role-selection dialogs. · `src/components/VerifyOTPModal.tsx`
- [Mother care UI](https://github.com/anto-remy/remy-care-connect/blob/main/src/components/mother/ModernMotherDashboard.tsx): role dashboard · Self-service, pregnancy tracking, and facility booking. · `src/components/mother/ModernMotherDashboard.tsx`
- [CHW care UI](https://github.com/anto-remy/remy-care-connect/blob/main/src/components/chw/EnhancedCHWDashboard.tsx): role dashboard · Caseload and mother monitoring workflow. · `src/components/chw/EnhancedCHWDashboard.tsx`
- [Nurse care UI](https://github.com/anto-remy/remy-care-connect/blob/main/src/components/nurse/EnhancedNurseDashboard.tsx): role dashboard · Supervisory care workflow. · `src/components/nurse/EnhancedNurseDashboard.tsx`
- [Facility operations UI](https://github.com/anto-remy/remy-care-connect/blob/main/src/components/facility/FacilityDashboard.tsx): role dashboard · `src/components/facility/FacilityDashboard.tsx`
- [Authenticated layout](https://github.com/anto-remy/remy-care-connect/blob/main/src/components/layout/Layout.tsx): shared layout · Navigation frame for signed-in role surfaces. · `src/components/layout/Layout.tsx`
- [Push service worker](https://github.com/anto-remy/remy-care-connect/blob/main/public/firebase-messaging-sw.js): browser worker · `public/firebase-messaging-sw.js`

### Frontend service boundary

Domain calls and real-time client integration.

- [Care domain services](https://github.com/anto-remy/remy-care-connect/blob/main/src/services/motherService.ts): service layer · Mother, check-in, assignment, escalation, appointment, and clinical-data APIs. · `src/services/motherService.ts`
- [Authentication services](https://github.com/anto-remy/remy-care-connect/blob/main/src/services/authService.ts): service layer · Authentication and facility-staff authentication APIs. · `src/services/authService.ts`
- [API client](https://github.com/anto-remy/remy-care-connect/blob/main/src/lib/apiClient.ts): HTTP client · Common backend request behavior. · `src/lib/apiClient.ts`
- [Socket state](https://github.com/anto-remy/remy-care-connect/blob/main/src/contexts/SocketContext.tsx): React context · Centralized live-update lifecycle and state. · `src/contexts/SocketContext.tsx`
- [Socket client](https://github.com/anto-remy/remy-care-connect/blob/main/src/lib/socketClient.ts): realtime client · `src/lib/socketClient.ts`
- [Notification delivery](https://github.com/anto-remy/remy-care-connect/blob/main/src/services/notificationService.ts): notification integration · In-app notification service and Firebase messaging integration. · `src/services/notificationService.ts`

### External platforms

Backend and push-delivery boundaries outside this repository.

- **FastAPI and PostgreSQL**: backend boundary · External API and persistent care-data service.
- [Firebase Cloud Messaging](https://github.com/anto-remy/remy-care-connect/blob/main/src/lib/firebaseClient.ts): push platform · External browser push delivery. · `src/lib/firebaseClient.ts`

### Build and delivery

- [CI workflow](https://github.com/anto-remy/remy-care-connect/blob/main/.github/workflows/ci.yml): automation · `.github/workflows/ci.yml`
- [Security workflow](https://github.com/anto-remy/remy-care-connect/blob/main/.github/workflows/security.yml): automation · `.github/workflows/security.yml`

## Connections

- HTML entry → React bootstrap: loads
- React bootstrap → App and routes: mounts
- App and routes → Public and auth pages: routes public users
- App and routes → Protected route: guards app routes
- Protected route → Authenticated layout: admits authenticated users
- Authenticated layout → Mother care UI: hosts
- Authenticated layout → CHW care UI: hosts
- Authenticated layout → Nurse care UI: hosts
- Authenticated layout → Facility operations UI: hosts
- Public and auth pages → Onboarding dialogs: continues registration
- Public and auth pages → Auth state: updates identity
- Auth state → Authentication services: authenticates through
- Authentication services → API client: uses
- Mother care UI → Care domain services: care actions
- CHW care UI → Care domain services: care actions
- Nurse care UI → Care domain services: care actions
- Facility operations UI → Care domain services: care actions
- Care domain services → API client: uses
- API client → FastAPI and PostgreSQL: HTTP API
- Socket state → Socket client: manages
- Socket client → FastAPI and PostgreSQL: live updates
- Socket state → Mother care UI: alerts and updates
- Socket state → CHW care UI: alerts and updates
- Socket state → Nurse care UI: alerts and updates
- Socket state → Facility operations UI: alerts and updates
- Notification delivery → Firebase Cloud Messaging: push delivery
- Firebase Cloud Messaging → Push service worker: invokes