# harshhh28/hia architecture

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

- Interactive diagram: https://gitdiagram.com/harshhh28/hia
- Repository: https://github.com/harshhh28/hia

## Overview

##### Project Type and Purpose
- This is a single-page, interactive full-stack application built with Streamlit as the front-end UI. Its purpose is to allow users to authenticate, upload and process PDF blood reports, and then use an AI-driven analysis agent (with multi-model cascades) to provide personalized health insights.
- The project integrates with Supabase for authentication and database operations and uses external AI models (via Groq API) for processing.

##### Key Components
a. Frontend/UI Layer:
- Built with Streamlit (files in the .streamlit directory and UI components in src/components such as analysis_form.py, auth_pages.py, footer.py, and sidebar.py).
- Handles user interactions like login, file uploads, and display of analysis results.

b. Authentication & Session Management:
- Found under src/auth (auth_service.py and session_manager.py), which integrates with Supabase Auth.
- Separate module sessions are managed to handle secure access.

c. AI Analysis and Agent-Based Architecture:
- The core health insights functionality resides in the AI agents housed under src/agents (analysis_agent.py and model_manager.py, with the README also noting agent management and model fallback logic).
- The pattern here is an agent-based cascade: one primary AI model is used first, with secondary models as backups via a fallback mechanism.

d. AI Service Integration:
- Located in src/services/ai_service.py; this module handles interaction with the Groq API and ingestion of responses from various models.

e. PDF Processing:
- Implemented in src/utils/pdf_extractor.py using PDFPlumber.
- This component extracts text from uploaded blood reports (and is triggered likely by the UI on file upload).

f. Configuration and Utilities:
- Configurations (app_config.py, prompts.py, sample_data.py) in src/config set global settings and AI prompt data.
- Additional utilities (like validators under src/utils/validators.py) support input checks.

g. Database & Schema:
- The public/db directory and SQL script (script.sql) denote that Supabase manages the database where session histories and report analyses are stored.
- Extra emphasis on the database is also shown via instructions in the README.

##### Relationships and Interactions
- User actions (via the Streamlit UI) will interact with authentication modules (src/auth) for login and session management.
- Once authenticated, users can upload a PDF report. The UI component calls the PDF extractor (src/utils/pdf_extractor.py) to convert the PDF content into text.
- The text is then passed to an analysis agent (src/agents/analysis_agent.py), which uses the AI service (src/services/ai_service.py) for processing. This service, in turn, communicates with multiple AI models (with priority ordering defined via the model_manager and fallback logic).
- After processing, the AI-generated insights are sent back to UI components for display, and may also be logged/stored in the Supabase database.
- The configuration files (src/config) parameterize many of these interactions (such as API keys, prompt templates, etc.).

##### Architectural Patterns and Design Principles
- The project follows an agent-based and layered architecture:
- Presentation Layer (Streamlit UI components)
- Application Layer (Authentication, PDF processing, AI analysis, agent management)
- Integration Layer (Supabase for DB/auth and external AI models via Groq API)
- Emphasis is on modularity: separate directories and files for agents, services, authentication, and utilities ensure loose coupling.
- The use of configuration files enables easier environment changes without deep code modifications.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        UI_Config["Streamlit Config"]:::frontend
        UI_Analysis["Analysis Form"]:::frontend
        UI_AuthPages["Auth Pages"]:::frontend
        UI_Footer["Footer"]:::frontend
        UI_Header["Header"]:::frontend
        UI_Sidebar["Sidebar"]:::frontend
    end

    %% Authentication & Session Management
    subgraph "Authentication & Session Management"
        Auth_Service["Auth Service (Supabase Integration)"]:::auth
        Session_Manager["Session Manager"]:::auth
    end

    %% AI Analysis Agent
    subgraph "AI Analysis Agent"
        Analysis_Agent["Analysis Agent"]:::agent
        Model_Manager["Model Manager (Fallback)"]:::agent
    end

    %% AI Service Integration
    subgraph "AI Service Integration"
        AI_Service["AI Service (Groq API Integration)"]:::service
    end

    %% PDF Processing
    subgraph "PDF Processing"
        PDF_Extractor["PDF Extractor (PDFPlumber)"]:::processing
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        App_Config["App Config"]:::config
        Prompts["Prompts"]:::config
        Sample_Data["Sample Data"]:::config
        Validators["Validators"]:::config
    end

    %% Database
    subgraph "Database"
        Supabase_DB["Supabase DB"]:::db
    end

    %% External Service
    Groq_API["Groq API"]:::service

    %% Relationships
    UI_AuthPages -->|"authenticate"| Auth_Service
    Auth_Service -->|"session_manage"| Session_Manager
    Auth_Service -->|"db_store"| Supabase_DB
    UI_Analysis -->|"upload_PDF"| PDF_Extractor
    PDF_Extractor -->|"extract_text"| Analysis_Agent
    Analysis_Agent -->|"call_AI"| AI_Service
    AI_Service -->|"invoke_Groq"| Groq_API
    Analysis_Agent -->|"fallback"| Model_Manager
    Analysis_Agent -->|"db_log"| Supabase_DB
    Analysis_Agent -->|"deliver_insights"| UI_Analysis

    %% Configuration dotted links
    App_Config -.->|"configures"| Auth_Service
    App_Config -.->|"configures"| Analysis_Agent
    App_Config -.->|"configures"| AI_Service
    Prompts -.->|"used_by"| Analysis_Agent

    %% Click Events
    click UI_Config "https://github.com/harshhh28/hia/blob/main/.streamlit/config.toml"
    click UI_Analysis "https://github.com/harshhh28/hia/blob/main/src/components/analysis_form.py"
    click UI_AuthPages "https://github.com/harshhh28/hia/blob/main/src/components/auth_pages.py"
    click UI_Footer "https://github.com/harshhh28/hia/blob/main/src/components/footer.py"
    click UI_Header "https://github.com/harshhh28/hia/blob/main/src/components/header.py"
    click UI_Sidebar "https://github.com/harshhh28/hia/blob/main/src/components/sidebar.py"

    click Auth_Service "https://github.com/harshhh28/hia/blob/main/src/auth/auth_service.py"
    click Session_Manager "https://github.com/harshhh28/hia/blob/main/src/auth/session_manager.py"

    click Analysis_Agent "https://github.com/harshhh28/hia/blob/main/src/agents/analysis_agent.py"
    click Model_Manager "https://github.com/harshhh28/hia/blob/main/src/agents/model_manager.py"

    click AI_Service "https://github.com/harshhh28/hia/blob/main/src/services/ai_service.py"

    click PDF_Extractor "https://github.com/harshhh28/hia/blob/main/src/utils/pdf_extractor.py"

    click App_Config "https://github.com/harshhh28/hia/blob/main/src/config/app_config.py"
    click Prompts "https://github.com/harshhh28/hia/blob/main/src/config/prompts.py"
    click Sample_Data "https://github.com/harshhh28/hia/blob/main/src/config/sample_data.py"
    click Validators "https://github.com/harshhh28/hia/blob/main/src/utils/validators.py"

    click Supabase_DB "https://github.com/harshhh28/hia/blob/main/public/db/script.sql"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef auth fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef agent fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef service fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef processing fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef config fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef db fill:#F0E68C,stroke:#000,stroke-width:2px;
```
