# aws-samples/amazon-bedrock-flows-samples architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/amazon-bedrock-flows-samples
- Repository: https://github.com/aws-samples/amazon-bedrock-flows-samples

## Overview

##### Project Type and Purpose
- This is an open-source sample utility and demonstration repository for Amazon Bedrock Flows.
- It provides a Python CLI/Jupyter-based “Flow Manager” that:
– imports/creates Flow definitions from JSON templates
– invokes and tests those Flows against AWS Bedrock
– optionally cleans up (deletes) resources
- It also includes a CloudFormation template for deploying a Flow as an AWS resource.

##### File Structure
- Top-level
– README, CONTRIBUTING, LICENSE, requirements.txt, release notes, repo metadata
- cloudformation/
– bedrock_flows.json – CloudFormation template for automated Flow deployment
- docs/images/
- notebooks/
– flow_notebook.ipynb – interactive demonstration in Jupyter
- src/
– bedrock_flow_manager.py – main Python script (CLI + boto3 logic)
- templates/
– a set of JSON files implementing different Flow patterns (iterator, agents, RAG, guardrails, etc.)

##### README Insights
- The README outlines:
– the Flow patterns (nodes, connections, branching)
– CLI usage, arguments, and environment‐variable support
– CloudFormation deployment steps and parameters
– Examples for each template type
- It also references AWS IAM roles and permissions needed to manage Flows.

##### Main Components
a. Developer/Operator Environment
– Local CLI (bedrock_flow_manager.py)
– Local JSON templates directory
– Jupyter Notebook (flow_notebook.ipynb)
b. Infrastructure as Code
– CloudFormation service deploying bedrock_flows.json
c. AWS Services
– AWS IAM (executionRoleArn)
– Amazon Bedrock Flows Service
– (Optionally) Amazon S3 if DefinitionS3Location is used
d. Flow Execution Elements
– FlowDefinition (Nodes + Connections)
– Flow Versions, Flow Aliases
– Flow Invocation & Response

##### Relationships and Interactions
- CLI/Notebook reads a JSON template → calls boto3 to CreateFlow/CreateFlowVersion
→ AWS IAM evaluates permissions → Bedrock Flows Service stores the FlowDefinition
- CLI/Notebook invokes the Flow with test‐input → Bedrock runs each node
→ returns modelCompletion or aggregated array → CLI/Notebook collects outputs
- On `--cleanup`, CLI/Notebook calls DeleteFlowVersion/DeleteFlow → Bedrock deletes resources
- CloudFormation template can be deployed independently in AWS console/CLI to provision the same Flow

##### Architectural Patterns and Principles
- Separation of concerns
– “Flow Manager” logic (src/) vs JSON resources (templates/) vs IaC (cloudformation/)
- Extensibility points
– Add new JSON templates without changing code
– Plug in custom IAM roles via `--existing-role`
- Declarative vs Imperative
– Declarative (CloudFormation) vs Imperative (CLI/Notebook)

##### Including Relevant Technologies
- Python 3.10+, boto3, termcolor, rich
- Jupyter Notebook for interactive demos
- AWS CloudFormation
- AWS Bedrock Flows API
- JSON as the Flow definition language

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Local Development Components
    subgraph "Local Development" 
        direction TB
        README["README.md"]:::docs
        Requirements["requirements.txt"]:::local
        Templates["templates/"]:::local
        subgraph "JSON Flow Templates" 
            direction TB
            C1["conditions_flow.json"]:::local
            C2["iterator_collector_flow.json"]:::local
            C3["multi_agent_flow.json"]:::local
            C4["multi_turn_agent_flow.json"]:::local
            C5["prompt_guardrail_flow.json"]:::local
            C6["rag_kb_flow.json"]:::local
        end
        Notebook["flow_notebook.ipynb"]:::local
        CLI["bedrock_flow_manager.py"]:::local
    end

    %% Infrastructure as Code
    subgraph "Infrastructure as Code (IaC)"
        direction TB
        CF["bedrock_flows.json"]:::iac
    end

    %% AWS Managed Services
    subgraph "AWS Services"
        direction TB
        IAM["AWS IAM"]:::aws
        S3["Amazon S3 (Optional)"]:::aws
        Bedrock["Amazon Bedrock Flows Service"]:::aws
    end

    %% Relationships
    README -.->|references| CLI
    Requirements -..-|dependencies| CLI
    Templates -->|reads JSON| CLI
    C1 -->|template| Templates
    C2 -->|template| Templates
    C3 -->|template| Templates
    C4 -->|template| Templates
    C5 -->|template| Templates
    C6 -->|template| Templates
    Notebook -->|drives CLI| CLI

    CLI -->|"CreateFlow/CreateFlowVersion"| IAM
    IAM -->|"authenticates"| Bedrock
    CLI -->|"InvokeFlow"| Bedrock
    Bedrock -->|"Response"| CLI
    CLI -->|"DeleteFlow/DeleteFlowVersion"| Bedrock

    CLI -->|"Upload Definition"| S3
    S3 -->|"Fetch Definition"| Bedrock

    CF -->|"Deploy Flow Resource"| Bedrock

    %% Click Events
    click CLI "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/src/bedrock_flow_manager.py"
    click Templates "https://github.com/aws-samples/amazon-bedrock-flows-samples/tree/main/templates/"
    click C1 "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/templates/conditions_flow.json"
    click C2 "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/templates/iterator_collector_flow.json"
    click C3 "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/templates/multi_agent_flow.json"
    click C4 "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/templates/multi_turn_agent_flow.json"
    click C5 "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/templates/prompt_guardrail_flow.json"
    click C6 "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/templates/rag_kb_flow.json"
    click Notebook "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/notebooks/flow_notebook.ipynb"
    click CF "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/cloudformation/bedrock_flows.json"
    click Requirements "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/requirements.txt"
    click README "https://github.com/aws-samples/amazon-bedrock-flows-samples/blob/main/README.md"
    click README "https://github.com/aws-samples/amazon-bedrock-flows-samples/tree/main/docs/images/"

    %% Styles
    classDef local fill:#D6E4FF,stroke:#000,stroke-width:1px
    classDef aws fill:#D4F8E8,stroke:#000,stroke-width:1px
    classDef iac fill:#FFF1B8,stroke:#000,stroke-width:1px
    classDef docs fill:#FFE7BA,stroke:#000,stroke-width:1px
```
