# aws-samples/sample-remote-swe-agents architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-remote-swe-agents
- Repository: https://github.com/aws-samples/sample-remote-swe-agents

## Overview

##### Main Components
- AWS Infrastructure (defined in the “cdk” directory)
– CDK constructs for provisioning AWS resources:
- Lambda functions (for handling incoming Slack webhooks)
- API Gateway (receiving requests from Slack and routing them to Lambdas)
- AppSync Events for event distribution
- DynamoDB (storing message history, job statuses, etc.)
- EC2 resources (worker units including dedicated EC2 instances and attached EBS volumes)
– Also, SSM Parameter Store is used to configure secrets (Slack tokens, GitHub tokens, etc.)
- Slack Bolt App (located in the “slack-bolt-app” directory)
– This handles the Slack App functionality and user interactions
– It translates incoming Slack messages and directs them into the AWS-driven workflow
- Worker Software Development Agents (located in the “worker” folder)
– These represent the autonomous agents that process tasks, execute commands, and interact with GitHub and other services
– Includes tools for command execution, repository management, and integration with MCP servers
- GitHub Integration
– Either via a Personal Access Token or a GitHub App (as documented)
– Configured via environment variables and SSM parameters to securely link GitHub with the AWS infrastructure

##### Relationships and Interactions
- The Slack Workflow:
– A Slack user sends a message via the Slack client.
– The Slack app (Slack Bolt App) receives the message via a webhook.
– API Gateway accepts the webhook and forwards it to a Lambda function.
– The Lambda function publishes events to AppSync; meanwhile, message history is logged in DynamoDB.
- The Worker System:
– When a new session (or Slack thread) is initiated, the Worker Manager (defined in CDK constructs and implemented in the “worker” project) is notified.
– It provisions a dedicated Worker Unit (EC2 instance with EBS) that subscribes to AppSync events.
– The Worker Unit processes the task (e.g., handling a code feature/bug request) and ultimately pushes status updates or replies back to the Slack channel.
- GitHub Integration:
– The agent interacts with GitHub (through either a PAT or a GitHub App) to perform repository operations, create and link issues, and manage pull requests as described in README.
- MCP Integration:
– Optional integration with MCP servers is configured (via the “claude_desktop_config.json” in the worker directory) and can be represented as an external service used by agents.

##### Architectural Patterns & Design Principles
- Serverless & Event-Driven:
– Lambda functions and AppSync events highlight an event-driven architecture to handle incoming Slack events and associated actions.
- Modular Infrastructure as Code:
– The use of AWS CDK is modular. The “cdk/lib/constructs” folder shows dedicated modules for EC2 worker units, Slack Bolt, storage, and more.
- Separation of Concerns:
– The project is split into discrete parts: infrastructure (cdk), Slack app logic (slack-bolt-app), and worker processing (worker).
- Secure & Configurable:
– Secrets and tokens are managed via SSM Parameter Store. Environment variables (e.g., for GitHub App and Slack restrictions) provide runtime configurability.

- Then, incorporate the detailed internal components from the CDK configuration:
– Show how the infrastructure deploys serverless functions (API Gateway and Lambda) that bridge Slack and worker management.
– Indicate the flow of events (from Slack message reception, logging in DynamoDB, to assignment to worker units).
- Configuration and integration points:
– Mark where environment configuration, SSM parameters, and GitHub integration feed into the system.
– Include any security aspects such as restricted Slack user access.
– Clear labels for every component and sub-component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    SlackUser("Slack User"):::external
    SlackPlatform("Slack Platform"):::external

    %% Slack Bolt App Subgraph
    subgraph "Slack Bolt App"
        SA["Slack App (app.ts)"]:::slack
        SL["Slack Lambda (lambda.ts)"]:::slack
    end

    %% AWS Infrastructure Subgraph
    subgraph "AWS Infrastructure"
        API["API Gateway"]:::aws
        LF["Lambda Function"]:::aws
        AS["AppSync"]:::aws
        DDB["DynamoDB"]:::aws
        SSM["SSM Parameter Store"]:::aws
        EC2W["EC2 Worker Unit"]:::aws
        %% AWS CDK Constructs Subgraph
        subgraph "AWS CDK Constructs"
            EC2C["EC2 Construct"]:::aws
            SLACKC["Slack Bolt Construct"]:::aws
            STORC["Storage Construct"]:::aws
            WORKERC["Worker Construct"]:::aws
        end
    end

    %% Worker Agents Subgraph
    subgraph "Worker Agents"
        WSA["Worker Software Agent"]:::worker
        WAgentModules["Worker Agent Modules"]:::worker
        CDConfig["Claude Desktop Config"]:::worker
        WREADME["Worker README"]:::worker
    end

    %% External Services Subgraph
    subgraph "External Services"
        GI["GitHub Integration Tool"]:::external
        MCP["MCP Servers"]:::external
    end

    %% Flow Connections
    SlackUser -->|"SendsMessage"| SlackPlatform
    SlackPlatform -->|"SlackWebhook"| SL
    SL -->|"forwardsRequest"| API
    API -->|"routesRequest"| LF
    LF -->|"publishEvent"| AS
    LF -->|"logMessage"| DDB
    SSM -->|"providesSecrets"| LF
    AS -->|"triggerWorker"| EC2W
    EC2W -->|"assignTask"| WSA
    SSM -->|"providesConfig"| WSA
    WSA -->|"sendResponse"| SlackPlatform
    WSA -->|"repoUpdate"| GI
    WSA -->|"uses"| WAgentModules
    WSA -->|"configuredBy"| CDConfig
    WSA -->|"docs"| WREADME
    WSA -->|"mcpIntegration"| MCP

    %% Styles
    classDef aws fill:#CCF,stroke:#333,stroke-width:2px;
    classDef slack fill:#CFF,stroke:#333,stroke-width:2px;
    classDef worker fill:#CFC,stroke:#333,stroke-width:2px;
    classDef external fill:#FDC,stroke:#333,stroke-width:2px;

    class SlackUser,SlackPlatform,GI,MCP external;
    class SA,SL slack;
    class API,LF,AS,DDB,SSM,EC2W,EC2C,SLACKC,STORC,WORKERC aws;
    class WSA,WAgentModules,CDConfig,WREADME worker;

    %% Click Events for AWS CDK Constructs
    click EC2C "https://github.com/aws-samples/sample-remote-swe-agents/tree/main/cdk/lib/constructs/ec2-gc"
    click SLACKC "https://github.com/aws-samples/sample-remote-swe-agents/tree/main/cdk/lib/constructs/slack-bolt"
    click STORC "https://github.com/aws-samples/sample-remote-swe-agents/blob/main/cdk/lib/constructs/storage.ts"
    click WORKERC "https://github.com/aws-samples/sample-remote-swe-agents/tree/main/cdk/lib/constructs/worker"

    %% Click Events for Slack Bolt App
    click SA "https://github.com/aws-samples/sample-remote-swe-agents/blob/main/slack-bolt-app/src/app.ts"
    click SL "https://github.com/aws-samples/sample-remote-swe-agents/blob/main/slack-bolt-app/src/lambda.ts"

    %% Click Events for Worker Software Development Agents
    click WREADME "https://github.com/aws-samples/sample-remote-swe-agents/blob/main/worker/README.md"
    click CDConfig "https://github.com/aws-samples/sample-remote-swe-agents/blob/main/worker/claude_desktop_config.json"
    click WAgentModules "https://github.com/aws-samples/sample-remote-swe-agents/tree/main/worker/src/agent"

    %% Click Event for GitHub Integration
    click GI "https://github.com/aws-samples/sample-remote-swe-agents/blob/main/worker/src/agent/tools/command-execution/github.ts"
```
