# aws-solutions/generative-ai-application-builder-on-aws architecture

> Architecture diagram of the GitHub repository aws-solutions/generative-ai-application-builder-on-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-solutions/generative-ai-application-builder-on-aws
- Repository: https://github.com/aws-solutions/generative-ai-application-builder-on-aws

## Overview

##### And lay out the major components
- Frontend UIs:
- Deployment Dashboard UI (located in source/ui-deployment)
- Chat UI (located in source/ui-chat)
- Cloud Infrastructure:
- AWS CDK defined stacks (source/infrastructure) that deploy the overall architecture.
- Nested CloudFormation stacks for various use cases.
- AWS Serverless Backing:
- REST APIs and WebSocket APIs deployed via Amazon API Gateway.
- AWS Lambda functions (found in source/lambda), including helpers, custom authorizers, and orchestration functions.
- Authentication and Authorization:
- Amazon Cognito for user authentication, integrated with both UI projects and API endpoints.
- Data Stores & Storage:
- Amazon DynamoDB for storing deployment configurations, user policies, LLM configuration options, and chat histories.
- Amazon S3 buckets used for hosting the static web UI assets and storing artifacts (assets are also staged from source/stage-assets.sh).
- Additional Services:
- Amazon CloudFront to serve the frontend UIs.
- Optional usage of Amazon Kendra or Bedrock Knowledge Bases for knowledge retrieval in use cases.
- Amazon SQS being used as part of asynchronous processing in the LangChain Orchestrator workflow.
- Amazon CloudWatch for operational metrics, dashboards, and logging.

##### Relationships and interactions
- A separation between the two UIs:
- The Deployment Dashboard UI for admin users is delivered via CloudFront. It interacts with API Gateway endpoints (protected via AWS WAF) and invokes Lambda functions that in turn manage CloudFormation (for deploying use cases).
- The Chat UI for business users also leverages CloudFront and a WebSocket API built using API Gateway. It interacts with a series of Lambda functions (the LangChain Orchestrator) that receive asynchronous requests via an SQS queue and then query either Amazon SageMaker or Amazon Bedrock for the LLM response.
- From CloudFront (hosting static assets) → API Gateway → Lambda → possibly DynamoDB (for configuration or session data) → further AWS services (S3, SQS, or external LLM provider endpoints).
- Callback paths, such as Lambda streaming back responses to API Gateway’s WebSocket connection.
- Authentication flow:
- From end users (admin or business) → Cognito (and custom authorizers in some cases) → API Gateway which is secured by Cognito.

##### Architectural patterns to highlight
- Serverless design using AWS Lambda, API Gateway, and DynamoDB.
- Modular and extensible infrastructure provisioning via AWS CDK and nested stacks.
- Use of asynchronous messaging (SQS) to decouple web API and long-running orchestration tasks.
- Clear separation between UI (frontend) and backend (Lambda functions, data stores, orchestration logic).

##### Following technical details
- Technologies, frameworks, and libraries:
- AWS CDK (in TypeScript and occasionally Python)
- Lambda functions written in Python, Node.js, and TypeScript
- Use of LangChain (an external open-source library for LLM orchestration)
- Frontend built with React via Vite.
- Usage of AWS CloudFormation; nested stack approach is a key design principle.
- Utility scripts for staging assets, building distribution packages, and running tests.

##### Final advice
- Next, decompose the system into its layers: presentation (UI), application (API Gateway + Lambda), and data/infrastructure (DynamoDB, S3, CloudFormation/CDK).
- Modularized design as seen in the file tree (notably, separate directories for infrastructure, lambda functions, and UI projects) and indicate that testing, deployment scripts, and asset staging are part of the continuous deployment workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Personas
    subgraph "User Personas"
        Admin("Admin User"):::frontend
        Business("Business User"):::frontend
    end

    %% UI Layer
    subgraph "UI Layer"
        DC_UI("Deployment Dashboard UI"):::frontend
        Chat_UI("Chat UI"):::frontend
    end

    %% Content Delivery Network
    subgraph "Content Delivery Network"
        CF("CloudFront"):::frontend
    end

    %% API & Application Layer
    subgraph "API & App Layer"
        APIRest("API Gateway (REST)"):::backend
        APIWeb("API Gateway (WebSocket)"):::backend
        Lambda("Lambda Functions (Business Logic & Orchestration)"):::backend
        CustomAuth("Custom Authorizer"):::backend
    end

    %% Authentication
    subgraph "Authentication"
        Cognito("Amazon Cognito"):::backend
    end

    %% Infrastructure & Data
    subgraph "Infrastructure & Data"
        CDK("AWS CDK & CloudFormation"):::infra
        Dynamo("DynamoDB"):::database
        SQS("Amazon SQS"):::backend
        CloudWatch("CloudWatch (Monitoring)"):::monitor
        Kendra("Amazon Kendra/Knowledge Base"):::infra
        Bedrock("Amazon Bedrock (LLM Integration)"):::infra
        S3Hosting("S3 (Static Hosting & Artifacts)"):::infra
        StageAssets("Asset Staging Script"):::infra
    end

    %% Interactions: Users to UIs
    Admin -->|"access"| DC_UI
    Business -->|"access"| Chat_UI

    %% UIs to CDN
    DC_UI -->|"served via"| CF
    Chat_UI -->|"served via"| CF

    %% CDN to API Gateways
    CF -->|"routes REST requests"| APIRest
    CF -->|"routes WS connections"| APIWeb

    %% Authentication Flow
    Admin -->|"authenticate"| Cognito
    Business -->|"authenticate"| Cognito
    Cognito -->|"secures"| APIRest
    Cognito -->|"secures"| APIWeb

    %% API Gateway to Lambda and Custom Auth
    APIRest -->|"invokes"| Lambda
    APIWeb -->|"invokes"| Lambda
    APIRest -->|"validates"| CustomAuth
    APIWeb -->|"validates"| CustomAuth

    %% Lambda interactions with Data Stores and External Services
    Lambda -->|"reads/writes"| Dynamo
    Lambda -->|"fetches artifacts"| S3Hosting
    Lambda -->|"triggers async"| SQS
    Lambda -->|"reports to"| CloudWatch
    Lambda -->|"queries"| Kendra
    Lambda -->|"queries"| Bedrock

    %% Infrastructure provisioning via CDK
    CDK -->|"deploys"| CF
    CDK -->|"deploys"| APIRest
    CDK -->|"deploys"| APIWeb
    CDK -->|"deploys"| Lambda
    CDK -->|"configures"| Cognito
    CDK -->|"provisions"| Dynamo
    CDK -->|"provisions"| S3Hosting
    CDK -->|"deploys"| CloudWatch

    %% Connect Stage Assets Node to CDK (for deployment scripts)
    CDK -->|"includes"| StageAssets

    %% Click Events
    click DC_UI "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/ui-deployment"
    click Chat_UI "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/ui-chat"
    click CDK "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/infrastructure"
    click Lambda "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/lambda"
    click Cognito "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/blob/main/source/infrastructure/lib/auth/cognito-setup.ts"
    click CustomAuth "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/lambda/custom-authorizer"
    click Dynamo "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/infrastructure/lib/storage"
    click S3Hosting "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/infrastructure/lib/s3web"
    click StageAssets "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/blob/main/source/stage-assets.sh"
    click APIRest "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/infrastructure/lib/api"
    click CF "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/infrastructure/lib/s3web"
    click CloudWatch "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/tree/main/source/infrastructure/lib/metrics"
    click Kendra "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/blob/main/source/infrastructure/lib/search/kendra-knowledge-base.ts"
    click Bedrock "https://github.com/aws-solutions/generative-ai-application-builder-on-aws/blob/main/source/infrastructure/lib/bedrock-agent-stack.ts"

    %% Styles
    classDef frontend fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef backend fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef infra fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef database fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef monitor fill:#F08080,stroke:#333,stroke-width:2px;
```
