# asana/sgtm architecture

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

- Interactive diagram: https://gitdiagram.com/asana/sgtm
- Repository: https://github.com/asana/sgtm

## Overview

##### Main Components
- External Services:
- GitHub: Used for pull request events, webhooks, and GraphQL API interactions. (See modules under src/github – client, controller, GraphQL queries, models, and webhook processing).
- Asana: Used for task creation/updating based on GitHub pull requests. (See src/asana including client, controller, logic, and helpers).
- AWS: The project uses several AWS services. In the source code (under src/aws) and Terraform configuration (in terraform/sgtm-cluster), AWS is used to set up S3 for storing configuration (for example, the GitHub-to-Asana mappings), DynamoDB for Terraform state locks and mapping persistence, SQS for message handling, and Lambda functions (via API Gateway) to process webhook requests.

- Internal Core Application Logic:
- Webhook Handler: (src/handler.py and src/github/webhook.py) which processes incoming GitHub events.
- Business Logic Components: Controllers and helpers found within both the GitHub and Asana modules. These handle tasks like creating/updating Asana tasks based on the state of GitHub pull requests.
- Utility Modules: Configuration (src/config.py), logging (src/logger.py), markdown parsing (src/markdown_parser.py), and various shared helper functions (src/utils.py).

- Deployment & Infrastructure:
- Terraform & Terragrunt configurations (in the terraform directory) which describe the cloud infrastructure (API Gateway, Lambda functions, S3, DynamoDB, etc.).
- Setup scripts (in the scripts directory) that configure the infrastructure and assist with project deployment or secret management.

- GitHub sends webhook events (for pull requests, reviews, comments, etc.) to an endpoint managed by AWS API Gateway.
- API Gateway routes the events to an AWS Lambda function that executes the main handler (src/handler.py).
- The handler invokes the appropriate controllers within the GitHub module to fetch pull request details (using the GitHub GraphQL API) or process review/comment events.
- The GitHub module then determines whether any corresponding actions should be taken in Asana.
- If an action is needed, the Asana module’s client and controllers are called to create or update Asana tasks.
- The AWS module components (e.g., s3_client, dynamodb_client, and sqs_client) provide support functions such as storing configuration (the GitHub-to-Asana mapping file in S3), handling state or locks in DynamoDB, and possibly queuing messages for asynchronous processing.
- Optional features like auto-merging or auto-completing tasks can be controlled via environment variables passed during deployment (visible in README and Terraform variables).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The design clearly splits responsibilities between different modules (GitHub, Asana, AWS, and utilities).
- Modularization: Each subsystem (e.g., GitHub integration vs. Asana integration) has its own dedicated set of modules and tests.
- Serverless Architecture: The deployment leverages AWS Lambda (with API Gateway) as the entry point for webhooks.
- Infrastructure as Code (IaC): Terraform (with additional Terragrunt configuration) is used to provision and manage cloud resources.

##### Incorporate Relevant Technologies and Tools
- Python: Main development language, with pipenv for dependency management.
- AWS Services: API Gateway, Lambda, S3, DynamoDB, SQS.
- GitHub & Asana APIs: Used for interacting with external systems via requests and GraphQL.
- Terraform & Terragrunt: Used for deploying infrastructure.
- Testing Framework: Unit tests are included in the test directory for comprehensive testing, along with scripts and builders used for mocking and constructing test scenarios.

##### Specific Elements
- Clear labels for each major component or subsystem:
- “GitHub Integration Module” (with subcomponents such as GraphQL client, webhook processor, and models).
- “Asana Integration Module” (with clients, controllers, and helpers).
- “AWS Infrastructure & Supporting Services” (illustrate API Gateway, Lambda, S3, DynamoDB, SQS).
- “Deployment & Infrastructure Management” (Terraform/Terragrunt configuration).
- “Utility Components” (logger, config, markdown parser).
- For example: GitHub Webhook → API Gateway → Lambda (Handler) → GitHub/Asana Controllers.
- External systems vs. internal modules.
- Differentiation between processing components (controllers, clients, handlers) and support/infrastructure components (Terraform, AWS service clients).
- Optionally, include annotations that explain key interactions (e.g., “Auto-merge PR” feature or “Complete linked tasks on merge” flows).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Services
    subgraph "External Services"
        A("GitHub"):::external
        B("Asana API"):::external
    end

    %% AWS Infrastructure
    subgraph "AWS Infrastructure"
        C("API Gateway"):::aws
        F("AWS Service Clients & Helpers"):::aws
    end

    %% Core Application Logic
    subgraph "Core Application Logic"
        subgraph "Webhook Handler"
            H1("Handler"):::core
            WP("Webhook Processor"):::core
            H1 -->|"ForwardsEvent"| WP
        end
        D("GitHub Integration Module"):::core
        E("Asana Integration Module"):::core
        G("Utility: Config"):::utility
        H("Utility: Logger"):::utility
        I("Utility: Markdown Parser"):::utility
        J("Utility: Shared Helpers"):::utility
    end

    %% Deployment & Infrastructure Management
    subgraph "Deployment & Infra Management"
        K("Terraform & Terragrunt Configurations"):::deployment
        L("Setup & Deployment Scripts"):::deployment
    end

    %% Connections
    A -->|"WebhookEvent"| C
    C -->|"RoutesTo"| H1
    H1 -->|"ProcessesEvent"| D
    H1 -->|"ProcessesEvent"| E
    H1 -->|"UsesServiceClients"| F
    D -->|"Invokes"| E
    D -->|"UtilizesConfig"| G
    D -->|"UtilizesLogger"| H
    E -->|"UtilizesMarkdown"| I
    E -->|"UtilizesHelpers"| J
    D -->|"UsesServiceClients"| F
    E -->|"UsesServiceClients"| F
    K -->|"Provisions"| C
    K -->|"ConfiguresClients"| F
    L -->|"AssistsDeployment"| K

    %% Click Events
    click D "https://github.com/asana/sgtm/tree/master/src/github"
    click E "https://github.com/asana/sgtm/tree/master/src/asana"
    click F "https://github.com/asana/sgtm/tree/master/src/aws"
    click H1 "https://github.com/asana/sgtm/blob/master/src/handler.py"
    click WP "https://github.com/asana/sgtm/blob/master/src/github/webhook.py"
    click G "https://github.com/asana/sgtm/blob/master/src/config.py"
    click H "https://github.com/asana/sgtm/blob/master/src/logger.py"
    click I "https://github.com/asana/sgtm/blob/master/src/markdown_parser.py"
    click J "https://github.com/asana/sgtm/blob/master/src/utils.py"
    click K "https://github.com/asana/sgtm/tree/master/terraform/sgtm-cluster"
    click L "https://github.com/asana/sgtm/tree/master/scripts"

    %% Styles
    classDef external fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
    classDef aws fill:#ccffcc,stroke:#00aa00,stroke-width:2px;
    classDef core fill:#ccccff,stroke:#0000ff,stroke-width:2px;
    classDef deployment fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef utility fill:#e0e0e0,stroke:#000000,stroke-width:2px;
```
