# lasuss/medihouse architecture

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

- Interactive diagram: https://gitdiagram.com/lasuss/medihouse
- Repository: https://github.com/lasuss/medihouse

## Overview

1. **System shape**
   - MediHouse is a **Flutter mobile app** backed by **Supabase** and augmented with **Firebase Cloud Messaging** for push notifications.
   - The repository is split into three architectural layers: the **Flutter client** (`lib/`), the **backend/database provisioning** (`database/`, `supabase/`, `docs/`), and the **platform wrappers** for Android/iOS (`android/`, `ios/`).

2. **Client entry point and app shell**
   - The runtime starts in `lib/main.dart`, which likely initializes Supabase/Firebase, loads environment config from `.env`, and sets up routing.
   - `lib/Widgets/AppShell.dart` and `lib/menus/bottom_navigation.dart` suggest a shared application frame used after login, with role-specific navigation and consistent layout across screens.

3. **Role-based frontend architecture**
   - The UI is organized by user role:
     - `patient/`
     - `doctor/`
     - `receptionist/`
     - `admin/`
     - `pharmacy/`
   - This is a strong boundary in the architecture: each role gets its own dashboard and task screens, while shared components live outside those folders.

4. **Authentication and user state**
   - `lib/Widgets/login.dart`, `register.dart`, and `lib/enroll/UserRole.dart` indicate an onboarding/auth flow that determines the user’s role.
   - `lib/helpers/UserManager.dart` acts as the app’s central session/user-state singleton, likely holding current user identity, role, and session-derived access data.
   - Supabase Auth is the main authentication boundary, with role-based access control enforced at the app and database level.

5. **Routing and screen composition**
   - `lib/helpers/routers.dart` is the main navigation boundary.
   - The app appears to route users into different dashboards and nested feature screens based on authentication state and role, rather than using one monolithic UI flow.

6. **Domain-specific subsystems**
   - The repository models healthcare workflows as separate feature areas:
     - **Appointments/booking**: `PatientBooking`, `PatientAppointment`, `DoctorSchedule`
     - **Medical records**: `PatientRecordDetail`, `DoctorRecordDetail`, `DoctorRecordDetailEdit`
     - **Profiles**: patient, doctor, receptionist, and edit/profile-detail screens
     - **Messaging and notifications**: role-specific message and notification screens
     - **Help/policy content**: help center, privacy policy, terms of service
   - This indicates a screen-driven architecture where each clinical workflow is encapsulated in its own feature folder.

7. **Shared domain models**
   - `lib/Widgets/model/` contains data objects such as `Appointment`, `Inventory`, `Medicine`, `Message`, and `Prescription`.
   - These models are the bridge between Supabase records and UI screens, and likely represent the main entities flowing through the app.
   - `PatientChatScreen.dart` under the model folder suggests chat is treated as a reusable feature tied to the message model.

8. **Operational workflows in the app**
   - The main user journeys are:
     - login/register → resolve role → dashboard
     - booking/triage → appointment scheduling
     - profile/record lookup → detailed record view or edit
     - QR/National ID scan → patient or prescription identification
   - The QR and ID scanning screens in both patient and doctor areas show that identity capture is a recurring integration point in the app.

9. **Backend and database layer**
   - Supabase is the central backend runtime: database, auth, and likely row-level authorization.
   - `database/supabase_setup.sql`, `database/supabase_auth_trigger.sql`, and the docs in `docs/` imply the schema is provisioned through SQL scripts and documented separately.
   - `docs/database_overview.md` and `docs/database_full_reference.md` suggest the database is a first-class part of the system design, not an opaque external dependency.

10. **Notification pipeline**
   - `lib/helpers/NotificationService.dart` plus `supabase/functions/push-notification/index.ts` show a two-part notification architecture:
     - the Flutter client receives and displays notifications
     - a Supabase Edge Function sends push notifications via Firebase
   - This is the main asynchronous cross-system flow in the repo: backend event → edge function → Firebase FCM → device.

11. **Administrative and operational boundaries**
   - Admin screens (`AdminDashboard`, `AdminUserManagement`) imply centralized governance over users and system data.
   - Pharmacy screens (`PharmacyPending`, `PharmacyFilled`, `PharmacyInventory`) isolate medication fulfillment from clinical workflows.
   - Receptionist screens manage triage and coordination, acting as an operational bridge between patients and clinicians.

12. **Platform and build boundaries**
   - `android/` and `ios/` are standard Flutter host apps, meaning the business architecture lives almost entirely in Dart while native code remains thin.
   - Native code is mainly for app bootstrapping and platform packaging, not domain logic.

13. **What to show in an architecture diagram**
   - A useful diagram should center on:
     - **Flutter client**
     - **Role-based feature modules**
     - **Shared auth/session/router helpers**
     - **Supabase Auth + PostgreSQL**
     - **Supabase Edge Function for notifications**
     - **Firebase Cloud Messaging**
     - **SQL/database provisioning scripts and documentation**
   - The key flows are auth/role resolution, CRUD-style healthcare data access, QR-based identification, and asynchronous push notifications.

Main entry points: [`lib/Widgets/AppShell.dart`](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/AppShell.dart) (App Shell), [`lib/main.dart`](https://github.com/lasuss/medihouse/blob/master/lib/main.dart) (Main), [`database/supabase_setup.sql`](https://github.com/lasuss/medihouse/blob/master/database/supabase_setup.sql) (Supabase), [`lib/Widgets/patient/PatientDashboard.dart`](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/patient/PatientDashboard.dart) (Patient Space)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter client"]
  node_main(("Main<br/>entrypoint<br/>[main.dart]"))
  node_routers["Router<br/>navigation<br/>[routers.dart]"]
  node_shell["App Shell<br/>ui shell<br/>[AppShell.dart]"]
  node_session["User Manager<br/>session state<br/>[UserManager.dart]"]
  node_auth["Login & Register<br/>auth flow<br/>[login.dart]"]
  node_role["User Role<br/>onboarding<br/>[UserRole.dart]"]
  node_models[("Domain Models<br/>shared models<br/>[Appointment.dart]")]
  node_scan["Scan Tools<br/>identity capture<br/>[CCCDScanner.dart]"]
  node_notify["Notifications<br/>client service"]
  node_patient["Patient Space<br/>feature area"]
  node_doctor["Doctor Space<br/>feature area"]
  node_reception["Receptionist Space<br/>feature area"]
  node_admin["Admin Space<br/>feature area"]
  node_pharmacy["Pharmacy Space<br/>feature area"]
end

subgraph group_backend["Backend & data"]
  node_supabase[("Supabase<br/>backend runtime<br/>[supabase_setup.sql]")]
  node_schema["DB Setup<br/>sql provisioning"]
  node_docs["DB Docs<br/>reference"]
  node_edgefn["Push Function<br/>edge function<br/>[index.ts]"]
  node_fcm(("Firebase FCM<br/>push service"))
end

subgraph group_platform["Native shells"]
  node_android["Android Host<br/>native shell<br/>[MainActivity.kt]"]
  node_ios["iOS Host<br/>native shell<br/>[AppDelegate.swift]"]
end

node_main -->|"boots"| node_routers
node_main -->|"initializes"| node_session
node_main -->|"connects"| node_supabase
node_main -->|"registers"| node_notify
node_auth -->|"resolves"| node_role
node_role -->|"stores"| node_session
node_routers -->|"enters"| node_shell
node_shell -->|"hosts"| node_patient
node_shell -->|"hosts"| node_doctor
node_shell -->|"hosts"| node_reception
node_shell -->|"hosts"| node_admin
node_shell -->|"hosts"| node_pharmacy
node_patient -->|"uses"| node_models
node_doctor -->|"uses"| node_models
node_reception -->|"uses"| node_models
node_admin -->|"governs"| node_supabase
node_pharmacy -->|"fulfills"| node_supabase
node_scan -->|"supports"| node_patient
node_scan -->|"supports"| node_doctor
node_notify -->|"receives"| node_edgefn
node_edgefn -->|"sends"| node_fcm
node_supabase -->|"provisioned by"| node_schema
node_supabase -->|"documented by"| node_docs
node_android -->|"launches"| node_main
node_ios -->|"launches"| node_main

click node_main "https://github.com/lasuss/medihouse/blob/master/lib/main.dart"
click node_routers "https://github.com/lasuss/medihouse/blob/master/lib/helpers/routers.dart"
click node_shell "https://github.com/lasuss/medihouse/blob/master/lib/Widgets/AppShell.dart"
click node_session "https://github.com/lasuss/medihouse/blob/master/lib/helpers/UserManager.dart"
click node_auth "https://github.com/lasuss/medihouse/blob/master/lib/Widgets/login.dart"
click node_role "https://github.com/lasuss/medihouse/blob/master/lib/enroll/UserRole.dart"
click node_models "https://github.com/lasuss/medihouse/blob/master/lib/Widgets/model/Appointment.dart"
click node_scan "https://github.com/lasuss/medihouse/blob/master/lib/Widgets/common/CCCDScanner.dart"
click node_notify "https://github.com/lasuss/medihouse/blob/master/lib/helpers/NotificationService.dart"
click node_patient "https://github.com/lasuss/medihouse/blob/master/lib/Widgets/patient/PatientDashboard.dart"
click node_doctor "https://github.com/lasuss/medihouse/blob/master/lib/Widgets/doctor/DoctorDashboard.dart"
click node_reception "https://github.com/lasuss/medihouse/blob/master/lib/Widgets/receptionist/ReceptionistDashboard.dart"
click node_admin "https://github.com/lasuss/medihouse/blob/master/lib/Widgets/admin/AdminDashboard.dart"
click node_pharmacy "https://github.com/lasuss/medihouse/blob/master/lib/Widgets/pharmacy/PharmacyInventory.dart"
click node_supabase "https://github.com/lasuss/medihouse/blob/master/database/supabase_setup.sql"
click node_schema "https://github.com/lasuss/medihouse/blob/master/database/supabase_auth_trigger.sql"
click node_docs "https://github.com/lasuss/medihouse/blob/master/docs/database_overview.md"
click node_edgefn "https://github.com/lasuss/medihouse/blob/master/supabase/functions/push-notification/index.ts"
click node_android "https://github.com/lasuss/medihouse/blob/master/android/app/src/main/kotlin/com/example/medi_house/MainActivity.kt"
click node_ios "https://github.com/lasuss/medihouse/blob/master/ios/Runner/AppDelegate.swift"

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_main,node_routers,node_shell,node_session,node_auth,node_role,node_models,node_scan,node_notify,node_patient,node_doctor,node_reception,node_admin,node_pharmacy toneBlue
class node_supabase,node_schema,node_docs,node_edgefn,node_fcm toneAmber
class node_android,node_ios toneMint
```

## Components

### Flutter client

Dart app runtime, feature screens, shared state, and navigation.

- [Main](https://github.com/lasuss/medihouse/blob/master/lib/main.dart): entrypoint · App startup and initial service wiring. · `lib/main.dart`
- [Router](https://github.com/lasuss/medihouse/blob/master/lib/helpers/routers.dart): navigation · Central route and role-based screen selection. · `lib/helpers/routers.dart`
- [App Shell](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/AppShell.dart): ui shell · Shared logged-in frame and bottom navigation. · `lib/Widgets/AppShell.dart`
- [User Manager](https://github.com/lasuss/medihouse/blob/master/lib/helpers/UserManager.dart): session state · Central user/session singleton for identity and role state. · `lib/helpers/UserManager.dart`
- [Login & Register](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/login.dart): auth flow · Sign-in, registration, and onboarding entry screens. · `lib/Widgets/login.dart`
- [User Role](https://github.com/lasuss/medihouse/blob/master/lib/enroll/UserRole.dart): onboarding · Role selection and enrollment boundary. · `lib/enroll/UserRole.dart`
- [Domain Models](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/model/Appointment.dart): shared models · Core app entities shared across features and backend records. · `lib/Widgets/model/Appointment.dart`
- [Scan Tools](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/common/CCCDScanner.dart): identity capture · Shared QR and national ID scanning capability. · `lib/Widgets/common/CCCDScanner.dart`
- [Notifications](https://github.com/lasuss/medihouse/blob/master/lib/helpers/NotificationService.dart): client service · Client-side notification display and handling. · `lib/helpers/NotificationService.dart`
- [Patient Space](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/patient/PatientDashboard.dart): feature area · Patient dashboard, booking, records, profile, and policy screens. · `lib/Widgets/patient/PatientDashboard.dart`
- [Doctor Space](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/doctor/DoctorDashboard.dart): feature area · Doctor dashboard, records, schedule, chat, and scan flows. · `lib/Widgets/doctor/DoctorDashboard.dart`
- [Receptionist Space](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/receptionist/ReceptionistDashboard.dart): feature area · Reception and triage coordination screens. · `lib/Widgets/receptionist/ReceptionistDashboard.dart`
- [Admin Space](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/admin/AdminDashboard.dart): feature area · Administrative dashboard and user management. · `lib/Widgets/admin/AdminDashboard.dart`
- [Pharmacy Space](https://github.com/lasuss/medihouse/blob/master/lib/Widgets/pharmacy/PharmacyInventory.dart): feature area · Medication fulfillment and inventory screens. · `lib/Widgets/pharmacy/PharmacyInventory.dart`

### Backend & data

Supabase auth, database setup, edge functions, and schema docs.

- [Supabase](https://github.com/lasuss/medihouse/blob/master/database/supabase_setup.sql): backend runtime · Backend auth and database platform. · `database/supabase_setup.sql`
- [DB Setup](https://github.com/lasuss/medihouse/blob/master/database/supabase_auth_trigger.sql): sql provisioning · Schema and auth trigger provisioning scripts. · `database/supabase_auth_trigger.sql`
- [DB Docs](https://github.com/lasuss/medihouse/blob/master/docs/database_overview.md): reference · Database overview and full reference documentation. · `docs/database_overview.md`
- [Push Function](https://github.com/lasuss/medihouse/blob/master/supabase/functions/push-notification/index.ts): edge function · Supabase Edge Function that sends push notifications. · `supabase/functions/push-notification/index.ts`
- **Firebase FCM**: push service · External push notification delivery channel.

### Native shells

Android and iOS host projects for packaging and bootstrapping.

- [Android Host](https://github.com/lasuss/medihouse/blob/master/android/app/src/main/kotlin/com/example/medi_house/MainActivity.kt): native shell · Android packaging and platform bootstrap layer. · `android/app/src/main/kotlin/com/example/medi_house/MainActivity.kt`
- [iOS Host](https://github.com/lasuss/medihouse/blob/master/ios/Runner/AppDelegate.swift): native shell · iOS packaging and platform bootstrap layer. · `ios/Runner/AppDelegate.swift`

## Connections

- Main → Router: boots · Startup hands control to routing and app flow selection.
- Main → User Manager: initializes · App startup loads or creates session state.
- Main → Supabase: connects · Client initializes Supabase services for auth and data access.
- Main → Notifications: registers · Client sets up local notification handling.
- Login & Register → User Role: resolves · Authentication flow determines the user's role.
- User Role → User Manager: stores · Selected role is persisted in session state.
- Router → App Shell: enters · Authenticated users are routed into the shared app shell.
- App Shell → Patient Space: hosts · Shared shell renders patient workflows.
- App Shell → Doctor Space: hosts · Shared shell renders doctor workflows.
- App Shell → Receptionist Space: hosts · Shared shell renders receptionist workflows.
- App Shell → Admin Space: hosts · Shared shell renders admin workflows.
- App Shell → Pharmacy Space: hosts · Shared shell renders pharmacy workflows.
- Patient Space → Domain Models: uses · Patient screens read and write shared domain entities.
- Doctor Space → Domain Models: uses · Doctor screens read and write shared domain entities.
- Receptionist Space → Domain Models: uses · Reception workflows operate on shared records and appointments.
- Admin Space → Supabase: governs · Admin workflows depend on backend-authored user and data state.
- Pharmacy Space → Supabase: fulfills · Pharmacy workflows manage fulfillment and inventory records.
- Scan Tools → Patient Space: supports · Patient identity capture is used in patient flows.
- Scan Tools → Doctor Space: supports · Patient identity capture is used in doctor flows.
- Notifications → Push Function: receives · Client-side notifications are triggered by backend push events.
- Push Function → Firebase FCM: sends · Edge function forwards push payloads to Firebase Cloud Messaging.
- Supabase → DB Setup: provisioned by · Backend setup is defined through SQL scripts.
- Supabase → DB Docs: documented by · Database behavior and structure are described in repo docs.
- Android Host → Main: launches · Android host starts the Flutter runtime.
- iOS Host → Main: launches · iOS host starts the Flutter runtime.
