AWS Cost Alerting

Plan Metadata

• Plan type: plan
• Parent plan: N/A
• Depends on: N/A
• Status: documentation

// TODO @blaine validate this please

System Intent

• What is being built: Contract for infrastructure-level budget alerts, EC2 state notifications, and scheduled cost reporting to Discord.
• Primary consumer(s): Platform operators and finance/ops visibility workflows.
• Boundary (black-box scope only): AWS Budgets/SNS/EventBridge/Lambda deployment surfaces, IAM/runtime wiring, SSM-backed Discord configuration, and Discord webhook/interaction delivery behavior.

Stage Gate Tracker

• [x] Stage 1 Mermaid approved
• [x] Stage 2 I/O contracts approved
• [x] Stage 3 acceptance criteria and plan-first tests approved

1. Mermaid Diagram

Reference: .agent/skills/create-mermaid-diagram/SKILL.md

flowchart TD
  H[Interaction Build Script — main/devops/lambdas/discord_interaction/build.sh] -->|produces discord_interaction_pkg artifact for terraform archive| A[Cost Alerting Infrastructure Wiring — main/devops/cost_alerts.tf]
  A -->|provisions alerts lambda wiring and ec2 budget trigger routes| C[Discord Alerts Handler — main/devops/lambdas/discord_alerts/handler.py]
  A -->|provisions report lambda wiring and daily schedule routes| D[Daily Cost Report Handler — main/devops/lambdas/discord_alerts/cost_report.py]
  A -->|provisions interaction lambda and function URL output| E[Discord Interaction Handler — main/devops/lambdas/discord_interaction/handler.py]
  A -->|defines required SSM parameter names| F[Discord Config Wiring — main/devops/cost_alerts.tf]
  F -->|DISCORD_WEBHOOK_URL env value| C
  F -->|DISCORD_WEBHOOK_URL env value| D
  F -->|DISCORD_APP_ID and DISCORD_PUBLIC_KEY env values| E
  D -->|aws cost and instance query request| G[Shared AWS Report Builder — main/devops/lambdas/discord_alerts/aws_report.py]
  E -->|slash command report query request| G

  classDef unchanged fill:#d3d3d3,stroke:#666,stroke-width:1px;
  classDef updated fill:#ffe58a,stroke:#666,stroke-width:1px;
  classDef deleted fill:#f4a6a6,stroke:#666,stroke-width:1px;
  classDef created fill:#a8e6a3,stroke:#666,stroke-width:1px;

  class A,C,D,E,F,G,H unchanged;

File status note: this is a documentation-only update, so all runtime nodes above are marked unchanged. External providers are intentionally omitted as black boxes. Terraform .tf implementation details are documented in contract sections below, not in this Mermaid diagram.

2. Black-Box Inputs and Outputs

Keep this short. Define types in JSON-style blocks and capture each flow with path-level rows.

AWS Resource Inventory

The infrastructure deployment in main/devops/cost_alerts.tf is expected to manage these AWS resources:

Global Types

Define shared types used across multiple flows.

DiscordWebhookMessage {
  content: string
  embeds?: list
}

BudgetAlertEvent {
  event_source: "aws:sns"
  sns_subject?: string
  sns_message: string
}

StandardError {
  status?: number
  code?: string
  message: string
}

DiscordSupportInputs {
  discord_webhook_url: string
  discord_app_id: string
  discord_public_key: string
  discord_interaction_endpoint_url_configured: boolean
  discord_command_scope?: "global" | "guild"
  discord_test_guild_id?: string
}

CostAlertingInfrastructureDeploymentInput {
  terraform_apply: boolean
  aws_region: string
  interaction_build_artifact_ready: boolean
  required_ssm_parameters: [
    "/encache/discord/webhook_url",
    "/encache/discord/app_id",
    "/encache/discord/public_key"
  ]
}

CostAlertingInfrastructureDeploymentOutput {
  resources_provisioned: {
    sns_topic_cost_alerts: string
    lambda_discord_alerts: string
    lambda_cost_report: string
    lambda_discord_interaction: string
    event_rule_ec2_state: string
    event_rule_daily_cost_report: string
    budget_encache_monthly: string
  }
  deployment_outputs: {
    discord_interaction_url: string
  }
}

DeploymentReadinessState {
  terraform_apply_succeeded: boolean
  slash_commands_routable: boolean
}

Flow: cost-alerting-infrastructure-deployment, N/A

Type Definitions

CostAlertingInfrastructureDeploymentContractInput = CostAlertingInfrastructureDeploymentInput

CostAlertingInfrastructureDeploymentContractOutput = CostAlertingInfrastructureDeploymentOutput

Paths

Flow: budget-alert-dispatch, N/A

Type Definitions

BudgetAlertDispatchInput {
  sns_records: list<BudgetAlertEvent>
}

BudgetAlertDispatchOutput {
  status_code: 200
  delivery_attempted: boolean
}

Paths

Flow: ec2-state-alert-dispatch, N/A

Type Definitions

Ec2StateAlertInput {
  detail-type: "EC2 Instance State-change Notification"
  detail.state: string
  detail.instance-id: string
}

Ec2StateAlertOutput {
  status_code: 200
  delivery_attempted: boolean
}

Paths

Flow: daily-cost-report, N/A

Type Definitions

DailyCostReportInput {
  scheduled_event: cron(0 14 * * ? *)
}

DailyCostReportOutput {
  status_code: 200
  report_body: string
  delivery_attempted: boolean
  warning_sections?: list<"cost" | "instance_status">
}

Paths

Flow: discord-slash-command-interaction, N/A

Type Definitions

DiscordSlashCommandInput {
  interaction_type: number
  command_name?: "help" | "cost" | "status"
  interaction_token?: string
  signature_headers: map<string, string>
}

DiscordSlashCommandOutput {
  status_code: 200 | 400 | 401
  interaction_response_type?: 1 | 4 | 5
  followup_delivery?: boolean
}

Paths

Flow: discord-support-intake, N/A

Type Definitions

DiscordSupportIntakeInput {
  user_provided_values: DiscordSupportInputs
}

DiscordSupportIntakeOutput {
  completeness: "complete" | "incomplete"
  missing_fields?: list<string>
}

Paths

3. Acceptance Criteria and Plan-First Tests

Operational prerequisites: 1. Fill the in-plan Discord intake template with values. 2. Run main/devops/lambdas/discord_interaction/build.sh before terraform apply. 3. Confirm target Discord channel for webhook alerts and reports. 4. Optionally define command rollout strategy (global vs guild) in the intake template.

4. Pseudocode / Technical Details for Critical Flows (Optional)

Deployment Prerequisites (Technical)

Discord Inputs Required From User

Before implementation or terraform apply, complete this in-plan Discord intake section.

Operational rollout inputs not consumed directly by current runtime: | optional-item | purpose | value | updated | | --- | --- | --- | --- | | discord_command_scope | command rollout strategy only (global or guild) | TBD by user | | | discord_test_guild_id | faster testing iteration for guild-scoped command registration | optional; recommended | |

Discord Intake Template

Do not commit real secrets. Store secret values in AWS SSM Parameter Store and keep this plan table as status-only.

Discord Setup Checklist

• [ ] Confirm the Discord channel where budget alerts and daily reports should be posted.
• [ ] Create or select incoming webhook for that channel.
• [ ] Create or verify the Discord application for slash commands.
• [ ] Capture Application ID and Public Key from Discord Developer Portal.
• [ ] Set Discord Interactions Endpoint URL to Terraform output discord_interaction_url.
• [ ] Optionally decide and record command scope (global or guild).
• [ ] If using guild scope, optionally provide discord_test_guild_id.

AWS SSM Parameter Mapping

aws ssm put-parameter \
  --name /encache/discord/webhook_url \
  --value "<discord_webhook_url>" \
  --type SecureString \
  --overwrite \
  --region us-east-1

aws ssm put-parameter \
  --name /encache/discord/app_id \
  --value "<discord_app_id>" \
  --type String \
  --overwrite \
  --region us-east-1

aws ssm put-parameter \
  --name /encache/discord/public_key \
  --value "<discord_public_key>" \
  --type String \
  --overwrite \
  --region us-east-1

Discord Intake Sign-off

Implementation Prerequisites

• Required SSM parameters must exist in AWS before deployment:
• /encache/discord/webhook_url
• /encache/discord/app_id
• /encache/discord/public_key
• Required build artifact must exist before terraform apply:
• run main/devops/lambdas/discord_interaction/build.sh to populate main/devops/.build/discord_interaction_pkg

• Required owner sign-off for Discord intake must be present before deployment validation.

• Flow name:: alert-pipeline

  receive budget/scheduled/state event
  transform event into Discord payload
  read webhook from secure config
  POST payload to Discord webhook
  

• Flow name:: slash-command-pipeline

  receive Discord interaction HTTP payload
  verify ed25519 signature with DISCORD_PUBLIC_KEY
  if command is help then return immediate response
  if command is cost or status then return deferred response
  self invoke lambda async, build AWS report, patch deferred Discord message
  

• Flow name:: infrastructure-deployment-pipeline

  validate required Discord inputs from in-plan intake template
  write Discord inputs to required SSM parameter names
  run main/devops/lambdas/discord_interaction/build.sh
  run terraform apply for main/devops/cost_alerts.tf
  read discord_interaction_url output
  set Discord interactions endpoint URL in Discord Developer Portal
  run command and webhook smoke tests
  

• Implementation notes: Runtime readiness requires completed Discord intake values and the interaction lambda build artifact.

5. Handoff to Related Plan Reconciliation

After all stages are approved, apply .agent/skills/reconcile-plans/SKILL.md to propagate contract updates across linked plans.