# aws-samples/failure-analysis-assistant architecture

> Architecture diagram of the GitHub repository aws-samples/failure-analysis-assistant, 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-samples/failure-analysis-assistant
- Repository: https://github.com/aws-samples/failure-analysis-assistant

## Overview

##### Main Components
- AWS API Gateway: Acts as the HTTP endpoint (with public URL) for Slack events (such as slash commands and interactive components). Make sure to denote that API Gateway has CloudWatch logging enabled, and note that AWS WAF is recommended if deployed in production.
- Lambda Functions: Several Lambda functions are present:
- fa2-lambda: The core function that handles the main failure analysis workflow.
- findings-report: Generates detailed reports from Security Hub or GuardDuty findings.
- metrics-insight: Handles on-demand metric-related queries via Slack.
- slack-handler: Processes incoming Slack events/commands.
- Lambda Layers: Shared modules used by the Lambda functions, for example, the nodejs layer that includes modules required to support functionality (like rendering or additional libraries).
- AWS Services for Data Acquisition:
- CloudWatch Logs: The primary store for log data that are queried based on time ranges.
- Amazon Athena (optional): Used for querying logs from S3 (e.g., ALB or CloudTrail logs).
- AWS X-Ray (optional): Provides trace information when enabled.
- Amazon Bedrock / LLM: The LLM service (e.g., Claude 3 Sonnet) is invoked to process prompt templates (in lambda/lib/prompts.ts) and generate insights or summaries for incident analysis.
- CDK Deployment: Represent this component separately as it is responsible for provisioning and managing the whole infrastructure using CloudFormation through AWS CDK stacks and constructs (files in lib/stack and lib/constructs).

##### Relationships & Interactions
- The Slack event triggers the Lambda function (via API Gateway) when users interact with the presented form. Once users submit their chosen time range and event details, the Lambda function (fa2-lambda) begins processing.
- The Lambda then queries various sources (CloudWatch Logs, Athena, X-Ray) and constructs a prompt using the defined templates.
- The Lambda sends this prompt to the LLM (Amazon Bedrock) and, upon receiving a response, sends the insight back to Slack.
- For optional but additional functionality, other Lambda functions (metrics-insight and findings-report) handle specific interactions triggered by Slack slash commands.

##### Architectural Patterns & Design Principles
- Modular Microservice-based Approach: Each Lambda function is dedicated to a clear responsibility, ensuring separation of concerns.
- Event-driven Architecture: The design is heavily event-driven (triggered by Slack events and alarms) with asynchronous processing.
- Infrastructure as Code (IaC): The CDK and associated constructs/stacks indicate an IaC approach for managing resources.
- Use of Shared Libraries: Both in the lambda/lib and lambda/layers directories for common functionalities, promoting code reuse and maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Trigger
    alarm["Alarm/Notification"]:::external

    %% Client Interface
    slack["Slack (Client Interface)"]:::external

    %% AWS API Gateway
    api["AWS API Gateway"]:::compute

    %% Lambda Functions Subgraph
    subgraph "Lambda Functions"
        fa2["fa2-lambda (Failure Analysis)"]:::compute
        insight["metrics-insight (Metrics Queries)"]:::compute
        report["findings-report (Generate Reports)"]:::compute
    end

    %% Data Stores and External Services
    cw["CloudWatch Logs"]:::datastore
    athena["Amazon Athena (Optional)"]:::datastore
    xray["AWS X-Ray (Optional)"]:::datastore
    bedrock["Amazon Bedrock / LLM"]:::external

    %% Shared Library Layer
    layers["Lambda Layers (Shared Modules)"]:::compute

    %% CDK Deployment Subgraph
    subgraph "CDK Deployment (IaC)"
        cdk_primary["Primary Entry: bin/failure-analysis-assistant.ts"]:::iac
        cdk_stack["Stack: lib/stack/fa2-stack.ts"]:::iac
        cdk_fa2["Construct: lib/constructs/fa2.ts"]:::iac
        cdk_bucket["Construct: lib/constructs/bucket.ts"]:::iac
    end

    %% Flow Connections
    alarm -->|"triggers"| slack
    slack -->|"initiates"| api

    %% API Gateway triggers Lambda functions for different tasks
    api -->|"invokes"| fa2
    api -->|"invokes"| insight
    api -->|"invokes"| report

    %% Lambda fa2 workflow
    fa2 -->|"queries"| cw
    fa2 -->|"queries"| athena
    fa2 -->|"queries"| xray
    fa2 -->|"sends prompt"| bedrock
    bedrock -->|"returns insight to"| slack

    %% Shared Library Dependencies (dashed lines)
    fa2 ---|"uses"| layers
    insight ---|"uses"| layers
    report ---|"uses"| layers

    %% CDK Deployment provisions API Gateway and shared resources
    cdk_primary --> api
    cdk_stack --> api
    cdk_stack --> fa2
    cdk_stack --> insight
    cdk_stack --> report
    cdk_fa2 --> layers
    cdk_bucket --> layers

    %% Style Classes
    classDef external fill:#f9c,stroke:#333,stroke-width:2px;
    classDef compute fill:#bbf,stroke:#333,stroke-width:2px;
    classDef datastore fill:#afa,stroke:#333,stroke-width:2px;
    classDef iac fill:#fdc,stroke:#333,stroke-width:2px;

    %% Click Events
    click slack "https://github.com/aws-samples/failure-analysis-assistant/tree/main/lambda/functions/slack-handler"
    click api "https://github.com/aws-samples/failure-analysis-assistant/blob/main/lib/stack/fa2-stack.ts"
    click fa2 "https://github.com/aws-samples/failure-analysis-assistant/tree/main/lambda/functions/fa2-lambda"
    click report "https://github.com/aws-samples/failure-analysis-assistant/tree/main/lambda/functions/findings-report"
    click insight "https://github.com/aws-samples/failure-analysis-assistant/tree/main/lambda/functions/metrics-insight"
    click layers "https://github.com/aws-samples/failure-analysis-assistant/tree/main/lambda/layers/nodejs"
    click bedrock "https://github.com/aws-samples/failure-analysis-assistant/blob/main/lambda/lib/prompts.ts"
    click cdk_primary "https://github.com/aws-samples/failure-analysis-assistant/blob/main/bin/failure-analysis-assistant.ts"
    click cdk_stack "https://github.com/aws-samples/failure-analysis-assistant/blob/main/lib/stack/fa2-stack.ts"
    click cdk_fa2 "https://github.com/aws-samples/failure-analysis-assistant/blob/main/lib/constructs/fa2.ts"
    click cdk_bucket "https://github.com/aws-samples/failure-analysis-assistant/blob/main/lib/constructs/bucket.ts"
```
