# valencienseow/herai---codeblue architecture

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

- Interactive diagram: https://gitdiagram.com/valencienseow/herai---codeblue
- Repository: https://github.com/valencienseow/herai---codeblue

## Overview

##### Project type and purpose
- HerAI is a full-stack clinical decision support system for maternal health.
- Frontend: Next.js/TypeScript UI with Tailwind CSS, RAG (retrieval-augmented generation) endpoint.
- Backend: FastAPI Python service with ML risk-prediction models, SQLite DB, PDF CPG storage.
- ML: scikit-learn (.joblib) and Keras models.

##### Top-level components
- Frontend (herai-frontend/)
– Next.js App Router under src/app
– API routes (e.g., /api/rag) for local LLM or RAG calls
– React components, Tailwind styling
– localStorage mock or HTTP client (src/lib/api.ts, supabaseClient.js)
– Dockerized “llm-app” for LLM service (docker/llm-app)
- Backend (herai-backend/)
– main.py launches FastAPI, registers routes for patients, vitals, guidelines
– supabase_client.py (optional integration)
– cpg_helper.py for guideline lookup from PDF corpus (cpg_documents/)
– ml/ml_service.py wrapping ML models in models/
– SQLite database herai.db
- External/Infrastructure
– Docker container for LLM (llm-app)
– Potential Supabase or external API for production
– Vercel hosting frontend, Railway/Heroku for backend

##### Relationships & interactions
- User → Browser → Next.js UI
- Next.js fetches:
a) Mock/local patient data via localStorage or
b) HTTP to FastAPI endpoints at http://localhost:8000/patients, /vitals, /risk, /cpg
- FastAPI → SQLite for CRUD patient & vitals
- FastAPI → ml_service to predict risk → returns risk score & next-step recommendations
- FastAPI → cpg_helper to search embedded PDF guidelines → returns relevant CPG text
- Next.js → RAG API route (/api/rag) → Dockerized LLM service → generates narrative insights
- Optional: Frontend ↔ Supabase (auth, real DB) via supabaseClient.js

##### Architectural patterns & design principles
- Clear separation of concerns: UI, API layer, ML service, guideline search, persistence
- Modular ML encapsulation (ml_service.py + models folder)
- RAG microservice pattern for LLM (docker/llm-app)
- Component-based React UI
- Configurable backend client (supabase for production)

##### Detail
- Separation of static assets (public/ folder) vs. dynamic data
- Docker llm-app microservice for LLM/RAG
- Call out mock vs. real API integration path in src/lib/api.ts
- PDF guideline store as a filesystem mount under backend
- Environment/config layers (dotenv, next.config.ts, docker-compose env files)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User (Healthcare Professional)"]:::external

    %% Frontend
    subgraph "Next.js Frontend" 
        AppRouter["App Router (src/app)"]:::frontend
        subgraph "UI Components"
            Dashboard["Dashboard Components"]:::frontend
            Layout["Layout/Navbar"]:::frontend
            Patients["Patients Components"]:::frontend
            Vitals["Vitals Components"]:::frontend
        end
        LS["LocalStorage (Mock Data)"]:::frontend
        APIClient["API Client (api.ts)"]:::frontend
        RAGClient["RAG Client (rag.ts)"]:::frontend
        RAGRoute["RAG API Route (/api/rag)"]:::frontend
        SupabaseFrontend["Supabase Integration"]:::frontend
    end

    %% Backend
    subgraph "FastAPI Backend"
        Main["Entry Point (main.py)"]:::backend
        DatabaseMod["Database Module"]:::backend
        SQLite["SQLite DB (herai.db)"]:::datastore
        MLService["ML Service (ml_service.py)"]:::backend
        ModelsDir["Models Directory"]:::datastore
        CPGHelper["CPG Helper (cpg_helper.py)"]:::backend
        PDFs["CPG PDF Corpus"]:::datastore
        SupabaseBackend["Supabase Client"]:::backend
        Requirements["requirements.txt"]:::backend
    end

    %% External Services
    subgraph "External Services"
        LLMContainer["LLM Container (llm-app)"]:::external
        SupabaseExt["Supabase / Auth"]:::external
    end

    %% Connections
    User -->|"uses UI"| AppRouter
    AppRouter -->|"renders"| Dashboard
    AppRouter --> Layout
    Dashboard --> Patients
    Dashboard --> Vitals

    AppRouter --> LS
    Dashboard --> APIClient
    Patients --> APIClient
    Vitals --> APIClient

    APIClient -->|"HTTP /patients, /vitals, /risk, /cpg"| Main
    RAGRoute -->|"fetch narrative"| LLMContainer
    RAGClient --> RAGRoute

    Main --> DatabaseMod
    DatabaseMod --> SQLite
    Main --> MLService
    MLService --> ModelsDir
    ModelsDir -->|"model files"| MLService
    Main --> CPGHelper
    CPGHelper --> PDFs
    Main --> SupabaseBackend
    APIClient --> SupabaseExt
    SupabaseFrontend --> SupabaseExt

    %% Click Events
    click AppRouter "https://github.com/valencienseow/herai---codeblue/tree/main/herai-frontend/src/app"
    click APIClient "https://github.com/valencienseow/herai---codeblue/blob/main/herai-frontend/src/lib/api.ts"
    click RAGClient "https://github.com/valencienseow/herai---codeblue/blob/main/herai-frontend/src/lib/rag.ts"
    click SupabaseFrontend "https://github.com/valencienseow/herai---codeblue/blob/main/herai-frontend/config/supabaseClient.js"
    click RAGRoute "https://github.com/valencienseow/herai---codeblue/blob/main/herai-frontend/src/app/api/rag/route.ts"
    click Dashboard "https://github.com/valencienseow/herai---codeblue/tree/main/herai-frontend/src/components/dashboard"
    click Layout "https://github.com/valencienseow/herai---codeblue/tree/main/herai-frontend/src/components/layout"
    click Patients "https://github.com/valencienseow/herai---codeblue/tree/main/herai-frontend/src/components/patients"
    click Vitals "https://github.com/valencienseow/herai---codeblue/tree/main/herai-frontend/src/components/vitals"
    click LLMContainer "https://github.com/valencienseow/herai---codeblue/tree/main/herai-frontend/docker/llm-app"
    click Main "https://github.com/valencienseow/herai---codeblue/blob/main/herai-backend/main.py"
    click SupabaseBackend "https://github.com/valencienseow/herai---codeblue/blob/main/herai-backend/supabase_client.py"
    click CPGHelper "https://github.com/valencienseow/herai---codeblue/blob/main/herai-backend/cpg_helper.py"
    click PDFs "https://github.com/valencienseow/herai---codeblue/tree/main/herai-backend/cpg_documents"
    click MLService "https://github.com/valencienseow/herai---codeblue/blob/main/herai-backend/ml/ml_service.py"
    click ModelsDir "https://github.com/valencienseow/herai---codeblue/tree/main/herai-backend/ml/models"
    click SQLite "https://github.com/valencienseow/herai---codeblue/blob/main/herai-backend/herai.db"
    click Requirements "https://github.com/valencienseow/herai---codeblue/blob/main/herai-backend/requirements.txt"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:1px;
    classDef backend fill:#c8e6c9,stroke:#1b5e20,stroke-width:1px;
    classDef datastore fill:#ffe0b2,stroke:#ff6f00,stroke-width:1px;
    classDef external fill:#ffcc80,stroke:#e65100,stroke-width:1px;
```
