# prajvalrasik/healthos-web architecture

> Architecture diagram of the GitHub repository prajvalrasik/healthos-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prajvalrasik/healthos-web
- Repository: https://github.com/prajvalrasik/healthos-web

## Overview

##### Project Type and Purpose
- HealthOS is a full-stack web application (Next.js v15 + TypeScript) for health data management.
- Frontend delivers UI and routing via the Next.js App Router.
- Backend relies on Supabase (PostgreSQL + Auth + Storage + Edge Functions) and several Third-Party APIs (Google Fit, OpenAI).

##### File Structure Analysis
- src/app/api: Next.js API routes (chat, google-fit, health, lab-reports, etc.).
- src/app/dashboard & src/app/settings: React pages and UI components for end-user flows.
- src/components/ui: Reusable UI primitives (buttons, cards, inputs).
- src/lib: Utilities (Supabase client, encryption, OpenAI LLM wrapper).
- supabase/functions: Edge Functions for heavy tasks (hardDelete, parseLabReport).
- supabase/migrations: SQL migrations for the database schema.

##### README Insights
- Authentication & Security (Supabase Auth + RLS + GDPR flows).
- Google Fit Integration (OAuth + real-time sync).
- Lab Report Processing (PDF upload → AI extraction → storage).
- AI Health Assistant (RAG chat using OpenAI + user data).
- Deployment targets (Vercel for frontend, Supabase CLI for Edge Functions).

##### Main Components
a. Client (Browser / Next.js Frontend)
b. Next.js Server (App Router + API Routes on Vercel)
c. Supabase Backend
- Auth
- PostgreSQL Database
- Storage (PDFs, images)
- Edge Functions (hardDelete, parseLabReport)
d. External Services
- Google Fit API (OAuth exchange, data fetch)
- OpenAI API (chat completions, document processing)
e. CI/CD / Deployment Platforms
- Vercel (Front + API routes)
- Supabase CLI (Edge Functions)

##### Relationships & Data Flow
- Browser ↔ Next.js (SSR/SSR, client-side routing).
- Next.js API Routes ↔ Supabase services (via supabase-js client).
- Edge Functions ↔ Supabase Database & Storage (server-side tasks).
- Next.js & Edge Functions ↔ Google Fit & OpenAI over HTTPS.
- Database tables with RLS policies protect user data.

##### Architectural Patterns & Principles
- Jamstack style: Pre-rendered UI with dynamic API routes.
- Microservices-style separation: Next.js API vs. Supabase Edge Functions.
- Client-server separation: UI components vs. business logic in API.
- Security by design: Row-Level Security, GDPR soft deletes.
- Eventual consistency: Deferred cleanup via edge functions.

##### Technologies & Frameworks
- Frontend: Next.js (App Router), React, Tailwind CSS, VisX charts.
- Backend: Supabase (Auth, Postgres, Storage), supabase-js, Edge Functions.
- AI: OpenAI GPT-4, RAG patterns.
- OAuth: Google Fit via Google Cloud Console.
- Deployment: Vercel, Supabase CLI.

##### Essential Elements
- Labels: Clear names (e.g., “Next.js API Route: /api/process-lab-report”)
- Security Notes: Mark RLS boundary at database, note GDPR grace period step.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser UI)" 
        direction TB
        UI["Next.js App (src/app)"]:::frontend
        Dashboard["Dashboard Pages (src/app/dashboard)"]:::frontend
        Settings["Settings Pages (src/app/settings)"]:::frontend
        Components["UI Components (src/components/ui)"]:::frontend
    end

    %% Next.js Server Layer
    subgraph "Next.js Server (Vercel)" 
        direction TB
        Router["App Router & SSR"]:::frontend
        subgraph "API Routes (src/app/api)"
            direction TB
            ChatAPI["/api/chat"]:::api
            GFExchange["/api/google-fit/exchange"]:::api
            GFSync["/api/google-fit/sync"]:::api
            LabProcess["/api/process-lab-report"]:::api
            HealthDelete["/api/health/delete"]:::api
            HealthCancel["/api/health/cancel-deletion"]:::api
            HealthExport["/api/health/export"]:::api
            LabDelete["/api/lab-reports/delete"]:::api
        end
        subgraph "Utilities (src/lib)"
            direction TB
            SupabaseClient["supabase.ts"]:::util
            LLMWrapper["llm.ts"]:::util
            Encryption["encryption.ts"]:::util
        end
    end

    %% Supabase Backend Layer
    subgraph "Supabase Backend" 
        direction TB
        Auth["Auth Service"]:::supabase
        Database["PostgreSQL Database"]:::db
        Storage["Storage (PDFs, Images)"]:::storage
        subgraph "Edge Functions"
            direction TB
            HardDelete["hardDelete"]:::edge
            ParseLab["parseLabReport"]:::edge
        end
        subgraph "Migrations & Schema"
            direction TB
            MigrationChat["create_chat_conversations.sql"]:::db
            MigrationSoftDelete["add_soft_delete_columns.sql"]:::db
            SchemaInit["supabase-schema.sql"]:::db
            SchemaUpdate["supabase-schema-update.sql"]:::db
            StorageSetup["supabase-storage-setup.sql"]:::db
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleFit["Google Fit API"]:::external
        OpenAI["OpenAI API"]:::external
    end

    %% Deployment Layer
    subgraph "CI/CD & Deployment"
        direction TB
        Vercel["Vercel"]:::deploy
        SupabaseCLI["Supabase CLI"]:::deploy
    end

    %% Connections
    UI -->|"renders via"| Router
    Dashboard --> Router
    Settings --> Router
    Components --> UI
    Router -->|calls| ChatAPI
    Router -->|calls| GFExchange
    Router -->|calls| GFSync
    Router -->|calls| LabProcess
    Router -->|calls| HealthDelete
    Router -->|calls| HealthCancel
    Router -->|calls| HealthExport
    Router -->|calls| LabDelete
    ChatAPI -->|"uses"| SupabaseClient
    GFExchange -->|"uses"| SupabaseClient
    GFSync -->|"uses"| SupabaseClient
    LabProcess -->|"uses"| SupabaseClient
    HealthDelete -->|"uses"| SupabaseClient
    HealthCancel -->|"uses"| SupabaseClient
    HealthExport -->|"uses"| SupabaseClient
    LabDelete -->|"uses"| SupabaseClient
    ChatAPI -->|HTTPS| OpenAI
    LabProcess -->|HTTPS| OpenAI
    GFExchange -->|HTTPS| GoogleFit
    GFSync -->|HTTPS| GoogleFit
    SupabaseClient -->|auth & data| Auth
    SupabaseClient -->|queries| Database
    SupabaseClient -->|uploads/downloads| Storage
    HardDelete -.->|async cleans| Database
    HardDelete -.->|async cleans| Storage
    ParseLab -.->|async processes| Storage
    ParseLab -->|"writes results"| Database
    Vercel -->|hosts| Router
    Vercel -->|deploys| UI
    SupabaseCLI -->|deploys| HardDelete
    SupabaseCLI -->|deploys| ParseLab

    %% Click Events
    click UI "https://github.com/prajvalrasik/healthos-web/tree/main/src/app"
    click Dashboard "https://github.com/prajvalrasik/healthos-web/tree/main/src/app/dashboard"
    click Settings "https://github.com/prajvalrasik/healthos-web/tree/main/src/app/settings"
    click Components "https://github.com/prajvalrasik/healthos-web/tree/main/src/components/ui"
    click ChatAPI "https://github.com/prajvalrasik/healthos-web/blob/main/src/app/api/chat/route.ts"
    click GFExchange "https://github.com/prajvalrasik/healthos-web/blob/main/src/app/api/google-fit/exchange/route.ts"
    click GFSync "https://github.com/prajvalrasik/healthos-web/blob/main/src/app/api/google-fit/sync/route.ts"
    click LabProcess "https://github.com/prajvalrasik/healthos-web/blob/main/src/app/api/process-lab-report/route.ts"
    click HealthDelete "https://github.com/prajvalrasik/healthos-web/blob/main/src/app/api/health/delete/route.ts"
    click HealthCancel "https://github.com/prajvalrasik/healthos-web/blob/main/src/app/api/health/cancel-deletion/route.ts"
    click HealthExport "https://github.com/prajvalrasik/healthos-web/blob/main/src/app/api/health/export/route.ts"
    click LabDelete "https://github.com/prajvalrasik/healthos-web/blob/main/src/app/api/lab-reports/delete/route.ts"
    click SupabaseClient "https://github.com/prajvalrasik/healthos-web/blob/main/src/lib/supabase.ts"
    click LLMWrapper "https://github.com/prajvalrasik/healthos-web/blob/main/src/lib/llm.ts"
    click Encryption "https://github.com/prajvalrasik/healthos-web/blob/main/src/lib/encryption.ts"
    click MigrationChat "https://github.com/prajvalrasik/healthos-web/blob/main/supabase/migrations/20240101000006_create_chat_conversations.sql"
    click MigrationSoftDelete "https://github.com/prajvalrasik/healthos-web/blob/main/supabase/migrations/20240101000007_add_soft_delete_columns.sql"
    click SchemaInit "https://github.com/prajvalrasik/healthos-web/blob/main/supabase-schema.sql"
    click SchemaUpdate "https://github.com/prajvalrasik/healthos-web/blob/main/supabase-schema-update.sql"
    click StorageSetup "https://github.com/prajvalrasik/healthos-web/blob/main/supabase-storage-setup.sql"
    click HardDelete "https://github.com/prajvalrasik/healthos-web/blob/main/supabase/functions/hardDelete/index.ts"
    click ParseLab "https://github.com/prajvalrasik/healthos-web/blob/main/supabase/functions/parseLabReport/index.ts"
    click Vercel "https://github.com/prajvalrasik/healthos-web/blob/main/next.config.ts"
    click SupabaseCLI "https://github.com/prajvalrasik/healthos-web/blob/main/supabase/functions/.eslintignore"

    %% Styles
    classDef frontend fill:#e0f7ff,stroke:#0288d1,color:#01579b
    classDef api fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef util fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
    classDef supabase fill:#e8f5e9,stroke:#43a047,color:#2e7d32
    classDef db fill:#fff3e0,stroke:#fb8c00,color:#e65100
    classDef storage fill:#fff8e1,stroke:#f9a825,color:#ff6f00
    classDef edge fill:#f1f8e9,stroke:#558b2f,color:#33691e,stroke-dasharray: 5 5
    classDef external fill:#ffebee,stroke:#d32f2f,color:#b71c1c,stroke-dasharray: 2 2
    classDef deploy fill:#eceff1,stroke:#607d8b,color:#263238
```
