# biofiles/studio-clinical architecture

> Architecture diagram of the GitHub repository biofiles/studio-clinical, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/biofiles/studio-clinical
- Repository: https://github.com/biofiles/studio-clinical

## Overview

##### Project type and purpose
- Full-stack single-page application (SPA) built with Vite, React, TypeScript, Tailwind CSS, and shadcn-ui.
- Uses Supabase (Auth, Database, Storage) as the backend and Supabase Edge Functions for FHIR/CDISC operations.
- Purpose: clinical research platform handling participants, investigators, scheduling, questionnaires, e-consent, FHIR export/import/validation, and CDISC exports.

##### File structure
- src/ – React components (UI, pages, contexts, hooks, integrations, lib).
- supabase/ – Edge Functions (cdisc-export, fhir-client, fhir-export, fhir-import, fhir-validate) + database migrations.
- integrations/supabase/client.ts – Supabase client wrapper for API calls.
- lib/fhir-client.ts – shared FHIR logic.
- Contexts – manage Auth, Study, Onboarding, Language.
- UI Pattern – component folder for each feature; /ui subfolder for shadcn UI primitives.

##### README for additional insights
- Tech stack: Vite, TS, React, shadcn-ui, Tailwind.
- Deployment via Lovable (static hosting + automatic CI).
- Supabase handles data, auth, edge functions.

##### Main components and their relationships (stacked vertically)
a. Client Layer
– Browser (React SPA)
– UI Contexts & Routing (/src/pages, /contexts)
– UI Components (/src/components)

b. API Layer
– Supabase JavaScript Client (/src/integrations/supabase/client.ts)
– REST calls & WebSocket subscriptions to Supabase
– Edge Functions HTTP endpoints (cdisc-export, fhir-export, fhir-import, fhir-validate, fhir-client)

c. Data Layer
– Supabase Database (tables, migrations)
– Supabase Auth (users, roles)
– Supabase Storage (documents, e-consents)

d. External Services
– External FHIR Server(s) (for import/export/validation)
– CDISC conversion tool (invoked by Edge Function)

##### Architectural patterns & design principles
- Single-page app with Context API for global state (Auth, Study, Language, Onboarding).
- “API-first” serverless backend via Supabase client + Edge Functions.
- Separation of concerns:
– UI (components/pages)
– Business logic (hooks, lib)
– Data access (integrations, supabase functions)
- Migrations ensure reproducible database schema.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser / React SPA"]:::frontend
        Main["Entry Point: src/main.tsx"]:::frontend
        App["Root App: src/App.tsx"]:::frontend
        Pages["Pages & Routing: src/pages"]:::frontend
        Contexts["Context Providers"]:::frontend
        AuthCtx["AuthContext"]:::frontend
        StudyCtx["StudyContext"]:::frontend
        OnboardCtx["OnboardingContext"]:::frontend
        LangCtx["LanguageContext"]:::frontend
        Components["UI Components: src/components"]:::frontend
        UIPrims["UI Primitives: src/components/ui"]:::frontend
        DocRepo["DocumentRepository"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        SupaClient["Supabase JS Client"]:::api
        FHIRLib["Shared FHIR Logic"]:::api
        subgraph "Edge Functions"
            direction TB
            CDisc["cdisc-export"]:::api
            FHIRClientFunc["fhir-client"]:::api
            FHIRExport["fhir-export"]:::api
            FHIRImport["fhir-import"]:::api
            FHIRValidate["fhir-validate"]:::api
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Database["Supabase Database"]:::datastore
        Auth["Supabase Auth"]:::datastore
        Storage["Supabase Storage"]:::datastore
        Migrations["Database Migrations: supabase/migrations"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ExtFHIR["External FHIR Server"]:::external
        CDiscSvc["CDISC Conversion Service"]:::external
    end

    %% Connections
    Browser -->|"loads"| Main
    Main -->|"renders"| App
    App -->|"uses"| Pages
    App -->|"uses"| Components
    Components -->|"primitives"| UIPrims
    App -->|"provides contexts"| Contexts
    Contexts --> AuthCtx
    Contexts --> StudyCtx
    Contexts --> OnboardCtx
    Contexts --> LangCtx
    App -->|"uses"| DocRepo

    Browser -->|"HTTP/WebSocket"| SupaClient
    SupaClient -->|"logic"| FHIRLib
    SupaClient -->|"calls"| Database
    SupaClient -->|"auth"| Auth
    SupaClient -->|"storage"| Storage

    SupaClient -->|"HTTP"| CDisc
    SupaClient -->|"HTTP"| FHIRClientFunc
    SupaClient -->|"HTTP"| FHIRExport
    SupaClient -->|"HTTP"| FHIRImport
    SupaClient -->|"HTTP"| FHIRValidate

    CDisc -->|"writes"| Database
    CDisc -->|"uses"| CDiscSvc
    FHIRClientFunc -->|"uses"| ExtFHIR
    FHIRExport -->|"uses"| ExtFHIR
    FHIRImport -->|"uses"| ExtFHIR
    FHIRValidate -->|"uses"| ExtFHIR

    %% Click Events
    click Main "https://github.com/biofiles/studio-clinical/blob/main/src/main.tsx"
    click App "https://github.com/biofiles/studio-clinical/blob/main/src/App.tsx"
    click Pages "https://github.com/biofiles/studio-clinical/tree/main/src/pages"
    click AuthCtx "https://github.com/biofiles/studio-clinical/blob/main/src/contexts/AuthContext.tsx"
    click StudyCtx "https://github.com/biofiles/studio-clinical/blob/main/src/contexts/StudyContext.tsx"
    click OnboardCtx "https://github.com/biofiles/studio-clinical/blob/main/src/contexts/OnboardingContext.tsx"
    click LangCtx "https://github.com/biofiles/studio-clinical/blob/main/src/contexts/LanguageContext.tsx"
    click Components "https://github.com/biofiles/studio-clinical/tree/main/src/components"
    click UIPrims "https://github.com/biofiles/studio-clinical/tree/main/src/components/ui"
    click DocRepo "https://github.com/biofiles/studio-clinical/blob/main/src/components/DocumentRepository.tsx"
    click SupaClient "https://github.com/biofiles/studio-clinical/blob/main/src/integrations/supabase/client.ts"
    click FHIRLib "https://github.com/biofiles/studio-clinical/blob/main/src/lib/fhir-client.ts"
    click CDisc "https://github.com/biofiles/studio-clinical/blob/main/supabase/functions/cdisc-export/index.ts"
    click FHIRClientFunc "https://github.com/biofiles/studio-clinical/blob/main/supabase/functions/fhir-client/index.ts"
    click FHIRExport "https://github.com/biofiles/studio-clinical/blob/main/supabase/functions/fhir-export/index.ts"
    click FHIRImport "https://github.com/biofiles/studio-clinical/blob/main/supabase/functions/fhir-import/index.ts"
    click FHIRValidate "https://github.com/biofiles/studio-clinical/blob/main/supabase/functions/fhir-validate/index.ts"
    click Migrations "https://github.com/biofiles/studio-clinical/tree/main/supabase/migrations"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef api fill:#DFFFE0,stroke:#22863a,stroke-width:1px;
    classDef datastore fill:#FFEDD5,stroke:#d15704,stroke-width:1px;
    classDef external fill:#F0E5FF,stroke:#6f42c1,stroke-width:1px;
```
