# chxb07/mediflow-ai architecture

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

- Interactive diagram: https://gitdiagram.com/chxb07/mediflow-ai
- Repository: https://github.com/chxb07/mediflow-ai

## Overview

1. **Overall shape**
   - This is a **single-page React application** built with **Vite + TypeScript**, styled with **Tailwind CSS** and a large **shadcn/ui** component set.
   - Architecturally, it is a **client UI** that delegates persistence, identity, storage, and role enforcement to **Supabase**, with AI-assisted workflows routed through a separate **Groq** integration.

2. **Primary user-facing entry points**
   - `src/pages/Landing.tsx`, `Auth.tsx`, `Index.tsx`, `Dashboard.tsx`, and `NotFound.tsx` form the top-level route targets.
   - The app likely starts at a public landing experience, then moves into authentication, then into a role-aware dashboard area.

3. **Role-based dashboard subsystem**
   - `src/pages/dashboards/DoctorDashboard.tsx`, `LabDashboard.tsx`, `PatientDashboard.tsx`, and `PharmacistDashboard.tsx` split the app by clinical role.
   - This is the core domain boundary: each dashboard represents a distinct workflow surface over shared backend data, rather than a generic one-size-fits-all UI.

4. **Shared UI and composition layer**
   - `src/components/` contains the app-specific building blocks: `Header`, `LanguageSwitcher`, `GlassCard`, `NavLink`, and `mode-toggle`.
   - `src/components/ui/` is the reusable design system layer, largely made up of shadcn-style primitives such as dialogs, forms, tables, sidebars, menus, toasts, and inputs.
   - This separation suggests a clean distinction between **domain-specific shell components** and **low-level UI primitives**.

5. **State, responsiveness, and feedback**
   - `src/hooks/use-mobile.tsx` handles viewport-aware behavior, while `src/hooks/use-toast.ts` plus the `toast/toaster` components provide app-wide notifications.
   - These are cross-cutting UI services used across pages and dashboards rather than business-specific logic.

6. **Platform services and integration layer**
   - `src/lib/supabase.ts` is the database/auth/storage gateway.
   - `src/lib/auth.ts` likely centralizes session and role checks.
   - `src/lib/ai-service.ts` is the AI boundary, encapsulating calls to Groq-hosted Llama 3.3 for clinical analysis/summarization.
   - `src/lib/i18n.ts` provides multilingual support, and `src/lib/utils.ts` holds shared helpers.

7. **Backend/data model boundary**
   - `supabase_schema.sql` and `supabase_setup.sql` indicate that a meaningful portion of the system’s behavior lives in the database layer: schema, access control, triggers, and storage policies.
   - The README notes **Supabase Auth**, **Row Level Security**, and automatic profile creation via triggers, which means authorization is enforced both in the UI and at the data layer.

8. **Main data flow**
   - A user authenticates through Supabase.
   - Their profile/role determines which dashboard is rendered.
   - Dashboards read and write clinical data through Supabase-backed APIs/tables.
   - Where needed, the doctor-facing flow calls `ai-service.ts` to generate analysis from clinical context.
   - Lab/pharmacy actions feed status updates back into Supabase so other roles see updated records.

9. **Storage and document workflow**
   - The README references a public Supabase storage bucket named `medical-results`.
   - That implies a document/report pipeline for lab or radiology outputs, with metadata and access rules managed in Supabase and file artifacts stored separately from relational records.

10. **Internationalization and theming**
   - The presence of `LanguageSwitcher`, `theme-provider`, and `mode-toggle` shows the UI is designed for **language switching** and **dark/light theme control** as first-class concerns.
   - These are client-side presentation concerns layered on top of the clinical workflows, not part of the domain backend.

11. **Testing and quality gates**
   - `vitest.config.ts`, `src/test/*`, and `playwright.config.ts` / `playwright-fixture.ts` show both **unit/integration testing** and **browser-level end-to-end testing**.
   - This is important architecturally because the app combines auth, role routing, and dashboard flows that need coverage across both component and full-browser layers.

12. **Deployment/runtime boundary**
   - `vercel.json` indicates a frontend deployment target on **Vercel**, while `index.html`, `vite.config.ts`, and `main.tsx` define a standard Vite SPA runtime.
   - The repo does not show a custom backend server; instead, the runtime model is a static/frontend app consuming external managed services.

13. **What to draw in an architecture diagram**
   - Show a **client SPA** in the center with three main internal zones: routing/pages, shared UI/system components, and service adapters.
   - Connect it outward to **Supabase** for auth/database/storage and to **Groq** for AI inference.
   - Add a separate **database/schema/RLS** boundary beneath Supabase, and a **testing/deployment** boundary around the app for Vitest, Playwright, and Vercel.

Main entry points: [`src/App.tsx`](https://github.com/chxb07/mediflow-ai/blob/main/src/App.tsx) (App shell), [`src/lib/supabase.ts`](https://github.com/chxb07/mediflow-ai/blob/main/src/lib/supabase.ts) (Supabase client), [`src/pages/Dashboard.tsx`](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/Dashboard.tsx) (Dashboard), [`src/pages/dashboards/DoctorDashboard.tsx`](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/dashboards/DoctorDashboard.tsx) (Doctor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client SPA"]
  node_app["App shell<br/>spa entry<br/>[App.tsx]"]
  node_main["Main entry<br/>runtime entry<br/>[main.tsx]"]
  node_landing["Landing<br/>public page<br/>[Landing.tsx]"]
  node_auth["Auth<br/>[Auth.tsx]"]
  node_indexpage["Index<br/>route page<br/>[Index.tsx]"]
  node_dashboard["Dashboard<br/>route gate<br/>[Dashboard.tsx]"]
  node_doctor["Doctor<br/>clinical dashboard"]
  node_lab["Lab<br/>clinical dashboard<br/>[LabDashboard.tsx]"]
  node_patient["Patient<br/>clinical dashboard"]
  node_pharmacist["Pharmacist<br/>clinical dashboard"]
  node_shell["UI shell<br/>app chrome<br/>[Header.tsx]"]
  node_designsystem["UI primitives<br/>component library<br/>[button.tsx]"]
  node_mobiletoast["Mobile & toast<br/>cross-cutting ui<br/>[use-mobile.tsx]"]
end

subgraph group_services["Platform Services"]
  node_supabase[("Supabase client<br/>data adapter<br/>[supabase.ts]")]
  node_authlib["Auth logic<br/>session roles<br/>[auth.ts]"]
  node_ai["AI service<br/>groq adapter<br/>[ai-service.ts]"]
  node_i18n["I18n<br/>localization<br/>[i18n.ts]"]
end

subgraph group_backend["Supabase Boundary"]
  node_supabase_schema["Schema"]
  node_supabase_setup["Setup<br/>sql bootstrap<br/>[supabase_setup.sql]"]
end

subgraph group_quality["Quality & Deploy"]
  node_tests["Vitest<br/>unit/integration<br/>[vitest.config.ts]"]
  node_e2e["Playwright<br/>browser e2e"]
  node_deploy["Vercel<br/>deployment<br/>[vercel.json]"]
end

node_main -->|"boots"| node_app
node_app -->|"routes"| node_landing
node_app -->|"routes"| node_auth
node_app -->|"routes"| node_indexpage
node_app -->|"routes"| node_dashboard
node_dashboard -->|"selects"| node_doctor
node_dashboard -->|"selects"| node_lab
node_dashboard -->|"selects"| node_patient
node_dashboard -->|"selects"| node_pharmacist
node_app -->|"composes"| node_shell
node_shell -->|"uses"| node_designsystem
node_app -->|"uses"| node_mobiletoast
node_app -->|"reads/writes"| node_supabase
node_authlib -->|"uses"| node_supabase
node_doctor -->|"calls"| node_ai
node_doctor -->|"guards"| node_authlib
node_lab -->|"updates"| node_supabase
node_patient -->|"reads"| node_supabase
node_pharmacist -->|"updates"| node_supabase
node_app -->|"localizes"| node_i18n
node_supabase -->|"backed by"| node_supabase_schema
node_supabase -->|"configured by"| node_supabase_setup
node_tests -.->|"covers"| node_app
node_e2e -.->|"covers"| node_app
node_deploy -->|"hosts"| node_app

click node_app "https://github.com/chxb07/mediflow-ai/blob/main/src/App.tsx"
click node_main "https://github.com/chxb07/mediflow-ai/blob/main/src/main.tsx"
click node_landing "https://github.com/chxb07/mediflow-ai/blob/main/src/pages/Landing.tsx"
click node_auth "https://github.com/chxb07/mediflow-ai/blob/main/src/pages/Auth.tsx"
click node_indexpage "https://github.com/chxb07/mediflow-ai/blob/main/src/pages/Index.tsx"
click node_dashboard "https://github.com/chxb07/mediflow-ai/blob/main/src/pages/Dashboard.tsx"
click node_doctor "https://github.com/chxb07/mediflow-ai/blob/main/src/pages/dashboards/DoctorDashboard.tsx"
click node_lab "https://github.com/chxb07/mediflow-ai/blob/main/src/pages/dashboards/LabDashboard.tsx"
click node_patient "https://github.com/chxb07/mediflow-ai/blob/main/src/pages/dashboards/PatientDashboard.tsx"
click node_pharmacist "https://github.com/chxb07/mediflow-ai/blob/main/src/pages/dashboards/PharmacistDashboard.tsx"
click node_shell "https://github.com/chxb07/mediflow-ai/blob/main/src/components/Header.tsx"
click node_designsystem "https://github.com/chxb07/mediflow-ai/blob/main/src/components/ui/button.tsx"
click node_mobiletoast "https://github.com/chxb07/mediflow-ai/blob/main/src/hooks/use-mobile.tsx"
click node_supabase "https://github.com/chxb07/mediflow-ai/blob/main/src/lib/supabase.ts"
click node_authlib "https://github.com/chxb07/mediflow-ai/blob/main/src/lib/auth.ts"
click node_ai "https://github.com/chxb07/mediflow-ai/blob/main/src/lib/ai-service.ts"
click node_i18n "https://github.com/chxb07/mediflow-ai/blob/main/src/lib/i18n.ts"
click node_supabase_schema "https://github.com/chxb07/mediflow-ai/blob/main/supabase_schema.sql"
click node_supabase_setup "https://github.com/chxb07/mediflow-ai/blob/main/supabase_setup.sql"
click node_tests "https://github.com/chxb07/mediflow-ai/blob/main/vitest.config.ts"
click node_e2e "https://github.com/chxb07/mediflow-ai/blob/main/playwright.config.ts"
click node_deploy "https://github.com/chxb07/mediflow-ai/blob/main/vercel.json"

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_app,node_main,node_landing,node_auth,node_indexpage,node_dashboard,node_doctor,node_lab,node_patient,node_pharmacist,node_shell,node_designsystem,node_mobiletoast toneBlue
class node_supabase,node_authlib,node_ai,node_i18n toneAmber
class node_supabase_schema,node_supabase_setup toneMint
class node_tests,node_e2e,node_deploy toneRose
```

## Components

### Client SPA

Vite React frontend with routed pages, shared UI, and cross-cutting client services.

- [App shell](https://github.com/chxb07/mediflow-ai/blob/main/src/App.tsx): spa entry · Top-level React application wiring routing, providers, and global composition. · `src/App.tsx`
- [Main entry](https://github.com/chxb07/mediflow-ai/blob/main/src/main.tsx): runtime entry · Bootstraps the SPA into the DOM. · `src/main.tsx`
- [Landing](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/Landing.tsx): public page · Public marketing or introduction screen. · `src/pages/Landing.tsx`
- [Auth](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/Auth.tsx): auth page · Authentication screen and sign-in flow. · `src/pages/Auth.tsx`
- [Index](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/Index.tsx): route page · Primary route target and redirect/entry page. · `src/pages/Index.tsx`
- [Dashboard](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/Dashboard.tsx): route gate · Role-aware dashboard entry that selects the appropriate clinical surface. · `src/pages/Dashboard.tsx`
- [Doctor](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/dashboards/DoctorDashboard.tsx): clinical dashboard · Physician workflow surface for review, analysis, and decision support. · `src/pages/dashboards/DoctorDashboard.tsx`
- [Lab](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/dashboards/LabDashboard.tsx): clinical dashboard · Laboratory workflow surface for results handling and status updates. · `src/pages/dashboards/LabDashboard.tsx`
- [Patient](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/dashboards/PatientDashboard.tsx): clinical dashboard · Patient-facing workflow surface for viewing records and results. · `src/pages/dashboards/PatientDashboard.tsx`
- [Pharmacist](https://github.com/chxb07/mediflow-ai/blob/main/src/pages/dashboards/PharmacistDashboard.tsx): clinical dashboard · Pharmacy workflow surface for medication and fulfillment tasks. · `src/pages/dashboards/PharmacistDashboard.tsx`
- [UI shell](https://github.com/chxb07/mediflow-ai/blob/main/src/components/Header.tsx): app chrome · App-specific layout and navigation components such as header, links, language, and theme controls. · `src/components/Header.tsx`
- [UI primitives](https://github.com/chxb07/mediflow-ai/blob/main/src/components/ui/button.tsx): component library · Reusable shadcn-style interface primitives used across the app. · `src/components/ui/button.tsx`
- [Mobile & toast](https://github.com/chxb07/mediflow-ai/blob/main/src/hooks/use-mobile.tsx): cross-cutting ui · Viewport responsiveness and global notification plumbing. · `src/hooks/use-mobile.tsx`

### Platform Services

Adapters for identity, persistence, AI, i18n, and shared helpers.

- [Supabase client](https://github.com/chxb07/mediflow-ai/blob/main/src/lib/supabase.ts): data adapter · Client gateway for auth, database, and storage access. · `src/lib/supabase.ts`
- [Auth logic](https://github.com/chxb07/mediflow-ai/blob/main/src/lib/auth.ts): session roles · Session handling and role checks for the clinical dashboards. · `src/lib/auth.ts`
- [AI service](https://github.com/chxb07/mediflow-ai/blob/main/src/lib/ai-service.ts): groq adapter · Encapsulates AI-assisted clinical analysis and summarization calls. · `src/lib/ai-service.ts`
- [I18n](https://github.com/chxb07/mediflow-ai/blob/main/src/lib/i18n.ts): localization · Language and translation support for the client UI. · `src/lib/i18n.ts`

### Supabase Boundary

Database schema, auth rules, storage, and setup scripts that back the app.

- [Schema](https://github.com/chxb07/mediflow-ai/blob/main/supabase_schema.sql): sql schema · Database tables, relations, and core data model. · `supabase_schema.sql`
- [Setup](https://github.com/chxb07/mediflow-ai/blob/main/supabase_setup.sql): sql bootstrap · Supabase provisioning, triggers, policies, and initial configuration. · `supabase_setup.sql`

### Quality & Deploy

Testing and deployment/runtime configuration around the SPA.

- [Vitest](https://github.com/chxb07/mediflow-ai/blob/main/vitest.config.ts): unit/integration · Fast automated tests for application logic and components. · `vitest.config.ts`
- [Playwright](https://github.com/chxb07/mediflow-ai/blob/main/playwright.config.ts): browser e2e · End-to-end browser test harness for routed and role-based flows. · `playwright.config.ts`
- [Vercel](https://github.com/chxb07/mediflow-ai/blob/main/vercel.json): deployment · Frontend deployment target and runtime hosting configuration. · `vercel.json`

## Connections

- Main entry → App shell: boots · Bootstraps the React application shell.
- App shell → Landing: routes · Public entry route.
- App shell → Auth: routes · Authentication route.
- App shell → Index: routes · Primary index route.
- App shell → Dashboard: routes · Role-aware dashboard gate.
- Dashboard → Doctor: selects · Doctor workflow surface.
- Dashboard → Lab: selects · Lab workflow surface.
- Dashboard → Patient: selects · Patient workflow surface.
- Dashboard → Pharmacist: selects · Pharmacist workflow surface.
- App shell → UI shell: composes · Shared chrome and navigation.
- UI shell → UI primitives: uses · Builds on reusable UI primitives.
- App shell → Mobile & toast: uses · Shared responsiveness and notifications.
- App shell → Supabase client: reads/writes · Client data and session access.
- Auth logic → Supabase client: uses · Session and role checks rely on Supabase auth state.
- Doctor → AI service: calls · Doctor-facing AI assistance and summarization.
- Doctor → Auth logic: guards · Role-based access and session checks.
- Lab → Supabase client: updates · Writes clinical status and result data.
- Patient → Supabase client: reads · Fetches patient records and results.
- Pharmacist → Supabase client: updates · Maintains fulfillment and medication state.
- App shell → I18n: localizes · Language-aware client presentation.
- Supabase client → Schema: backed by · Relational model and stored clinical data.
- Supabase client → Setup: configured by · Provisioning, policies, and triggers.
- Vitest → App shell: covers · Unit and integration coverage for the SPA.
- Playwright → App shell: covers · Browser-level routing and role flows.
- Vercel → App shell: hosts · Frontend runtime and deployment target.
