# aws-samples/bedrock-chat architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, serverless generative AI chat platform (“Bedrock Chat”) built on AWS managed services.
- Purpose: provide multilingual chat, custom bots with retrieval-augmented generation (RAG), bot sharing/store, API publication, and agent-based task automation, all powered by Amazon Bedrock.

##### File structure
- Top-level directories:
- backend/ – FastAPI app, agents, repositories, use-cases, Lambda handlers, tests
- frontend/ – React + TypeScript UI, components, features, i18n, Vite/Tailwind, Ladle stories
- cdk/ – AWS CDK stacks and constructs for provisioning all AWS resources
- scripts/ – utility scripts (doc translation, cross-region inference)
- Infra configuration: cdk.json, parameter.ts, GitHub workflows, Dockerfiles, run.sh, bin.sh
- Patterns:
- Frontend-Backend separation
- Serverless microservices with Lambda, API Gateway, DynamoDB, EventBridge Pipes + Step Functions
- RAG pipeline orchestration
- Infrastructure as code using CDK

##### README for additional insights
- Lists AWS services and how they fit (DynamoDB, Lambda + API Gateway + Web Adapter, CloudFront + S3, Cognito, WAF, Bedrock, Bedrock KB, EventBridge Pipes, Step Functions, OpenSearch Serverless, Athena)
- Includes a high-level architecture image

##### Components
a. Main components
- User Client / Browser (React SPA)
- Amazon CloudFront + S3 (hosting the frontend)
- Amazon Cognito (authentication & user pools)
- Amazon API Gateway (REST API front door)
- AWS Lambda (FastAPI backend, SQS consumer, embedding statemachine Lambdas)
- Amazon DynamoDB (conversation history, metadata)
- Amazon S3 (storing documents, KB exports)
- Amazon EventBridge Pipes (DynamoDB stream → state machine trigger)
- AWS Step Functions (orchestrate embedding pipeline)
- Amazon Bedrock (LLM inference)
- Amazon Bedrock Knowledge Bases (RAG embedding store)
- Amazon OpenSearch Serverless (vector & full-text search)
- Amazon Athena (analytics over S3 logs/data)
- AWS WAF (IP-restriction on CloudFront)
- AWS CDK (IaC) / CodeBuild pipelines (deployment)

b. Relationships & data flows
1. User logs in via CloudFront → Cognito (OAuth flow)
2. Authenticated React app calls API Gateway (passes JWT)
3. API Gateway invokes Lambda (FastAPI)
– Chat endpoints call Bedrock inference + vector_search + repositories on DynamoDB
– Bot store / publication endpoints manage metadata in DynamoDB / OpenSearch
4. Conversation writes to DynamoDB → DynamoDB stream → EventBridge Pipes → Step Functions → Lambda functions → embed docs into Bedrock KB & OpenSearch
5. Frontend assets are served from S3/CloudFront behind WAF
6. CDK scripts deploy all the above via CodeBuild / CloudFormation

c. Architectural patterns & principles
- Serverless microservices: stateless Lambdas behind API Gateway
- RAG pipeline: event-driven via DB streams + state machine
- Separation of concerns: UI, API layer, compute, data storage, search, orchestration
- Infrastructure as code: CDK constructs organized per service domain
- Multi-region / cross-region inference configurable

d. Technologies / frameworks
- React + Vite + TypeScript + Tailwind (frontend)
- FastAPI + aws-lambda-web-adapter + Python (backend)
- boto3, Amazon Bedrock SDK for LLM & KB
- DynamoDB, S3, OpenSearch Serverless, Athena
- Cognito, API Gateway, Lambda, EventBridge Pipes, Step Functions, WAF
- AWS CDK (TypeScript)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["User Client / Browser"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        CF["Amazon CloudFront"]:::infra
        S3Frontend["Amazon S3 (Frontend Assets)"]:::storage
        ReactSPA["Frontend UI (React SPA)"]:::frontend
    end

    %% Authentication
    Cognito["Amazon Cognito"]:::infra

    %% API Layer
    APIGW["Amazon API Gateway"]:::infra

    %% Compute Layer
    subgraph "Compute Layer"
        direction TB
        LambdaAPI["Lambda (FastAPI Backend)"]:::compute
        Agents["Agents & Tools Module"]:::compute
        UseCases["Business Logic (Use Cases)"]:::compute
        Repos["Data Access (Repositories)"]:::compute
        StreamHandler["DynamoDB Stream Handler"]:::compute
        SQSConsumer["SQS Consumer"]:::compute
        EmbeddingSM["Embedding Pipeline State Machine"]:::orchestration
        EBStepLambdas["Embedding Step Lambdas"]:::compute
        BedrockLLM["Amazon Bedrock (LLM Inference)"]:::compute
        VectorSearch["Vector & Full-Text Search"]:::compute
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        EventPipes["Amazon EventBridge Pipes"]:::orchestration
        StepFunctions["AWS Step Functions"]:::orchestration
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DynamoDB["Amazon DynamoDB"]:::storage
        S3Docs["Amazon S3 (Documents & KB Exports)"]:::storage
        BedrockKB["Amazon Bedrock Knowledge Bases"]:::storage
        OpenSearch["Amazon OpenSearch Serverless"]:::storage
        Athena["Amazon Athena"]:::storage
    end

    %% CI/CD Sideband
    subgraph "CI/CD & IaC"
        direction TB
        GitHubActions["GitHub Actions / CodeBuild"]:::cd
        CDK["AWS CDK"]:::cd
    end

    %% Data Flows
    User -->|"GET frontend"| CF -->|"serves assets"| S3Frontend --> ReactSPA
    ReactSPA -->|"OAuth JWT"| Cognito
    ReactSPA -->|"REST calls JWT"| APIGW -->|"invokes"| LambdaAPI

    LambdaAPI -->|"calls"| BedrockLLM
    LambdaAPI -->|"queries"| VectorSearch
    LambdaAPI -->|"reads/writes"| DynamoDB
    LambdaAPI -->|"stores files"| S3Docs
    LambdaAPI --> Agents
    Agents --> UseCases --> Repos

    DynamoDB -->|"stream events"| EventPipes --> StepFunctions --> EBStepLambdas --> BedrockKB
    EBStepLambdas --> OpenSearch

    SQSConsumer --> UseCases

    OpenSearch -->|"search results"| LambdaAPI

    DynamoDB --> Athena
    S3Docs --> Athena

    %% CI/CD Flows
    GitHubActions --> CDK --> CF
    CDK --> Cognito
    CDK --> APIGW
    CDK --> DynamoDB
    CDK --> EventPipes
    CDK --> StepFunctions

    %% Click Events
    click ReactSPA "https://github.com/aws-samples/bedrock-chat/tree/v3/frontend/"
    click CF "https://github.com/aws-samples/bedrock-chat/blob/v3/cdk/lib/constructs/frontend.ts"
    click Cognito "https://github.com/aws-samples/bedrock-chat/blob/v3/cdk/lib/constructs/auth.ts"
    click APIGW "https://github.com/aws-samples/bedrock-chat/blob/v3/cdk/lib/constructs/api.ts"
    click LambdaAPI "https://github.com/aws-samples/bedrock-chat/blob/v3/backend/app/main.py"
    click LambdaAPI "https://github.com/aws-samples/bedrock-chat/tree/v3/backend/Dockerfile"
    click LambdaAPI "https://github.com/aws-samples/bedrock-chat/blob/v3/backend/run.sh"
    click Agents "https://github.com/aws-samples/bedrock-chat/tree/v3/backend/app/agents/"
    click UseCases "https://github.com/aws-samples/bedrock-chat/tree/v3/backend/app/usecases/"
    click Repos "https://github.com/aws-samples/bedrock-chat/tree/v3/backend/app/repositories/"
    click StreamHandler "https://github.com/aws-samples/bedrock-chat/blob/v3/backend/app/stream.py"
    click SQSConsumer "https://github.com/aws-samples/bedrock-chat/blob/v3/backend/app/sqs_consumer.py"
    click EmbeddingSM "https://github.com/aws-samples/bedrock-chat/blob/v3/cdk/lib/constructs/embedding.ts"
    click EBStepLambdas "https://github.com/aws-samples/bedrock-chat/tree/v3/backend/embedding_statemachine/"
    click BedrockLLM "https://github.com/aws-samples/bedrock-chat/blob/v3/backend/app/bedrock.py"
    click BedrockKB "https://github.com/aws-samples/bedrock-chat/tree/v3/backend/embedding_statemachine/bedrock_knowledge_base/"
    click VectorSearch "https://github.com/aws-samples/bedrock-chat/blob/v3/backend/app/vector_search.py"
    click DynamoDB "https://github.com/aws-samples/bedrock-chat/blob/v3/cdk/lib/constructs/database.ts"
    click Athena "https://github.com/aws-samples/bedrock-chat/blob/v3/cdk/lib/constructs/usage-analysis.ts"
    click Athena "https://github.com/aws-samples/bedrock-chat/tree/v3/.github/workflows/"
    click CDK "https://github.com/aws-samples/bedrock-chat/blob/v3/cdk/bin/bedrock-chat.ts"

    %% Styles
    classDef user fill:#FFD966,stroke:#333,stroke-width:1px
    classDef frontend fill:#93C47D,stroke:#333,stroke-width:1px
    classDef infra fill:#6D9EEB,stroke:#333,stroke-width:1px
    classDef compute fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef storage fill:#76A5AF,stroke:#333,stroke-width:1px
    classDef orchestration fill:#F6B26B,stroke:#333,stroke-width:1px
    classDef cd fill:#E06666,stroke:#333,stroke-width:1px
```
