# kacemmathlouthi/vcell-demo architecture

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

- Interactive diagram: https://gitdiagram.com/kacemmathlouthi/vcell-demo
- Repository: https://github.com/kacemmathlouthi/vcell-demo

## Overview

##### Project type and purpose
- This is a lightweight full‑stack demo application built with Streamlit that exposes a natural‑language chatbot for querying and visualizing BioModels from the VCell BioModel Database.
- It relies on two external services:
- A Groq‑powered LLaMA 3.3 LLM (via utils/llm_helper.py) for parameter extraction and summarization
- The VCell Public API (via vcelldb/vcell_api.py) for fetching real biological model data

##### File structure
Top‑level:
- app.py – The Streamlit entry point and orchestrator of UI, user input, and module calls
- requirements.txt, .env/.streamlit/config.toml – Dependencies and deployment configuration
Utility layer (utils/):
- llm_helper.py – Wrapper around the Groq API for LLM calls
- params_extraction.py – Logic for turning free‑text prompts into structured query parameters
Domain/data layer (vcelldb/):
- vcell_api.py – HTTP client that retrieves models, SBML/VCML files, reaction network data
- params_model.py – Pydantic schemas for the request parameters and API responses

##### Key architectural patterns and principles
- “Separation of Concerns”: UI (app.py) vs. LLM logic vs. API client vs. data modeling vs. visualization
- “Adapter/Wrapper” pattern for external dependencies (Groq API and VCell API)
- Use of Pydantic for schema validation and type safety

##### Main components
A. Frontend/UI
- Streamlit App (app.py)
- Receives user input
B. Backend modules (internal services)
1. Parameter Extraction Service (utils/params_extraction.py)
2. LLM Service Adapter (utils/llm_helper.py)
3. VCell API Client (vcelldb/vcell_api.py)
4. Data Models (vcelldb/params_model.py)
C. External Services
- Groq LLaMA API (LLM)
- VCell Public API
D. Configuration
- Environment (.env) for API keys
- Streamlit config (.streamlit/config.toml)

##### Relationships and data flow
1. User → Streamlit UI: submits a natural language query
2. UI → Parameter Extraction: passes query text to params_extraction
3. Parameter Extraction → LLM Adapter: sends prompt to Groq API
4. LLM Adapter → LLM Service: retrieves structured query parameters
5. UI/Controller → VCell API Client: invokes HTTP calls with extracted parameters
6. VCell API → VCell API Client → Data Models: responses are validated via Pydantic
8. Summarization (via LLM Adapter) → Human‑readable answer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        StreamlitApp["Streamlit App"]:::frontend
        Dependencies["requirements.txt"]:::config
        ConfigFile[".streamlit/config.toml"]:::config
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        ParamExtraction["Parameter Extraction Service"]:::business
        LLMAdapter["LLM Service Adapter"]:::business
    end

    %% Data & Visualization Layer
    subgraph "Data & Visualization"
        VCellClient["VCell API Client"]:::data
        DataModels["Data Models (Pydantic)"]:::data
        DiagramGen["Diagram Generator"]:::data
    end

    %% External Services
    Groq["Groq LLM API"]:::external
    VCellAPI["VCell Public API"]:::external

    %% Connections
    User -->|"enters query"| StreamlitApp
    StreamlitApp -->|"loads dependencies"| Dependencies
    StreamlitApp -->|"loads config"| ConfigFile
    StreamlitApp -->|"passes prompt text"| ParamExtraction
    ParamExtraction -->|"formats prompt"| LLMAdapter
    LLMAdapter -->|"sends prompt"| Groq
    Groq -->|"returns params"| LLMAdapter
    LLMAdapter -->|"returns query params"| StreamlitApp
    StreamlitApp -->|"invokes API client with params"| VCellClient
    VCellClient -->|"HTTP request"| VCellAPI
    VCellAPI -->|"JSON model data"| VCellClient
    VCellClient -->|"validate via Pydantic"| DataModels
    VCellClient -->|"passes data"| DiagramGen
    DiagramGen -->|"generates SVG diagram"| StreamlitApp
    LLMAdapter -->|"provides summary"| StreamlitApp

    %% Click Events
    click StreamlitApp "https://github.com/kacemmathlouthi/vcell-demo/blob/main/app.py"
    click ParamExtraction "https://github.com/kacemmathlouthi/vcell-demo/blob/main/utils/params_extraction.py"
    click LLMAdapter "https://github.com/kacemmathlouthi/vcell-demo/blob/main/utils/llm_helper.py"
    click VCellClient "https://github.com/kacemmathlouthi/vcell-demo/blob/main/vcelldb/vcell_api.py"
    click DataModels "https://github.com/kacemmathlouthi/vcell-demo/blob/main/vcelldb/params_model.py"
    click DiagramGen "https://github.com/kacemmathlouthi/vcell-demo/blob/main/vcelldb/diagram.py"
    click ConfigFile "https://github.com/kacemmathlouthi/vcell-demo/blob/main/.streamlit/config.toml"
    click Dependencies "https://github.com/kacemmathlouthi/vcell-demo/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6,stroke-width:1px
    classDef business fill:#D1FFD0,stroke:#28a745,color:#28a745,stroke-width:1px
    classDef data fill:#D0FFF0,stroke:#20c997,color:#20c997,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#d2691e,color:#d2691e,stroke-width:1px
    classDef config fill:#F0E6FF,stroke:#6f42c1,color:#6f42c1,stroke-width:1px
```
