arafat-yasin-2413/health-sync

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.