# aws-samples/amazon-bedrock-agents-healthcare-lifesciences architecture

> Architecture diagram of the GitHub repository aws-samples/amazon-bedrock-agents-healthcare-lifesciences, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences
- Repository: https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences

## Overview

##### Project Type and Purpose
- This is a full-stack, serverless AWS solution that showcases a library of “Healthcare & Life Sciences” AI agents built on Amazon Bedrock.
- It provides:
- An **Agents Catalog** (pre-built Lambdas, Docker containers, CloudFormation stacks) for common HCLS workflows.
- **Multi-Agent Collaboration** examples orchestrating multiple agents for end-to-end scientific workflows.
- **Evaluation** notebooks to benchmark agent performance.
- Two UI frontends—**Streamlit** and a **Next.js React** app—served via AWS infrastructure.
- Infrastructure-as-code via CloudFormation templates (root `Infra_cfn.yaml`, per-agent CFNs, ECS & pipeline templates).

##### File Structure
- **Top-level infra & CI/CD**
- `Infra_cfn.yaml` – primary infra (VPCs, Redshift, Bedrock Agents, Knowledgebase, UIs)
- `agent_build.yaml`, `streamlit_build.yaml` – build pipelines
- `.github/workflows` – docs update CI
- **ActionGroups**
- Collections of Python AWS Lambda functions (DICOM→NIfTI, radiomics, PubMed, plotting, database queries).
- Each folder contains code, `requirements.txt`, and sometimes Dockerfiles for containerized actions.
- **agents_catalog**
- One folder per specialized “agent” (Clinical-Evidence, Imaging, SEC-10-K, etc.).
- Each agent has its own CloudFormation, Lambda code, Docker containers (when needed), and Jupyter notebooks for setup.
- **multi_agent_collaboration**
- Example orchestrations with notebooks and CFN.
- **evaluations**
- Notebooks + scripts to run agent performance evaluations.
- **UI**
- `streamlitapp/` – Streamlit code + CFN + Dockerfile for that UI
- `ui/` – Next.js React application, with API routes under `ui/app/api/*`, CloudFormation for ECS, and pipeline YAML.
- **docs/**

##### Main Components
a. **Infrastructure Layer (CloudFormation)**
– Two VPCs: one for backend infra, one for UI.
– Subnets, Security Groups, IAM Roles.
– CI/CD pipelines (CodeBuild/CodePipeline or GitHub Actions) that build agent containers and the React/Streamlit UIs.
b. **Data Layer**
– **Amazon Redshift** for structured data (genomic, clinical trial, biomarker tables).
– **Bedrock Knowledge Base** (with data source sync) for unstructured domain knowledge.
– **S3 buckets** (implied) for containers, artifacts, CFN templates, notebook outputs.
c. **Compute & AI Layer**
– **AWS Lambda**
- API handlers for React/Streamlit chat endpoints (`ui/app/api/chat/…`).
- ActionGroup Lambdas for specialized functions (imaging preprocessing, PubMed queries, plotting, analytics).
- Agent-specific Lambdas (as defined in each agents_catalog subfolder).
– **Amazon Bedrock** (foundation models) invoked by Lambdas for LLM tasks.
– **Docker-based containers** (when heavy dependencies are needed) deployed to AWS Lambda Container support or ECS.
d. **Application Layer (UIs)**
– **Streamlit App**
- Deployed via a Docker container, exposing a browser UI for interactive notebooks/controls.
– **React Next.js App**
- Hosted on ECS (via CFN `ecs.yml`).
- Exposes endpoints under `/api/agents` and `/api/chat`, which proxy to Lambda.
e. **Agent Catalog & Multi-agent Orchestration**
– YAML definitions and notebooks orchestrate sequences of Lambdas and Bedrock calls.
– Each agent catalog sub-stack can be deployed independently via its own CFN.
– Multi-agent examples assemble multiple agents to collaborate on a single task.
f. **Evaluation Suite**
– Jupyter notebooks calling the agents via Lambdas or direct Bedrock API calls.
– Metrics stored back into Redshift or local JSON for reporting.

##### Relationships & Data Flows
- **Frontend → API Gateway (or direct Lambda URL) → Lambda Chat Handlers → Bedrock models**
- **Chat Handlers** may invoke **ActionGroup Lambdas** or **agent-specific Lambdas** to fetch data (PubMed API, Redshift queries, imaging preprocess).
- **ActionGroup Lambdas** read/write to **Redshift** or **S3** or external sources, then return structured data to chat flow.
- **Bedrock Knowledge Base** is periodically synced via CFN triggers, and Lambdas query it for unstructured context.
- **CI/CD pipelines** push updated Docker images and Lambda code; CloudFormation updates the stacks.

##### Architectural Patterns & Principles
- **Serverless / Microservices**: each function is a single-purpose Lambda or container.
- **Infrastructure as Code**: reproducible via CloudFormation templates.
- **Separation of Concerns**: UI layer, API layer, compute layer, data layer are all distinct.
- **Modularity**: agent catalog folders are self-contained stacks.
- **Reusability**: ActionGroup Lambdas are generic building blocks used by multiple agents.

##### Technologies & Frameworks to Annotate
- AWS CloudFormation (root and per-agent CFNs)
- AWS Lambda (Python handlers, container Lambdas)
- Amazon Bedrock (LLM foundation models + Knowledge bases)
- Amazon Redshift
- Amazon S3
- ECS / Fargate for React App (Next.js)
- Docker (container images for heavy dependencies)
- React / Next.js / TypeScript for UI
- Streamlit for Python-based UI
- Astro for docs site
- GitHub Actions + CodeBuild/CodePipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        StreamlitApp["Streamlit App"]:::frontend
        ReactApp["React Next.js App"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIGateway["API Gateway / Lambda URL"]:::aws
    end

    %% Compute & AI Layer
    subgraph "Compute & AI Layer"
        direction TB
        subgraph "Chat Handlers"
            direction TB
            ChatLambda["Chat Lambda Handlers"]:::aws
        end
        subgraph "ActionGroup Lambdas"
            direction TB
            ImagingAG["Imaging Biomarker Lambda"]:::aws
            PubmedAG["PubMed Query Lambda"]:::aws
            QueryDBAG["Database Query Lambda"]:::aws
            PlotAG["Plotting Lambda"]:::aws
            SurvivalAG["Survival Data Processing Lambda"]:::aws
        end
        subgraph "Agent-specific Lambdas"
            direction TB
            AgentLambda["Agent Catalog Lambdas"]:::aws
        end
        Bedrock["Amazon Bedrock"]:::aws
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Redshift["Amazon Redshift"]:::data
        KB["Bedrock Knowledge Base"]:::data
        S3["Amazon S3"]:::data
    end

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD"
        direction TB
        RootCFN["Infra_cfn.yaml"]:::infra
        StreamlitCFN["Streamlit CFN"]:::infra
        ReactECSCFN["ECS CFN"]:::infra
        ReactPipeline["Docker Build Pipeline"]:::infra
        AgentBuild["agent_build.yaml"]:::infra
        StreamlitBuild["streamlit_build.yaml"]:::infra
        DocsCI[".github/workflows/on-docs-update.yml"]:::infra
        BuildAgentsScript["build_agents.sh"]:::infra
        BuildReactScript["build_react_app.sh"]:::infra
    end

    %% Multi-Agent & Evaluation
    subgraph "Agents Catalog & Orchestration"
        direction TB
        ClinicalEvidence["Clinical Evidence Agent"]:::container
        MedicalImaging["Medical Imaging Agent"]:::container
        PathologyAgent["Pathology Agent"]:::container
        SECAgent["SEC 10-K Agent"]:::container
        MultiAgentCA["Clinical-Trial-Protocol Assistant"]:::container
        MultiAgentCB["Cancer Biomarker Discovery"]:::container
        MultiAgentCI["Competitive Intelligence"]:::container
    end

    subgraph "Evaluation Suite"
        direction TB
        EvalNotebook["evaluate_biomarker_agent.ipynb"]:::container
        ExecEval["execute_eval.sh"]:::container
        TrajJSON["hcls_trajectories.json"]:::container
    end

    %% Connections
    StreamlitApp -->|UI Calls| APIGateway
    ReactApp -->|UI Calls| APIGateway
    APIGateway -->|Invokes| ChatLambda
    ChatLambda -->|Calls| ImagingAG
    ChatLambda -->|Calls| PubmedAG
    ChatLambda -->|Calls| QueryDBAG
    ChatLambda -->|Calls| PlotAG
    ChatLambda -->|Calls| SurvivalAG
    ChatLambda -->|Calls| AgentLambda
    ChatLambda -->|Invokes| Bedrock
    ImagingAG -->|Reads/Writes| Redshift
    PubmedAG -->|Reads| S3
    QueryDBAG -->|Reads/Writes| Redshift
    PlotAG -->|Writes| S3
    SurvivalAG -->|Reads/Writes| S3
    AgentLambda -->|Optional Containers| S3
    AgentLambda -->|Invokes| Bedrock
    Bedrock -->|Sync| KB
    RootCFN -->|Deploys| StreamlitCFN
    RootCFN -->|Deploys| ReactECSCFN
    RootCFN -->|Configures| Redshift
    RootCFN -->|Configures| KB
    AgentBuild -->|Builds| S3
    StreamlitBuild -->|Builds| S3
    DocsCI -->|Updates Docs| S3
    StreamlitBuild -->|Deploys| StreamlitApp
    ReactPipeline -->|Deploys| ReactApp
    RootCFN -->|Triggers| ReactPipeline
    RootCFN -->|Triggers| AgentBuild
    BuildAgentsScript -->|Scripts| AgentBuild
    BuildReactScript -->|Scripts| ReactPipeline

    ClinicalEvidence -->|Deployed by| RootCFN
    MedicalImaging -->|Deployed by| RootCFN
    PathologyAgent -->|Deployed by| RootCFN
    SECAgent -->|Deployed by| RootCFN
    MultiAgentCA -->|Uses| AgentLambda
    MultiAgentCA -->|Deployed by| RootCFN
    MultiAgentCB -->|Notebooks| MultiAgentCB
    MultiAgentCI -->|Deployed by| RootCFN

    EvalNotebook -->|Calls| AgentLambda
    EvalNotebook -->|Writes| Redshift
    ExecEval -->|Runs| EvalNotebook
    TrajJSON -->|Input| EvalNotebook

    %% Click Events
    click RootCFN "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/Infra_cfn.yaml"
    click StreamlitCFN "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/streamlitapp/Infra_cfn.yaml"
    click ReactECSCFN "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/cloudformation/ecs.yml"
    click ReactPipeline "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/cloudformation/docker_build_pipeline.yml"
    click AgentBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/agent_build.yaml"
    click StreamlitBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/streamlitapp/streamlit_build.yaml"
    click DocsCI "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/.github/workflows/on-docs-update.yml"
    click ImagingAG "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/ActionGroups/imaging-biomarker/"
    click PubmedAG "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/ActionGroups/pubmed-lambda-function/"
    click QueryDBAG "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/ActionGroups/querydatabaselambda/"
    click PlotAG "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/ActionGroups/matplotbarchartlambda/"
    click SurvivalAG "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/ActionGroups/survivaldataprocessinglambda/"
    click ClinicalEvidence "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/agents_catalog/02-Clinical-evidence-researcher/"
    click MedicalImaging "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/agents_catalog/03-Medical-imaging-expert/"
    click PathologyAgent "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/agents_catalog/07-Pathology-Agent/"
    click SECAgent "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/agents_catalog/10-SEC-10-K-agent/"
    click MultiAgentCA "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/multi_agent_collaboration/Clinical-Trial-Protocol-Assistant/clinical-trial-protocol-assistant-cfn.yaml"
    click MultiAgentCB "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/multi_agent_collaboration/cancer_biomarker_discovery/multi_agent_biomarker.ipynb"
    click MultiAgentCI "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/multi_agent_collaboration/competitive_intelligence/competitive-intelligence-agent-cfn.yaml"
    click EvalNotebook "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/evaluations/evaluate_biomarker_agent.ipynb"
    click ExecEval "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/evaluations/execute_eval.sh"
    click TrajJSON "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/evaluations/hcls_trajectories.json"
    click StreamlitApp "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/streamlitapp/app.py"
    click StreamlitApp "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/streamlitapp/Dockerfile.txt"
    click StreamlitApp "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/streamlitapp/requirements.txt"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/app/page.tsx"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/app/layout.tsx"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/app/chat/page.tsx"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/app/chat-b/page.tsx"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/app/api/chat/route.ts"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/app/api/chat/stream/route.ts"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/app/api/agents/route.ts"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/tree/main/ui/Dockerfile"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/package.json"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/next.config.ts"
    click ReactBuild "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/ui/tsconfig.json"
    click BuildAgentsScript "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/build_agents.sh"
    click BuildReactScript "https://github.com/aws-samples/amazon-bedrock-agents-healthcare-lifesciences/blob/main/build_react_app.sh"

    %% Styles
    classDef frontend fill:#f0f,stroke:#333,stroke-width:1px
    classDef aws fill:#bbf,stroke:#333,stroke-width:1px
    classDef container fill:#bfb,stroke:#333,stroke-width:1px
    classDef data fill:#fb8,stroke:#333,stroke-width:1px
    classDef infra fill:#ccc,stroke:#333,stroke-width:1px
```
