# arafat-yasin-2413/health-sync architecture

> Architecture diagram of the GitHub repository arafat-yasin-2413/health-sync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arafat-yasin-2413/health-sync
- Repository: https://github.com/arafat-yasin-2413/health-sync

## Overview

1. **Application shape**
   HealthSync is a **Next.js App Router** application built as a multi-portal healthcare front end. The top-level routes are split into **Home**, **Admin**, **Doctor**, and **Patient** views, with the patient flow appearing to be the primary product path.

2. **Primary user journey**
   The main flow is: user lands on the home page, chooses a portal card, enters the patient area, uploads a medical document, and gets structured clinical data extracted from that document. The architecture is optimized around this document-to-data conversion workflow.

3. **Route and page boundaries**
   Route entry points live under `src/app/`:
   - `/` for the main landing page
   - `/admin`
   - `/doctor`
   - `/patient`
   This indicates a route-level separation of concerns rather than a single monolithic screen with conditional rendering.

4. **AI extraction boundary**
   The AI integration is isolated in `src/app/actions/ai.ts`, which strongly suggests a **server action boundary** between UI and model invocation. That boundary is important: client components handle upload and interaction, while the server action handles AI processing and likely keeps the Gemini interaction out of the browser-facing component tree.

5. **Document processing flow**
   The repository includes utilities for **file-to-base64 conversion** and **file size formatting**, which implies uploaded PDFs/images are converted into a transport-friendly format before extraction. This points to a document ingestion pipeline centered on binary file handling rather than database records.

6. **Client-side state and persistence**
   `src/utils/storageEngine.ts` and the README’s emphasis on localStorage indicate that the app uses **browser persistence** to retain patient sessions, timelines, and extracted results across refreshes. There does not appear to be a backend database or API layer in this repo; the system is primarily client-state-driven with AI computation as the main external service.

7. **UI composition**
   The UI is built from reusable component layers:
   - `src/components/home` for portal selection cards
   - `src/components/nav` for shared navigation
   - `src/components/patientPortal` for patient-specific UI such as headers and loading skeletons
   - `src/components/shared` for common branding like the logo
   - `src/components/ui` for a Shadcn-style design system
   This makes the app modular by screen and by primitive.

8. **Visual and layout shell**
   `src/app/layout.tsx`, `src/app/globals.css`, and the Tailwind/Shadcn setup define a global layout shell with consistent styling and responsive constraints. The README calls out a unified max-width layout, so the diagram should show a single shared presentation layer wrapping all portals.

9. **Data model layer**
   `src/types/medical.ts` likely defines the structured output schema for extracted clinical data such as doctor names, vitals, summaries, and medicine arrays. This type layer is the contract between AI output, storage, and UI rendering.

10. **Mock/demo support**
   `src/utils/mockData.ts` suggests the app can render with sample clinical data, likely to support demo states or fallback behavior when no document has been processed yet. This is useful to show in the architecture as a non-production data source alongside real AI extraction.

11. **External dependency**
   The only clear external service is **Google Gemini** via `@google/genai`, with the README explicitly mentioning multimodal models like `gemini-1.5-flash` and `gemini-2.5-flash`. In the architecture, Gemini is the core external intelligence layer that transforms uploaded documents into structured medical records.

12. **Overall system boundary**
   In diagram terms, this repo is a **front-end-first system**: browser UI, local persistence, and server actions for AI calls, with no visible custom backend, auth service, or database layer in the tree. The main system boundary is between the Next.js client/server app and the Gemini API.

Main entry points: [`src/app/patient/page.tsx`](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/patient/page.tsx) (Patient), [`src/app/layout.tsx`](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/layout.tsx) (App shell), [`src/app/actions/ai.ts`](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/actions/ai.ts) (AI action), [`src/components/nav/PortalNav.tsx`](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/components/nav/PortalNav.tsx) (Portal nav)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_shell["App shell<br/>nextjs layout<br/>[layout.tsx]"]
  node_home["Home<br/>route page<br/>[page.tsx]"]
  node_admin["Admin<br/>route page<br/>[page.tsx]"]
  node_doctor["Doctor<br/>route page<br/>[page.tsx]"]
  node_patient["Patient<br/>route page<br/>[page.tsx]"]
  node_ai_action{{"AI action<br/>server action<br/>[ai.ts]"}}
end

subgraph group_components["UI Components"]
  node_portal_cards["Portal cards<br/>home components"]
  node_portal_nav["Portal nav<br/>shared nav<br/>[PortalNav.tsx]"]
  node_patient_ui["Patient UI<br/>portal components"]
  node_logo(("Logo<br/>brand component<br/>[Logo.tsx]"))
  node_ui_kit["UI kit<br/>design system"]
end

subgraph group_data["Data Layer"]
  node_storage[("Storage engine<br/>local persistence<br/>[storageEngine.ts]")]
  node_mock_data["Mock data<br/>demo dataset<br/>[mockData.ts]"]
  node_file_utils["File utils<br/>document helpers"]
  node_medical_types["Medical types<br/>domain schema<br/>[medical.ts]"]
  node_utils_core["App utils<br/>shared helpers<br/>[utils.ts]"]
end

subgraph group_external["External Service"]
  node_gemini{{"Gemini API<br/>ai model"}}
end

node_shell -->|"wraps"| node_home
node_shell -->|"wraps"| node_admin
node_shell -->|"wraps"| node_doctor
node_shell -->|"wraps"| node_patient
node_home -->|"renders"| node_portal_cards
node_home -->|"brands"| node_logo
node_admin -->|"uses"| node_portal_nav
node_doctor -->|"uses"| node_portal_nav
node_patient -->|"uses"| node_portal_nav
node_patient -->|"composes"| node_patient_ui
node_patient_ui -->|"builds on"| node_ui_kit
node_portal_cards -->|"builds on"| node_ui_kit
node_portal_nav -->|"includes"| node_logo
node_patient -->|"prepares uploads"| node_file_utils
node_patient -->|"persists"| node_storage
node_patient -->|"falls back to"| node_mock_data
node_patient -->|"structures"| node_medical_types
node_ai_action -->|"calls"| node_gemini
node_ai_action -->|"returns"| node_medical_types
node_patient -->|"submits to"| node_ai_action
node_file_utils -->|"feeds"| node_ai_action
node_storage -->|"stores"| node_medical_types
node_utils_core -->|"supports"| node_ui_kit

click node_shell "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/layout.tsx"
click node_home "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/page.tsx"
click node_admin "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/admin/page.tsx"
click node_doctor "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/doctor/page.tsx"
click node_patient "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/patient/page.tsx"
click node_ai_action "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/actions/ai.ts"
click node_portal_cards "https://github.com/arafat-yasin-2413/health-sync/tree/main/src/components/home"
click node_portal_nav "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/components/nav/PortalNav.tsx"
click node_patient_ui "https://github.com/arafat-yasin-2413/health-sync/tree/main/src/components/patientPortal"
click node_logo "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/components/shared/Logo.tsx"
click node_ui_kit "https://github.com/arafat-yasin-2413/health-sync/tree/main/src/components/ui"
click node_storage "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/utils/storageEngine.ts"
click node_mock_data "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/utils/mockData.ts"
click node_file_utils "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/utils/convertFileToBase64.ts"
click node_medical_types "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/types/medical.ts"
click node_utils_core "https://github.com/arafat-yasin-2413/health-sync/blob/main/src/lib/utils.ts"

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_shell,node_home,node_admin,node_doctor,node_patient,node_ai_action toneBlue
class node_portal_cards,node_portal_nav,node_patient_ui,node_logo,node_ui_kit toneAmber
class node_storage,node_mock_data,node_file_utils,node_medical_types,node_utils_core toneMint
class node_gemini toneRose
```

## Components

### App Router

Route entry points and shared shell

- [App shell](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/layout.tsx): nextjs layout · Global layout and styling wrapper for all portals · `src/app/layout.tsx`
- [Home](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/page.tsx): route page · Landing page that routes users into portal flows · `src/app/page.tsx`
- [Admin](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/admin/page.tsx): route page · Admin portal entry screen · `src/app/admin/page.tsx`
- [Doctor](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/doctor/page.tsx): route page · Doctor portal entry screen · `src/app/doctor/page.tsx`
- [Patient](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/patient/page.tsx): route page · Primary patient workflow for document upload and extraction · `src/app/patient/page.tsx`
- [AI action](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/app/actions/ai.ts): server action · Server-side boundary that invokes model extraction · `src/app/actions/ai.ts`

### UI Components

Reusable screen and design-system components

- [Portal cards](https://github.com/arafat-yasin-2413/health-sync/tree/main/src/components/home): home components · Home screen cards for choosing Admin, Doctor, or Patient portals · `src/components/home`
- [Portal nav](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/components/nav/PortalNav.tsx): shared nav · Shared navigation across portal views · `src/components/nav/PortalNav.tsx`
- [Patient UI](https://github.com/arafat-yasin-2413/health-sync/tree/main/src/components/patientPortal): portal components · Patient-specific header and loading states · `src/components/patientPortal`
- [Logo](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/components/shared/Logo.tsx): brand component · Shared branding used across the app shell and nav · `src/components/shared/Logo.tsx`
- [UI kit](https://github.com/arafat-yasin-2413/health-sync/tree/main/src/components/ui): design system · Reusable shadcn-style primitives for forms, dialogs, cards, and tabs · `src/components/ui`

### Data Layer

Local state, types, and document helpers

- [Storage engine](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/utils/storageEngine.ts): local persistence · Browser persistence for sessions, timelines, and extracted results · `src/utils/storageEngine.ts`
- [Mock data](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/utils/mockData.ts): demo dataset · Sample clinical records for fallback or demo states · `src/utils/mockData.ts`
- [File utils](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/utils/convertFileToBase64.ts): document helpers · Base64 conversion and file-size formatting for uploads · `src/utils/convertFileToBase64.ts`
- [Medical types](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/types/medical.ts): domain schema · Structured output contract for extracted clinical data · `src/types/medical.ts`
- [App utils](https://github.com/arafat-yasin-2413/health-sync/blob/main/src/lib/utils.ts): shared helpers · Common utility helpers used across components · `src/lib/utils.ts`

### External Service

AI model boundary

- **Gemini API**: ai model · External multimodal model used for document-to-data extraction

## Connections

- App shell → Home: wraps · Provides the shared layout and styling shell
- App shell → Admin: wraps · Provides the shared layout and styling shell
- App shell → Doctor: wraps · Provides the shared layout and styling shell
- App shell → Patient: wraps · Provides the shared layout and styling shell
- Home → Portal cards: renders · Home page is composed of portal selection cards
- Home → Logo: brands · Landing page uses shared branding
- Admin → Portal nav: uses · Portal page shares navigation chrome
- Doctor → Portal nav: uses · Portal page shares navigation chrome
- Patient → Portal nav: uses · Patient portal shares navigation chrome
- Patient → Patient UI: composes · Patient route is built from portal-specific UI pieces
- Patient UI → UI kit: builds on · Patient UI uses reusable primitives
- Portal cards → UI kit: builds on · Portal cards use common UI primitives
- Portal nav → Logo: includes · Navigation includes shared branding
- Patient → File utils: prepares uploads · Patient flow converts and formats uploaded files
- Patient → Storage engine: persists · Patient flow stores state and extracted results in the browser
- Patient → Mock data: falls back to · Demo or empty states can be populated from sample records
- Patient → Medical types: structures · UI consumes the extracted medical record contract
- AI action → Gemini API: calls · Server action invokes the external AI model
- AI action → Medical types: returns · Model output is shaped into the medical data schema
- Patient → AI action: submits to · Upload workflow triggers server-side extraction
- File utils → AI action: feeds · Prepared file payload is passed into the extraction boundary
- Storage engine → Medical types: stores · Persisted records follow the structured medical schema
- App utils → UI kit: supports · Shared helpers assist UI primitive composition