How asana/sgtm works
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).