# aws-samples/dify-self-hosted-on-aws architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/dify-self-hosted-on-aws
- Repository: https://github.com/aws-samples/dify-self-hosted-on-aws

## Overview

##### Main Components
- AWS CDK Deployment/Management: Represent the CDK source (bin/ and lib/ directories) which contains the “Dify on AWS” stack definitions.
- VPC & Networking:
- VPC (network boundaries) with possibly public and private subnets.
- VPC Endpoints (as defined in lib/constructs/vpc-endpoints.ts) to route traffic without direct internet access.
- NAT instances (or NAT Gateway alternatives) if not using full NAT gateways.
- Compute (ECS Fargate):
- API and Worker Container: (defined in lib/constructs/dify-services/api.ts) hosting backend functionality.
- Web Container: (from lib/constructs/dify-services/web.ts) serving the frontend.
- Sidecar/Additional Containers: For external knowledge API and sandbox environments (see lib/constructs/dify-services/docker folder).
- Data Services:
- Aurora Serverless (Postgres), defined in lib/constructs/postgres.ts.
- ElastiCache (Redis), defined in lib/constructs/redis.ts.
- Load Balancing and Routing:
- Application Load Balancer (ALB) possibly tied with CloudFront for distributed content (see lib/constructs/alb-with-cloudfront.ts and lib/constructs/alb.ts).
- Web ACL (lib/constructs/web-acl.ts) for security enforcement.
- Additional Components:
- Email Setup (SMTP/SES) as configured in the CDK stack.
- Environment and configuration management using EnvironmentProps (lib/environment-props.ts) and VPC/VPC endpoints.
- Integration points for AWS Bedrock and external services like Notion.

##### Relationships and Interactions
- The AWS CDK code (your “deployment engine”) provisions and configures all AWS services. It creates the VPC as the underlying network, establishes ECS clusters that run containerized services (API, web, and sidecars).
- The ALB (and optional CloudFront) fronts incoming HTTP/HTTPS requests – routing them to respective ECS services.
- ECS services are connected to data stores (Aurora for the business data and Redis for caching).
- There is a bidirectional interaction between the API service and external services for knowledge base connections (i.e. the External Knowledge API container and integration with AWS Bedrock) as well as possible interactions with Notion for data import.
- Environment configuration and secrets (managed possibly via AWS Secrets Manager) help secure the integration credentials and other sensitive settings.

##### Architectural Patterns and Design Principles
- Infrastructure as Code (IaC) using AWS CDK.
- Service-oriented or microservice pattern within ECS where each containerized service is an independent unit (API, web, external knowledge API, sandbox).
- Separation of concerns: networking (VPC, endpoints), compute (ECS Fargate tasks), data (Aurora/Redis), and edge routing (ALB/CloudFront).
- Scalability and cost effectiveness: Aurora Serverless, Fargate spot capacity, NAT instances.
- Extensibility: Options for closed network deployments and integrations with external systems (Bedrock, Notion).

##### Creation Process
- In networking (VPC with subnets and endpoints) on one side.
- Optionally, include a side panel for “deployment” – illustrating the CDK codebase which orchestrates this entire setup.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Layer
    subgraph "Deployment"
        CDK_Entry("CDK Entry Points"):::deployment
        Stack_Dify("Dify On AWS Stack"):::deployment
        Stack_Useast("US-East-1 Stack"):::deployment
    end

    %% Networking Layer
    subgraph "Networking"
        VPC("VPC"):::network
        VPC_Ep("VPC Endpoints"):::network
    end

    %% Load Balancing and Routing
    subgraph "Load Balancing"
        ALB_CF("ALB/CloudFront"):::loadbalancer
        ALB_Config("ALB Config"):::loadbalancer
        Web_ACL("Web ACL"):::loadbalancer
    end

    %% Compute (ECS Fargate)
    subgraph "Compute (ECS Fargate)"
        API_Service("API & Worker Service"):::compute
        Web_Service("Web Service"):::compute
        External_Knowledge("External Knowledge API Container"):::compute
        Sandbox("Sandbox Container"):::compute
    end

    %% Data Services
    subgraph "Data Services"
        Aurora("Aurora Serverless (Postgres)"):::data
        Redis("Redis Cache"):::data
    end

    %% Additional Services
    subgraph "Additional Services"
        Email_Setup("Email Setup"):::additional
        Env_Config("Environment & Config"):::additional
        Env_Vars("Environment Variables"):::additional
    end

    %% External Integrations
    subgraph "External Integrations"
        AWS_Bedrock("AWS Bedrock"):::external
        Notion("Notion"):::external
    end

    %% User Traffic
    User_Traffic("User Traffic"):::user

    %% Connections
    User_Traffic -->|"routes"| ALB_CF
    ALB_CF -->|"to-Web"| Web_Service
    ALB_CF -->|"to-API"| API_Service
    API_Service -->|"queries"| Aurora
    API_Service -->|"caches"| Redis
    API_Service -->|"calls"| External_Knowledge
    External_Knowledge -->|"integrates"| AWS_Bedrock
    API_Service -->|"integrates"| Notion
    Env_Config -->|"configures"| API_Service
    Env_Vars -->|"sets"| API_Service

    %% Deployment provisioning arrows
    Stack_Dify -->|"provisions"| VPC
    Stack_Dify -->|"provisions"| ALB_CF
    Stack_Dify -->|"provisions"| API_Service
    Stack_Dify -->|"provisions"| Aurora
    Stack_Dify -->|"provisions"| Email_Setup
    VPC -->|"supports"| ALB_CF
    VPC -->|"supports"| API_Service
    VPC -->|"supports"| Aurora
    CDK_Entry ---|"triggers"| Stack_Dify
    CDK_Entry ---|"triggers"| Stack_Useast

    %% Styles
    classDef deployment fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef network fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef loadbalancer fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef compute fill:#DA70D6,stroke:#000,stroke-width:2px;
    classDef data fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef additional fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef user fill:#FFC0CB,stroke:#000,stroke-width:2px;

    %% Click Events for Deployment
    click CDK_Entry "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/bin/cdk.ts"
    click Stack_Dify "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/dify-on-aws-stack.ts"
    click Stack_Useast "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/us-east-1-stack.ts"

    %% Click Events for Networking
    click VPC "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/vpc.ts"
    click VPC_Ep "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/vpc-endpoints.ts"

    %% Click Events for Compute (ECS Fargate)
    click API_Service "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/dify-services/api.ts"
    click Web_Service "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/dify-services/web.ts"
    click External_Knowledge "https://github.com/aws-samples/dify-self-hosted-on-aws/tree/main/lib/constructs/dify-services/docker/external-knowledge-api"
    click Sandbox "https://github.com/aws-samples/dify-self-hosted-on-aws/tree/main/lib/constructs/dify-services/docker/sandbox"

    %% Click Events for Data Services
    click Aurora "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/postgres.ts"
    click Redis "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/redis.ts"

    %% Click Events for Load Balancing and Routing
    click ALB_CF "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/alb-with-cloudfront.ts"
    click ALB_Config "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/alb.ts"
    click Web_ACL "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/web-acl.ts"

    %% Click Events for Additional Components
    click Email_Setup "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/email.ts"
    click Env_Config "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/environment-props.ts"
    click Env_Vars "https://github.com/aws-samples/dify-self-hosted-on-aws/blob/main/lib/constructs/dify-services/environment-variables.ts"
```
