DEV Community: Emmanuel Ulu

From SAM to Terraform Rebuilding My Nigeria Power Outage Tracker with Modules

Emmanuel Ulu — Wed, 01 Jul 2026 07:53:04 +0000

INTRODUCTION

A few months ago I built a serverless power outage reporting system for Nigeria using AWS SAM. Citizens could submit outage reports via API, the system stored them in DynamoDB, and SNS sent email alerts when a threshold was hit.
It worked. But the infrastructure lived in a single template.yaml file with no modularity, no CloudWatch dashboard, no Dead Letter Queue, and the alert threshold was hardcoded.
So I rebuilt it from scratch using Terraform modules. Same problem. Same architecture. Better infrastructure.
This is Part 2. If you missed Part 1, read it here first: How I Built a Serverless Power Outage Tracker for Nigeria on AWS.

The Architecture

The event-driven pipeline looks like this:

User
  ↓
API Gateway (HTTP API)
  ↓
Lambda Validator    → SQS Dead Letter Queue (failed reports)
  ↓
SQS Queue
  ↓
Lambda Enricher     → DynamoDB + SNS alert (threshold exceeded)
  ↓
Lambda Query        ← GET /reports
  ↓
Lambda Aggregator   ← daily summary (EventBridge scheduled)

Every component is serverless. No servers to manage, no idle compute costs, pay only when reports come in.

The Architecture Drawing

The Terraform Module Structure

Instead of one giant template I split everything into 5 independent modules:

terraform/
├── modules/
│   ├── api/           # API Gateway HTTP API + routes + Lambda permissions
│   ├── compute/       # IAM role, Lambda functions, SQS event source mapping
│   ├── messaging/     # SQS queue, Dead Letter Queue, SNS topic + subscription
│   ├── observability/ # CloudWatch log groups, alarms, dashboard
│   └── storage/       # DynamoDB table with GSI and TTL
└── environments/
    └── dev/           # Root module wiring everything together

Each module has one job. The messaging module doesn't know about Lambda. The compute module doesn't know about API Gateway. They communicate through outputs and inputs only.

Module 1 — Storage

The DynamoDB table stores every outage report with 3 key design decisions:
Partition key + sort key:

hash_key  = "LGA"        # Local Government Area e.g. Ikeja
range_key = "timestamp"  # ISO 8601 timestamp

This lets you query all reports for a specific LGA efficiently.
Global Secondary Index for state-level queries:

global_secondary_index {
  name            = "StateIndex"
  hash_key        = "state"
  range_key       = "timestamp"
  projection_type = "ALL"
}

Query all outages in Lagos State without scanning the entire table.
TTL — auto-expire old records:

ttl {
  attribute_name = "expiry"
  enabled        = true
}

Records automatically delete after 90 days. No manual cleanup, no growing storage costs.

Module 2 — Messaging

Three resources with one important design decision — the Dead Letter Queue:

resource "aws_sqs_queue" "dlq" {
  name                      = "${var.project_name}-outage-dlq"
  message_retention_seconds = 1209600  # 14 days
}

resource "aws_sqs_queue" "outage_queue" {
  name                       = "${var.project_name}-outage-queue"
  receive_wait_time_seconds  = 10      # long polling
  visibility_timeout_seconds = 30

  redrive_policy = jsonencode({
    deadLetterTargetArn = aws_sqs_queue.dlq.arn
    maxReceiveCount     = 3
  })
}

Why the DLQ matters:
Without a DLQ, if the enricher Lambda fails to process a message it retries indefinitely. After 3 failed attempts the message disappears. You never know it failed.
With a DLQ, after 3 failed attempts the message moves to the DLQ where it stays for 14 days. You can investigate, fix the bug, and replay the message. No data loss.
Long polling (receive_wait_time_seconds = 10) reduces empty API calls to SQS — Lambda waits up to 10 seconds for messages before returning empty. Fewer API calls, lower cost.

Module 3 — Compute

Four Lambda functions, one IAM role, least privilege policies:

resource "aws_iam_role_policy" "lambda_sqs" {
  policy = jsonencode({
    Statement = [{
      Effect = "Allow"
      Action = [
        "sqs:SendMessage",
        "sqs:ReceiveMessage",
        "sqs:DeleteMessage",
        "sqs:GetQueueAttributes"
      ]
      Resource = [var.queue_arn, var.dlq_arn]
    }]
  })
}

Each policy only grants what's needed. Lambda can send to SQS but cannot delete tables. Lambda can write to DynamoDB but cannot access S3. Least privilege at every layer.
The SQS event source mapping connects the queue to the enricher Lambda automatically:

resource "aws_lambda_event_source_mapping" "sqs_enricher" {
  event_source_arn = var.queue_arn
  function_name    = aws_lambda_function.enricher.arn
  batch_size       = 10
}

When messages arrive in SQS, Lambda polls and processes them in batches of up to 10. No manual polling code needed.
The alert threshold is a variable:

variable "alert_threshold" {
  type    = number
  default = 3
}

Change it in terraform.tfvars and redeploy. No code changes needed:

alert_threshold = 5  # require 5 reports before alerting

Module 4 — API

HTTP API Gateway with two routes:

resource "aws_apigatewayv2_route" "post_reports" {
  route_key = "POST /reports"
  target    = "integrations/${aws_apigatewayv2_integration.validator.id}"
}

resource "aws_apigatewayv2_route" "get_reports" {
  route_key = "GET /reports"
  target    = "integrations/${aws_apigatewayv2_integration.query.id}"
}

POST /reports routes to the validator Lambda. GET /reports routes to the query Lambda. CORS is enabled so a frontend can call it directly from the browser.

Module 5 — Observability

This was missing entirely from the SAM version. Four CloudWatch log groups, alarms on Lambda errors, and a dashboard:

resource "aws_cloudwatch_metric_alarm" "dlq_messages" {
  alarm_name          = "${var.project_name}-dlq-messages"
  metric_name         = "ApproximateNumberOfMessagesVisible"
  namespace           = "AWS/SQS"
  threshold           = 0
  alarm_description   = "Messages are landing in the Dead Letter Queue"

  dimensions = {
    QueueName = "${var.project_name}-outage-dlq"
  }
}

The DLQ alarm is the most important one. If even one message lands in the DLQ something is wrong. Threshold of 0 means the alarm fires immediately.

The Proof

Submit an outage report:

curl -X POST https://your-api-id.execute-api.eu-west-1.amazonaws.com/reports \
  -H "Content-Type: application/json" \
  -d '{
    "lga": "Ikeja",
    "state": "Lagos",
    "reporter_name": "Emmanuel Ulu",
    "description": "Power outage on Allen Avenue since 6am"
  }'

{"message": "Outage report received", "report_id": "6765dd6f-cbbd-4900-a607-b542e5720487"}

Query reports for Ikeja:

curl "https://your-api-id.execute-api.eu-west-1.amazonaws.com/reports?lga=Ikeja"

{"count": 4, "reports": [...]}

After the 3rd report from the same LGA an email alert fires:

Power outage alert for Ikeja, Lagos.
4 reports received today.
Latest report: Generator running low on fuel, still no NEPA
Reported by: Bola
Time: 2026-06-27T21:04:45

SAM vs Terraform — What Actually Changed

Feature	SAM Version	Terraform Version
IaC tool	AWS SAM	Terraform
State management	CloudFormation	S3 backend with native locking
Module structure	Single template	5 independent modules
Dead Letter Queue	No	Yes
CloudWatch dashboard	No	Yes
Alert threshold	Hardcoded	Configurable variable
Observability	Basic logs	Log groups, alarms, dashboard

Key Lessons

The DLQ is not optional
Without it you have no idea when messages fail. Every production SQS queue needs a DLQ.
Long polling saves money
receive_wait_time_seconds = 10 cuts empty SQS API calls significantly. Small change, real savings at scale.
TTL is free cleanup
DynamoDB TTL automatically removes expired items. No Lambda scheduled to delete old records, no growing storage costs.
Modules make variables powerful
The alert threshold is a number in terraform.tfvars. Change it, run terraform apply, done. In the SAM version you would have to edit Python code, redeploy, and hope nothing broke.
Observability is infrastructure
CloudWatch dashboards and alarms should be provisioned with the same code that provisions the app. Not added later when something breaks.

What's Next

Add EventBridge scheduled trigger for the daily aggregator summary
Add X-Ray tracing across the full pipeline
Build a simple frontend on S3 and CloudFront to visualize outages on a map
Add VPC endpoints so Lambda never touches the public internet

Screenshots

Resources

GitHub: nigeria-outage-tracker
Part 1: How I Built a Serverless Power Outage Tracker for Nigeria on AWS
Terraform AWS Provider docs: registry.terraform.io/providers/hashicorp/aws

From SAM to Terraform Rebuilding My Nigeria Power Outage Tracker with Modules

Emmanuel Ulu — Wed, 01 Jul 2026 07:53:04 +0000

INTRODUCTION

The Architecture

The event-driven pipeline looks like this:

User
  ↓
API Gateway (HTTP API)
  ↓
Lambda Validator    → SQS Dead Letter Queue (failed reports)
  ↓
SQS Queue
  ↓
Lambda Enricher     → DynamoDB + SNS alert (threshold exceeded)
  ↓
Lambda Query        ← GET /reports
  ↓
Lambda Aggregator   ← daily summary (EventBridge scheduled)

Every component is serverless. No servers to manage, no idle compute costs, pay only when reports come in.

The Architecture Drawing

The Terraform Module Structure

Instead of one giant template I split everything into 5 independent modules:

terraform/
├── modules/
│   ├── api/           # API Gateway HTTP API + routes + Lambda permissions
│   ├── compute/       # IAM role, Lambda functions, SQS event source mapping
│   ├── messaging/     # SQS queue, Dead Letter Queue, SNS topic + subscription
│   ├── observability/ # CloudWatch log groups, alarms, dashboard
│   └── storage/       # DynamoDB table with GSI and TTL
└── environments/
    └── dev/           # Root module wiring everything together

Each module has one job. The messaging module doesn't know about Lambda. The compute module doesn't know about API Gateway. They communicate through outputs and inputs only.

Module 1 — Storage

The DynamoDB table stores every outage report with 3 key design decisions:
Partition key + sort key:

hash_key  = "LGA"        # Local Government Area e.g. Ikeja
range_key = "timestamp"  # ISO 8601 timestamp

This lets you query all reports for a specific LGA efficiently.
Global Secondary Index for state-level queries:

global_secondary_index {
  name            = "StateIndex"
  hash_key        = "state"
  range_key       = "timestamp"
  projection_type = "ALL"
}

Query all outages in Lagos State without scanning the entire table.
TTL — auto-expire old records:

ttl {
  attribute_name = "expiry"
  enabled        = true
}

Records automatically delete after 90 days. No manual cleanup, no growing storage costs.

Module 2 — Messaging

Three resources with one important design decision — the Dead Letter Queue:

resource "aws_sqs_queue" "dlq" {
  name                      = "${var.project_name}-outage-dlq"
  message_retention_seconds = 1209600  # 14 days
}

resource "aws_sqs_queue" "outage_queue" {
  name                       = "${var.project_name}-outage-queue"
  receive_wait_time_seconds  = 10      # long polling
  visibility_timeout_seconds = 30

  redrive_policy = jsonencode({
    deadLetterTargetArn = aws_sqs_queue.dlq.arn
    maxReceiveCount     = 3
  })
}

Module 3 — Compute

Four Lambda functions, one IAM role, least privilege policies:

resource "aws_iam_role_policy" "lambda_sqs" {
  policy = jsonencode({
    Statement = [{
      Effect = "Allow"
      Action = [
        "sqs:SendMessage",
        "sqs:ReceiveMessage",
        "sqs:DeleteMessage",
        "sqs:GetQueueAttributes"
      ]
      Resource = [var.queue_arn, var.dlq_arn]
    }]
  })
}

resource "aws_lambda_event_source_mapping" "sqs_enricher" {
  event_source_arn = var.queue_arn
  function_name    = aws_lambda_function.enricher.arn
  batch_size       = 10
}

When messages arrive in SQS, Lambda polls and processes them in batches of up to 10. No manual polling code needed.
The alert threshold is a variable:

variable "alert_threshold" {
  type    = number
  default = 3
}

Change it in terraform.tfvars and redeploy. No code changes needed:

alert_threshold = 5  # require 5 reports before alerting

Module 4 — API

HTTP API Gateway with two routes:

resource "aws_apigatewayv2_route" "post_reports" {
  route_key = "POST /reports"
  target    = "integrations/${aws_apigatewayv2_integration.validator.id}"
}

resource "aws_apigatewayv2_route" "get_reports" {
  route_key = "GET /reports"
  target    = "integrations/${aws_apigatewayv2_integration.query.id}"
}

POST /reports routes to the validator Lambda. GET /reports routes to the query Lambda. CORS is enabled so a frontend can call it directly from the browser.

Module 5 — Observability

This was missing entirely from the SAM version. Four CloudWatch log groups, alarms on Lambda errors, and a dashboard:

resource "aws_cloudwatch_metric_alarm" "dlq_messages" {
  alarm_name          = "${var.project_name}-dlq-messages"
  metric_name         = "ApproximateNumberOfMessagesVisible"
  namespace           = "AWS/SQS"
  threshold           = 0
  alarm_description   = "Messages are landing in the Dead Letter Queue"

  dimensions = {
    QueueName = "${var.project_name}-outage-dlq"
  }
}

The DLQ alarm is the most important one. If even one message lands in the DLQ something is wrong. Threshold of 0 means the alarm fires immediately.

The Proof

Submit an outage report:

curl -X POST https://your-api-id.execute-api.eu-west-1.amazonaws.com/reports \
  -H "Content-Type: application/json" \
  -d '{
    "lga": "Ikeja",
    "state": "Lagos",
    "reporter_name": "Emmanuel Ulu",
    "description": "Power outage on Allen Avenue since 6am"
  }'

{"message": "Outage report received", "report_id": "6765dd6f-cbbd-4900-a607-b542e5720487"}

Query reports for Ikeja:

curl "https://your-api-id.execute-api.eu-west-1.amazonaws.com/reports?lga=Ikeja"

{"count": 4, "reports": [...]}

After the 3rd report from the same LGA an email alert fires:

Power outage alert for Ikeja, Lagos.
4 reports received today.
Latest report: Generator running low on fuel, still no NEPA
Reported by: Bola
Time: 2026-06-27T21:04:45

SAM vs Terraform — What Actually Changed

Feature	SAM Version	Terraform Version
IaC tool	AWS SAM	Terraform
State management	CloudFormation	S3 backend with native locking
Module structure	Single template	5 independent modules
Dead Letter Queue	No	Yes
CloudWatch dashboard	No	Yes
Alert threshold	Hardcoded	Configurable variable
Observability	Basic logs	Log groups, alarms, dashboard

Key Lessons

The DLQ is not optional
Without it you have no idea when messages fail. Every production SQS queue needs a DLQ.
Long polling saves money
receive_wait_time_seconds = 10 cuts empty SQS API calls significantly. Small change, real savings at scale.
TTL is free cleanup
DynamoDB TTL automatically removes expired items. No Lambda scheduled to delete old records, no growing storage costs.
Modules make variables powerful
The alert threshold is a number in terraform.tfvars. Change it, run terraform apply, done. In the SAM version you would have to edit Python code, redeploy, and hope nothing broke.
Observability is infrastructure
CloudWatch dashboards and alarms should be provisioned with the same code that provisions the app. Not added later when something breaks.

What's Next

Add EventBridge scheduled trigger for the daily aggregator summary
Add X-Ray tracing across the full pipeline
Build a simple frontend on S3 and CloudFront to visualize outages on a map
Add VPC endpoints so Lambda never touches the public internet

Screenshots

Resources

GitHub: nigeria-outage-tracker
Part 1: How I Built a Serverless Power Outage Tracker for Nigeria on AWS
Terraform AWS Provider docs: registry.terraform.io/providers/hashicorp/aws

How I Built a Full High Availability AWS Infrastructure with Terraform Modules

Emmanuel Ulu — Wed, 24 Jun 2026 13:49:58 +0000

Introduction

Most AWS tutorials teach you how to launch a single EC2 instance in a public subnet and call it a day. That's fine for learning the basics, but it's nowhere near what production infrastructure looks like.
In this article I'll walk you through how I designed and deployed a full multi-tier, multi-AZ High Availability infrastructure on AWS written entirely in Terraform, structured as reusable modules. By the end you'll understand not just what I built, but why each decision was made.
This is part of my AWS SAA-C03 certification preparation as an AWS Community Builder 2026 (Serverless track).

What Does "High Availability" Actually Mean?

High Availability means your system keeps running even when something fails. In AWS, the primary failure unit is an Availability Zone a physically separate data centre within a region.

True HA means no single AZ failure can bring your application down. That requires every tier network, compute, and database to span multiple AZs.

Here's what most people get wrong: they put their EC2 instances in two AZs but share a single NAT Gateway in one AZ. When that AZ goes down, all outbound traffic from private subnets dies even the instances in the healthy AZ. True HA requires one NAT Gateway per AZ.

Architecture Drawing

Architecture Overview

The infrastructure spans 3 Availability Zones in eu-west-1 (Ireland) across 4 tiers:

Internet
    |
Route 53 (app.skylumanex.click)
    |
Application Load Balancer (3 public subnets)
    |
Auto Scaling Group (3 private app subnets)
    |
RDS MySQL Multi-AZ (3 private DB subnets)

Every tier lives in its own subnet type, in its own security group, with tightly scoped ingress rules.

Terraform Module Structure

modules/
├── network/      # VPC, subnets, IGW, NAT, route tables
├── compute/      # Security groups, ALB, ASG, CloudWatch
├── database/     # RDS Multi-AZ, DB subnet group
└── dns/          # Route 53 alias + health check
environments/
└── dev/          # Root module wiring everything together

Each module has exactly 3 files: main.tf, variables.tf, and outputs.tf. Modules communicate through outputs and inputs — the networking module outputs VPC ID and subnet IDs, the compute module takes those as inputs, the database module takes the app security group ID from compute to scope its DB ingress rules.

Module 1 — Networking

The networking module creates the entire network foundation:

1 VPC (10.0.0.0/16)
3 public subnets (one per AZ) for the ALB and NAT Gateways
3 private app subnets (one per AZ) for EC2 instances
3 private DB subnets (one per AZ) for RDS
1 Internet Gateway
NAT Gateway(s) configurable via single_nat_gateway toggle
Route tables 1 public, 1 private per AZ

The NAT Gateway decision:

variable "single_nat_gateway" {
  type    = bool
  default = true  # cost-optimized for dev
}

locals {
  nat_count = var.single_nat_gateway ? 1 : length(local.azs)
}

Flip single_nat_gateway = false in production and you get one NAT Gateway per AZ true HA outbound routing at ~$97/month. Keep it true for dev at ~$33/month.

Dynamic AZ lookup no hardcoded AZ names:

data "aws_availability_zones" "available" {
  state = "available"
}

locals {
  azs = slice(data.aws_availability_zones.available.names, 0, 3)
}

This makes the module region-agnostic. Deploy to us-east-1 and it automatically picks the right AZs.

Module 2 — Compute

The compute module creates the application layer:
Two security groups with layered access:

# ALB SG — internet can reach the ALB on port 80
resource "aws_security_group" "alb" {
  ingress {
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# App SG — only the ALB can reach the EC2 instances
resource "aws_security_group" "app" {
  ingress {
    from_port       = 80
    to_port         = 80
    protocol        = "tcp"
    security_groups = [aws_security_group.alb.id]
  }
}

EC2 instances are in private subnets and only accept traffic that came through the ALB. They are never directly reachable from the internet.

Launch template with security best practices:

metadata_options {
  http_endpoint               = "enabled"
  http_tokens                 = "required"  # enforces IMDSv2
  http_put_response_hop_limit = 1
}

monitoring {
  enabled = true  # detailed CloudWatch metrics
}

Auto Scaling with CloudWatch alarms:

resource "aws_cloudwatch_metric_alarm" "cpu_high" {
  comparison_operator = "GreaterThanThreshold"
  threshold           = var.cpu_high_threshold  # default 60%
  alarm_actions       = [aws_autoscaling_policy.scale_out.arn]
}

resource "aws_cloudwatch_metric_alarm" "cpu_low" {
  comparison_operator = "LessThanThreshold"
  threshold           = var.cpu_low_threshold   # default 20%
  alarm_actions       = [aws_autoscaling_policy.scale_in.arn]
}

Module 3 — Database

RDS MySQL with Multi-AZ the core HA database setting:

resource "aws_db_instance" "this" {
  engine         = var.db_engine
  instance_class = var.db_instance_class
  multi_az       = true              # synchronous standby + auto failover
  storage_encrypted = true           # encrypted at rest
  storage_type      = "gp3"          # faster and cheaper than gp2
  deletion_protection = true         # safety guardrail
  backup_retention_period = 7        # 7 days of automated backups
}

The DB security group only accepts traffic from the app security group — not from any IP address, not from the internet:

ingress {
  from_port       = 3306
  to_port         = 3306
  protocol        = "tcp"
  security_groups = [var.app_security_group_id]
}

Module 4 — DNS

Route 53 alias record pointing app.skylumanex.click to the ALB, with a health check:

resource "aws_route53_record" "app" {
  zone_id = var.hosted_zone_id
  name    = var.domain_name
  type    = "A"

  alias {
    name                   = var.alb_dns_name
    zone_id                = var.alb_zone_id
    evaluate_target_health = true
  }
}

evaluate_target_health = true means Route 53 won't route traffic to the ALB if the ALB health checks are failing. Another layer of resilience.

Root Module — Wiring Everything Together

The environments/dev/main.tf calls all 4 modules and passes outputs between them:

module "networking" {
  source         = "../../modules/network"
  project_name   = var.project_name
  vpc_cidr_block = var.vpc_cidr_block
  single_nat_gateway = var.single_nat_gateway
  # ...
}

module "compute" {
  source                 = "../../modules/compute"
  vpc_id                 = module.networking.vpc_id
  public_subnet_ids      = module.networking.public_subnet_ids
  private_app_subnet_ids = module.networking.private_app_subnet_ids
  # ...
}

module "database" {
  source                = "../../modules/database"
  vpc_id                = module.networking.vpc_id
  private_db_subnet_ids = module.networking.private_db_subnet_ids
  app_security_group_id = module.compute.app_security_group_id
  # ...
}

module "dns" {
  source         = "../../modules/dns"
  alb_dns_name   = module.compute.alb_dns_name
  alb_zone_id    = module.compute.alb_zone_id
  hosted_zone_id = var.hosted_zone_id
}

Notice how module.networking.vpc_id flows into both compute and database. module.compute.app_security_group_id flows into database. Each module is independent but they communicate cleanly through their interfaces.

Deploying It

cd environments/dev
export TF_VAR_db_password="YourStrongPassword"
terraform init
terraform plan
terraform apply

Terraform provisions all 40 resources in the correct dependency order automatically.

The Proof

$ curl http://app.skylumanex.click
Hello from ip-10-0-11-230.eu-west-1.compute.internal

$ curl http://app.skylumanex.click
Hello from ip-10-0-12-181.eu-west-1.compute.internal

Traffic distributing across private subnets in eu-west-1a and eu-west-1b through the ALB, resolved via Route 53. The instances are never directly reachable from the internet.

Screenshots

Key Lessons

Modules enforce separation of concerns the networking module doesn't know about EC2, the compute module doesn't know about RDS. Each module has one job.
Outputs are the module API — what a module exposes in outputs.tf is its contract with the outside world. Design them carefully
The NAT Gateway is the hidden single point of failure most HA tutorials miss this. One shared NAT Gateway means one AZ failure kills all outbound private traffic.
deletion_protection = true on RDS is a guardrail, not an obstacle — it saved me from accidentally destroying a database during testing. Disable it explicitly before destroy, never by default.
Never put db_password in terraform.tfvars use TF_VAR_db_password environment variable. It never touches disk.

What's Next

Add a bastion host or SSM Session Manager for secure instance access
Enable VPC Flow Logs for network traffic visibility
Add WAF in front of the ALB
Build a staging/ environment by copying environments/dev/ the modules don't change

Resources

Terraform AWS Provider docs
AWS Well-Architected Framework — Reliability Pillar
GitHub: aws-full-ha-infra

Part of my AWS SAA-C03 prep as an AWS Community Builder 2026 (Serverless track). Follow along as I build toward certification

How I Built a Serverless Power Outage Tracker for Nigeria on AWS | Part 1

Emmanuel Ulu — Sun, 10 May 2026 10:58:54 +0000

The Problem Every Nigerian Knows

You're at home in Ikeja trying to work. Suddenly "NEPA" takes light.
You don't know if it's just your street, your whole estate, or the entire LGA. You check WhatsApp groups people are complaining but nobody has answers. You call EKEDC customer care nobody picks up. You just sit and wait, not knowing if light is coming back in 30 minutes or 3 days.
This is the daily reality for millions of Nigerians. And it's the problem I decided to solve with my AWS Community Builder $500 credit.

What I Built

A serverless, crowdsourced power outage tracking and alert system for Nigeria built entirely on AWS using SAM (Serverless Application Model).

Here's how it works:

Light goes off in Amuwo Odofin a resident opens the app and submits a report in 10 seconds
More residents from Festac, Satellite Town, and Apple Junction in Amuwo Odofin report the same outage
When 5 or more reports come in within 2 hours, the system confirms a real neighbourhood outage
Everyone subscribed to Amuwo Odofin alerts receives an email " Power Outage confirmed in Amuwo Odofin LGA"
Citizens can make informed decisions turn on the generator, buy fuel, reschedule work

No more guessing. No more unanswered EKEDC calls. Just real, community-driven outage awareness powered by AWS serverless technology.

The Architecture

The entire backend is serverless no EC2 instances, no servers to manage, no patching. AWS handles all the infrastructure.

Service	Role
API Gateway	Front door receives outage reports from citizens
Lambda (Ingest)	Validates and stores each report
Lambda (Query)	Fetches active outages for the dashboard
Lambda (Aggregator)	Counts reports per LGA, checks the 5-report threshold
Lambda (Alert)	Sends SNS email alerts to subscribers
DynamoDB	Stores all outage reports with 90-day auto-expiry
DynamoDB Streams	Triggers the Aggregator whenever a new report lands
SNS	Delivers email alerts to subscribed citizens

The flow looks like this:

The API

Method	Endpoint	Description
POST	`/reports`	Submit an outage report
GET	`/reports`	Fetch all active outages across Nigeria
GET	`/reports?lga=Ikeja`	Fetch outages for a specific LGA
POST	`/alert`	Manually trigger an alert

A citizen submitting a report sends a payload like this:

{
  "lga": "Ikeja",
  "state": "Lagos",
  "outage_type": "total",
  "notes": "No light since 6am, no EKEDC notice"
}

And gets back:

{
  "message": "Report submitted successfully",
  "report_id": "506a3212-b7de-4af8-9739-83d33425e807"
}

The DynamoDB Schema

Getting the DynamoDB schema right was one of the most important design decisions. DynamoDB is query-driven you design the table around your access patterns, not your data structure.
My primary key design:

PK: LGA#Ikeja                    # groups all Ikeja reports together
SK: REPORT#2026-05-09T22:49:48   # orders reports by time

This allows me to query all reports for a specific LGA in a specific time window with a single, fast query no table scans needed.
I also added two Global Secondary Indexes:

StateIndex query all outages by state (e.g. all Lagos outages)
StatusIndex query all active outages across Nigeria

What Surprised Me Most

I expected deploying to AWS to be complex and time-consuming. But with SAM, I ran sam build && sam deploy and watched CloudFormation spin up my entire infrastructure Lambda functions, API Gateway, DynamoDB table, IAM roles, DynamoDB Streams in under 3 minutes.

The first time I ran:

curl -X POST https://my-api.execute-api.eu-west-1.amazonaws.com/prod/reports \
  -H "Content-Type: application/json" \
  -d '{"lga": "Ikeja", "state": "Lagos", "outage_type": "total"}'

And got back:

{"message": "Report submitted successfully", "report_id": "506a3212..."}

I genuinely couldn't believe it was that fast. A real API, live on AWS, accepting real Nigerian outage reports.

The Hardest Part

The hardest part was understanding that every Lambda function needs to be defined in the SAM template.
As someone who comes from a DevOps background rather than software development, I initially thought of the template.yaml as just a config file. But it's actually the heart of the entire application it wires everything together. Every Lambda function, every API route, every permission, every environment variable.
Once that clicked, everything else made sense.

An Honest Limitation

I want to be transparent about what this system does and doesn't do.
Right now this is a citizen-to-citizen awareness system. When an outage is confirmed in Amuwo Odofin, subscribers in Amuwo Odofin get an email. That's valuable it tells you "it's not just you, the whole LGA is affected." You can make informed decisions.
But EKEDC doesn't receive these alerts. They're not connected to the system.
Phase 2 vision: DisCos like EKEDC, IKEDC, and AEDC subscribe to alerts for their coverage areas. They receive outage confirmations, dispatch repair teams, and update restoration ETAs which citizens then see on the dashboard.
That's the full solution. Phase 1 solves the awareness problem. Phase 2 solves the response problem.

What I'd Do Differently Next Time

As someone who is primarily a DevOps/Cloud engineer rather than a developer, my biggest lesson was this: understand what code is needed and how to write it before you start.
I jumped into building before I fully understood each Lambda function's role. Taking time upfront to map out exactly what each function needed to do its inputs, outputs, and interactions would have saved time and confusion.
Next time: design first, code second.

The Cost

The entire system runs on AWS pay-per-use pricing. At civic app scale:

Lambda: effectively free (1M requests/month free tier)
PI Gateway: ~$1 per million requests
DynamoDB: ~$0.25 per million reads
SNS: first 1,000 emails free

Total estimated cost: under $2/month. My $500 AWS CB credit will outlast this project by years.

Try It Yourself

The full source code is on GitHub:
👉 github.com/Emmanuel-DevOps-Portfolio/nigeria-outage-tracker

To deploy your own instance:

git clone https://github.com/Emmanuel-DevOps-Portfolio/nigeria-outage-tracker
cd nigeria-outage-tracker
sam build
sam deploy --guided

Bug Fix: Wiring the Aggregator to the Alert Lambda

After publishing this post I tested the full end-to-end flow and discovered
a missing link. The Aggregator Lambda was correctly counting reports and
detecting the threshold but was not automatically calling the Alert Lambda.

The fix was simple. Instead of returning a result and waiting for Step Functions
to orchestrate the next step, I added a direct Lambda invocation inside the
Aggregator when the threshold is hit:

lambda_client.invoke(
    FunctionName='outage-alert',
    InvocationType='Event',
    Payload=json.dumps({
        'lga': lga,
        'report_count': report_count,
        'alert_message': alert_message
    })
)

I also updated the Alert Lambda to handle both direct invocations and
API Gateway calls since the event payload structure is different for each.

After the fix, the full chain fired automatically and the alert email
landed in my inbox. 13 reports from Ohafia LGA in 2 hours confirmed! ⚡

What's Next

Part 2: Building a real-time outage dashboard for Nigeria with S3 and CloudFront
Part 3: Adding SMS alerts with SNS for Nigerian phone numbers
Part 4: Connecting DisCos, how EKEDC can receive and respond to outage alerts

Final Thoughts

Nigeria's power problem is complex. One serverless app won't fix epileptic supply overnight. But technology can make the experience less frustrating one reported outage, one confirmed alert, one informed citizen at a time.
If you're a Nigerian engineer, a civic tech enthusiast, or just someone who has ever sat in the dark waiting for "NEPA" I'd love your feedback on this project.
Let's build for Nigeria 🇳🇬.

Emmanuel Ulu is a DevOps/Cloud Engineer based in Lagos, Nigeria, and an AWS Community Builder 2026. Connect on LinkedIn or GitHub.

Event-Driven Architecture on AWS Explained Simply (With SAM)

Emmanuel Ulu — Thu, 19 Mar 2026 09:17:27 +0000

Ever heard the term "event-driven architecture" and felt like it was written in a different language? You're not alone.
In this post, I'll break it all down using plain English, real analogies, and working code you can run entirely on your laptop using AWS SAM, no AWS account charges required.
By the end, you'll understand how EventBridge, SNS, SQS, and Lambda work together, and you'll have built a fully connected event-driven pipeline locally.

Think of it Like a Shopping Mall

Before any code, let me paint a picture.
You own a shopping mall. A customer places an order. Several things need to happen:

The warehouse needs to pack the item
The accounts team needs to record the payment
The delivery team needs to schedule a shipment

The old way? You'd call each team one by one. Slow, tightly coupled, and fragile. If one team is busy, everything stalls.
The new way? You post a message on a notice board. Every team that needs to act sees it automatically and responds in their own time.
That notice board is event-driven architecture. And AWS gives us four services to build it.

Prerequisites

Before you start, make sure you have the following installed on your Mac/Linux machine:

Tool	Why You Need It
AWS CLI	To configure your AWS credentials
AWS SAM CLI	To build and run Lambda locally
Python 3.12	The runtime for our Lambda functions
Docker	To simulate the Lambda execution environment

Quick check — run these in your terminal to confirm everything is ready:

aws --version
sam --version
python3 --version
docker --version

No AWS deployment needed! We run everything locally using SAM and Docker, so no AWS account charges apply while following this guide.

Architecture

The diagram shows the live event flow. The phases build it in reverse, starting from Lambda and working back to EventBridge, so each layer is testable before adding the next.

The 4 Services, Explained Simply

1. EventBridge — The Smart Postman

EventBridge is your event bus, the central place where things get published when something happens in your app.
You define rules that tell it where to route events:

If the event comes from myapp.orders and the type is OrderPlaced, send it to SNS.

It reads the label on every package and delivers it to exactly the right destination.

// An EventBridge event looks like this
{
  "source": "myapp.orders",
  "detail-type": "OrderPlaced",
  "detail": {
    "orderId": "ORD-789",
    "product": "Tablet",
    "amount": 749.99,
    "customer": "Emma Ulu"
  }
}

2. SNS — The Group Chat

SNS (Simple Notification Service) is your megaphone. Once EventBridge sends an event to an SNS topic, SNS fans it out to all subscribers simultaneously.
You could have one subscriber or a hundred. They all get the message at the same time. This is the fan-out pattern.

One message in, many receivers out.

3. SQS — The Voicemail Box

SQS (Simple Queue Service) is a waiting line for messages. When SNS drops a message into an SQS queue, it sits there patiently until someone picks it up.
Why does this matter? Because if your Lambda function is busy or crashes, the message doesn't get lost. It just waits.

Like voicemail. If you're busy, the message waits. You won't miss it.

4. Lambda — The Worker

Lambda is your actual worker function, the code that does the real job. It picks up messages from SQS one by one and processes them: saving to a database, sending an email, charging a card, notifying another service. Anything you need.

The Full Flow

Customer places an order
        ↓
EventBridge checks its rules
        ↓
Rule matches → sends to SNS Topic
        ↓
SNS fans out → drops into SQS Queue
        ↓
Lambda picks up the message
        ↓
Order is processed ✅

Clean. Decoupled. Scalable.

What is AWS SAM?
SAM (Serverless Application Model) is the tool that lets you define and test all of this locally. Instead of clicking around in the AWS console, you write a template.yaml that describes your infrastructure as code.

SAM runs everything in Docker containers on your machine. No deployment needed while learning.
Think of it as a flight simulator. You learn to fly before touching the real plane.

Think of it as a flight simulator. You learn to fly before touching the real plane.

Building It — Phase by Phase

I built this project in 4 phases, each adding one layer to the architecture.

Phase 1 — Lambda Foundation

First, a simple Lambda function that can receive and log any event.

hello_world/app.py

import json
import logging

logger = logging.getLogger()
logger.setLevel(logging.INFO)

def lambda_handler(event, context):
    logger.info(f"Received event: {json.dumps(event)}")
    return {
        "statusCode": 200,
        "body": json.dumps({"message": "Hello from Event-Driven App!"})
    }

Test it locally:

sam build
sam local invoke HelloWorldFunction --event events/event.json --skip-pull-image

Phase 2 — Add SQS

Now we wire SQS to trigger Lambda whenever a message arrives in the queue.
template.yaml (key additions)

EventQueue:
  Type: AWS::SQS::Queue
  Properties:
    QueueName: event-queue

HelloWorldFunction:
  Type: AWS::Serverless::Function
  Properties:
    Events:
      SQSEvent:
        Type: SQS
        Properties:
          Queue: !GetAtt EventQueue.Arn
          BatchSize: 1

Updated app.py to handle SQS Records:

def lambda_handler(event, context):
    for record in event.get("Records", []):
        body = json.loads(record["body"])
        logger.info(f"Processing message: {body}")
    return {"statusCode": 200, "body": "SQS messages processed!"}

Test event (events/sqs_event.json):

{
  "Records": [{
    "body": "{\"orderId\": \"ORD-123\", \"product\": \"Laptop\", \"amount\": 999.99}",
    "eventSource": "aws:sqs"
  }]
}

sam local invoke HelloWorldFunction --event events/sqs_event.json --skip-pull-image

Output:
Processing message: {'orderId': 'ORD-123', 'product': 'Laptop', 'amount': 999.99}

✅ SQS → Lambda working!

Phase 3 — Add SNS Fan-out

Now SNS sits between your publisher and SQS, enabling fan-out to multiple queues if needed.
template.yaml additions:

EventTopic:
  Type: AWS::SNS::Topic

EventTopicSubscription:
  Type: AWS::SNS::Subscription
  Properties:
    TopicArn: !Ref EventTopic
    Protocol: sqs
    Endpoint: !GetAtt EventQueue.Arn
    RawMessageDelivery: true

When SNS delivers to SQS, it wraps the message in an SNS envelope. Update app.py to unwrap it:

parsed_body = json.loads(record["body"])

if parsed_body.get("Type") == "Notification":
    # Unwrap the SNS envelope
    sns_message = json.loads(parsed_body["Message"])
    logger.info(f"Subject: {parsed_body.get('Subject')}")
    logger.info(f"Message: {sns_message}")

✅ SNS → SQS → Lambda working!

Phase 4 — Add EventBridge

The final piece. EventBridge becomes the entry point for all events, routing them to SNS based on rules.
template.yamladditions:

EventBus:
  Type: AWS::Events::EventBus
  Properties:
    Name: event-driven-bus

OrderPlacedRule:
  Type: AWS::Events::Rule
  Properties:
    EventBusName: !Ref EventBus
    EventPattern:
      source:
        - "myapp.orders"
      detail-type:
        - "OrderPlaced"
    Targets:
      - Arn: !Ref EventTopic
        Id: SNSTarget

Update app.py to extract the EventBridge payload from inside the SNS envelope:

if parsed_body.get("Type") == "Notification":
    sns_message = json.loads(parsed_body["Message"])

    source = sns_message.get("source")
    detail_type = sns_message.get("detail-type")
    detail = sns_message.get("detail", {})

    logger.info(f"Source: {source}")
    logger.info(f"Event Type: {detail_type}")
    logger.info(f"Detail: {detail}")

    if detail_type == "OrderPlaced":
        process_order(detail)

def process_order(detail):
    logger.info(f"Order ID: {detail.get('orderId')}")
    logger.info(f"Product: {detail.get('product')}")
    logger.info(f"Amount: ${detail.get('amount')}")
    logger.info(f"Customer: {detail.get('customer')}")

Final test output:

EventBridge Source: myapp.orders
Event Type: OrderPlaced
Processing order: ORD-789
Product: Tablet
Amount: $749.99
Customer: Emma ulu

✅ Full pipeline working — 100% locally!

Why Not Just Call Lambda Directly?

Direct Call	Event-Driven
Tight coupling	Loosely coupled
One failure breaks others	Services fail independently
Hard to add new features	Just add a new SNS subscriber
Hard to scale	Each service scales independently

The event-driven approach lets your teams and services operate independently. A new feature? Just subscribe to the event. No need to touch existing code.

What I Learned (Phase Summary)

Phase	Service Added	Pattern Learned
1	Lambda	Local SAM testing, template.yaml basics
2	SQS	Message queues, Records array
3	SNS	Fan-out, envelope unwrapping
4	EventBridge	Event buses, content-based routing

What's Next?

Dead Letter Queue (DLQ) — a system-wide safety net for failed messages across SNS, SQS, EventBridge, and Lambda. CloudWatch logs the details, DLQ captures the message.
SQS Queue Policy — restrict who can write to your queue. Without this, anyone can inject fake messages resulting in fake orders or improper charges.
Multiple Lambda consumers — fan-out to different Lambdas for different jobs
EventBridge Pipes — direct SQS to Lambda without SNS
Schema Registry — validate event shapes and share reusable Lambda test events across your team
Deploy to AWS — sam deploy --guided when you're ready

Food for thought: Could EventBridge route directly to multiple Lambdas
without SNS? Yes, but SNS gives you dynamic fan-out without editing
rules every time.

Business Impact for Nigerian & African Startups

This architecture is not just a learning exercise. It maps directly to real problems Nigerian businesses face every day.

🛒 E-Commerce (Jumia, Konga-style platforms)
When a customer places an order, multiple things need to happen at once. Notify the warehouse, send an SMS confirmation, update inventory, record the transaction. With event-driven architecture, each service subscribes to the OrderPlaced event independently. Add a new step without touching existing code.

🏦 Fintech (Flutterwave, Paystack-style apps)
Every payment triggers downstream actions. Fraud checks, notifications, ledger updates. These cannot fail or get lost. SQS acts as the safety net. If any service is down, the message waits in the queue. Nothing is lost. Critical in financial systems.

🚚 Logistics & Delivery (Gokada, Kwik-style)
A delivery status change needs to notify the customer, update the driver dashboard, and log for analytics. All at once. One EventBridge rule fans it out to all three simultaneously.

📱 Telecoms & Utility Platforms
Airtime purchases, bill payments, data subscriptions. All event-driven by nature. High volume, needs to scale instantly. Lambda + SQS handles traffic spikes automatically with zero server management.

Challenge	How This Architecture Helps
High AWS bills	SAM + local testing = build before you pay
Unreliable internet	SQS queues messages so nothing is lost during downtime
Rapid scaling needs	Lambda scales to thousands of requests automatically
Small dev teams	Loosely coupled services = teams work independently
Tight budgets	Pay only when Lambda runs — zero idle cost

Final Thoughts

Event-driven architecture sounds intimidating, but at its core, it's just a smarter way for services to talk to each other. You post an event, the right services react, and nothing is tightly coupled.
AWS SAM makes it approachable by letting you build and test everything locally before spending a single dollar on the cloud.
If you followed along and got it working, well done! You've just built a real-world architecture pattern used by companies at scale.
Drop a comment if you have questions or want me to go deeper on any phase. Happy building!

Built with: AWS SAM · EventBridge · SNS · SQS · Lambda · Python 3.12

Building a Serverless TODO API with AWS SAM, Lambda, DynamoDB and LocalStack

Emmanuel Ulu — Fri, 13 Mar 2026 13:31:43 +0000

When I started learning serverless, my biggest fear wasn't the
technology, it was the AWS bill.

As a self-taught Cloud and DevOps Engineer still building my skills,
I needed a way to practice real AWS serverless architecture without
watching my account balance drop every time I deployed something.

The solution? LocalStack, a tool that runs AWS services locally
on your machine using Docker. Completely free. Completely real.

In this article I'll show you how I built a fully serverless
TODO REST API using AWS SAM, Lambda, API Gateway and DynamoDB,
all running locally for free using LocalStack.

Why Serverless?

No servers to manage, automatic scaling, and you pay only for
what you use. It is perfect for APIs with variable traffic.

And with LocalStack, you get all of that free during development.

What I Built

A fully serverless REST API that manages TODO items with
full CRUD operations.

POST /todos to create a new todo
GET /todos to retrieve all todos
GET /todos/{id} to retrieve a single todo
PUT /todos/{id} to update a todo
DELETE /todos/{id} to delete a todo

The entire stack is defined as infrastructure as code using
AWS SAM. No clicking around the console, no manual resource
creation. Just code, build and deploy.

The Architecture

to API Gateway, which triggers a Lambda function that reads and
writes to DynamoDB, with logs sent to CloudWatch." width="800" height="489">

The system is built on four AWS services that work together
as a single serverless application.

Amazon API Gateway receives incoming HTTP requests and routes
them to the appropriate Lambda function handler.

AWS Lambda runs the business logic. One function handles all
five API routes, reading the HTTP method and path from the
event object to determine what action to take.

Amazon DynamoDB stores the TODO items. Each item has a unique
ID generated at creation time, a title, description, completion
status and timestamp.

AWS SAM ties everything together as infrastructure as code.
The entire application, API Gateway, Lambda and DynamoDB, is
defined in a single template.yaml file and deployed with one command.

The request flow looks like this:

Client sends HTTP request
API Gateway receives and routes the request
Lambda function executes the business logic
DynamoDB stores or retrieves the data
Response returns to the client

Prerequisites

Before getting started, make sure you have the following
installed on your machine.

Docker to run LocalStack as a container.

Python 3.9 or higher as the runtime for the Lambda function.
For this project, I used Python 3.12, but any supported Python
version will work.

AWS SAM CLI to build and deploy the serverless application.

AWS CLI to configure credentials for LocalStack.

LocalStack to simulate AWS services locally.

You can verify your installations by running:

docker --version
python3 --version
sam --version
aws --version
localstack --version

Setting Up LocalStack

LocalStack runs as a Docker container and simulates AWS services
locally. This is what allowed me to build and test this entire
project without spending anything on AWS.

First, create a docker-compose.yml file in your project folder:

version: "3"
services:
  localstack:
    image: localstack/localstack:latest
    container_name: localstack
    environment:
      - AWS_DEFAULT_REGION=us-east-1
      - EDGE_PORT=4566
      - SERVICES=lambda,s3,dynamodb,sns,events,apigateway,cloudwatch,cloudformation,iam,sts
    ports:
      - "4566:4566"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"

Start LocalStack:

docker-compose up -d

Verify all services are running:

curl http://localhost:4566/_localstack/health

You should see apigateway, lambda, dynamodb, cloudformation
and iam all showing as available. That means LocalStack is
ready and we can start building.

Next, configure fake AWS credentials. LocalStack does not need
real credentials but the AWS CLI requires something to be set:

aws configure --profile localstack

Enter dummy for the Access Key ID and Secret Access Key,
us-east-1 for the region and json for the output format.

Project Structure

After initializing the project with AWS SAM, the folder
structure looks like this:

todo-api/
├── todo_handler/
│ ├── init.py
│ ├── app.py
│ └── requirements.txt
├── events/
│ └── event.json
├── tests/
├── .gitignore
├── README.md
├── docker-compose.yml
└── template.yaml

todo_handler/app.py contains all the Lambda function code.
This is where the business logic lives.

template.yaml is the SAM template that defines all AWS
resources including API Gateway, Lambda and DynamoDB as
infrastructure as code.

docker-compose.yml starts LocalStack as a Docker container,
simulating the AWS services we need locally.

requirements.txt lists the Python dependencies for the
Lambda function.

The SAM Template

The template.yaml file is the heart of the project. It defines
all AWS resources as infrastructure as code. No manual resource
creation in the console.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Serverless TODO API using Lambda, API Gateway and DynamoDB

Globals:
  Function:
    Timeout: 10
    Runtime: python3.12
    Environment:
      Variables:
        TABLE_NAME: !Ref TodoTable
        AWS_ENDPOINT_URL: http://localstack:4566

Resources:

  TodoTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: todos
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: id
          AttributeType: S
      KeySchema:
        - AttributeName: id
          KeyType: HASH

  TodoFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: todo_handler/
      Handler: app.lambda_handler
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref TodoTable
      Events:
        CreateTodo:
          Type: Api
          Properties:
            Path: /todos
            Method: post
        GetTodos:
          Type: Api
          Properties:
            Path: /todos
            Method: get
        GetTodo:
          Type: Api
          Properties:
            Path: /todos/{id}
            Method: get
        UpdateTodo:
          Type: Api
          Properties:
            Path: /todos/{id}
            Method: put
        DeleteTodo:
          Type: Api
          Properties:
            Path: /todos/{id}
            Method: delete

Let me break down the key parts.

The Globals section sets default values for all Lambda functions
in the template. The timeout is set to 10 seconds and the runtime
is Python 3.12. The environment variables pass the DynamoDB table
name and the LocalStack endpoint URL directly into the function.

The TodoTable resource defines the DynamoDB table. I used
PAY_PER_REQUEST billing mode which means there is no cost
when the table is not being used. The partition key is id,
a string that uniquely identifies each todo item.

The TodoFunction resource defines the Lambda function. The
DynamoDBCrudPolicy automatically grants the function permission
to read and write to the DynamoDB table without manually
configuring IAM policies.

The Events section maps each HTTP route to the Lambda function.
SAM automatically creates the API Gateway and wires everything
together from this single configuration.

The Lambda Function

All the business logic lives in a single file, todo_handler/app.py.
Let me walk through each part.

The Imports and DynamoDB Connection

import json
import boto3
import os
import uuid
from datetime import datetime


dynamodb = boto3.resource('dynamodb', endpoint_url=os.environ.get('AWS_ENDPOINT_URL'))
table = dynamodb.Table(os.environ.get('TABLE_NAME', 'todos'))

json handles parsing incoming request data and formatting responses.
boto3 is the AWS SDK for Python and is what connects the function to DynamoDB.
uuid generates a unique ID for each todo item at creation time.
datetime adds a timestamp when a todo is created.

The endpoint_url points to LocalStack during local development.
In production on real AWS, removing this line makes boto3
connect to the actual DynamoDB service automatically.

The lambda_handler

def lambda_handler(event, context):
    http_method = event['httpMethod']
    path_parameters = event.get('pathParameters') or {}

    try:
        if http_method == 'POST':
            return create_todo(event)
        elif http_method == 'GET' and 'id' not in path_parameters:
            return get_todos()
        elif http_method == 'GET' and 'id' in path_parameters:
            return get_todo(event)
        elif http_method == 'PUT':
            return update_todo(event)
        elif http_method == 'DELETE':
            return delete_todo(event)
        else:
            return response(404, {'message': 'Route not found'})
    except Exception as e:
        return response(500, {'message': str(e)})

This is the entry point AWS calls every time an API request
comes in. Think of it as a traffic controller. It reads the
HTTP method and path parameters from the event object and
routes the request to the correct function.

The try/except block catches any unexpected errors and returns
a clean 500 response instead of crashing silently.

Create a Todo

def create_todo(event):
    body = json.loads(event['body'])
    if 'title' not in body:
        return response(400, {'message': 'title is required'})
    todo = {
        'id': str(uuid.uuid4()),
        'title': body['title'],
        'description': body.get('description', ''),
        'completed': False,
        'created_at': datetime.utcnow().isoformat()
    }
    table.put_item(Item=todo)
    return response(201, todo)

This function parses the request body, validates that a title
was provided, builds the todo item with a unique ID and
timestamp, saves it to DynamoDB and returns the created item
with a 201 status code.

Get All Todos

def get_todos():
    result = table.scan()
    return response(200, result['Items'])

This function scans the entire DynamoDB table and returns
all todo items. Simple and effective for a small dataset.

Get a Single Todo

def get_todo(event):
    todo_id = event['pathParameters']['id']
    result = table.get_item(Key={'id': todo_id})
    if 'Item' not in result:
        return response(404, {'message': 'Todo not found'})
    return response(200, result['Item'])

This function extracts the ID from the path parameters,
queries DynamoDB for that specific item and returns a 404
if it does not exist.

Update a Todo

def update_todo(event):
    todo_id = event['pathParameters']['id']
    body = json.loads(event['body'])
    result = table.get_item(Key={'id': todo_id})
    if 'Item' not in result:
        return response(404, {'message': 'Todo not found'})
    table.update_item(
        Key={'id': todo_id},
        UpdateExpression='SET title = :title, description = :desc, completed = :completed',
        ExpressionAttributeValues={
            ':title': body.get('title', result['Item']['title']),
            ':desc': body.get('description', result['Item']['description']),
            ':completed': body.get('completed', result['Item']['completed'])
        }
    )
    return response(200, {'message': 'Todo updated successfully'})

This function checks the item exists first, then updates only
the fields provided in the request body. If a field is not
provided, it keeps the existing value.

Delete a Todo

def delete_todo(event):
    todo_id = event['pathParameters']['id']
    result = table.get_item(Key={'id': todo_id})
    if 'Item' not in result:
        return response(404, {'message': 'Todo not found'})
    table.delete_item(Key={'id': todo_id})
    return response(200, {'message': 'Todo deleted successfully'})

This function checks the item exists before attempting to
delete it and returns a clear success message when done.

The Response Helper

def response(status_code, body):
    return {
        'statusCode': status_code,
        'headers': {
            'Content-Type': 'application/json',
            'Access-Control-Allow-Origin': '*'
        },
        'body': json.dumps(body)
    }

Every function uses this helper to return a properly formatted
HTTP response. Without this structure API Gateway would not
know how to send the result back to the client. The
Access-Control-Allow-Origin header allows the API to be
called from a browser.

What Went Wrong and How I Fixed It

No project goes perfectly the first time. Here are the two
bugs I hit during development and how I resolved them.

Bug 1: Route Not Found

After deploying and testing the CREATE endpoint I got this:

{"message": "Route not found"}

The issue was a trailing slash in my curl command. I was
sending the request to:

POST /todos/

Instead of:

POST /todos

A single extra slash was causing the routing to fail. Removing
it fixed the issue immediately. A small but important lesson
about how API Gateway handles URL matching.

Bug 2: Delete Was Not Deleting

After testing the DELETE endpoint I got this response:

{"message": "Todo deleted successfully"}

But when I ran GET /todos the item was still there.

The issue was in the original lambda_handler routing logic.
The condition for matching GET requests with a path parameter
was too broad and was also matching DELETE requests incorrectly,
causing the wrong function to be called.

I fixed it by simplifying the routing logic in lambda_handler
to check the HTTP method first and path parameters second:

if http_method == 'POST':
    return create_todo(event)
elif http_method == 'GET' and 'id' not in path_parameters:
    return get_todos()
elif http_method == 'GET' and 'id' in path_parameters:
    return get_todo(event)
elif http_method == 'PUT':
    return update_todo(event)
elif http_method == 'DELETE':
    return delete_todo(event)

After redeploying with sam build and samlocal deploy the
delete worked perfectly and GET /todos returned an empty
list confirming the item was gone.

These two bugs taught me more about API Gateway routing
and Lambda event handling than any tutorial could.

Testing the API

I tested all five endpoints using curl. Here is the full
test sequence.

Create a Todo

curl -X POST https://<your-api-id>.execute-api.localhost.localstack.cloud:4566/Prod/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn AWS Lambda", "description": "Build serverless APIs"}'

Response:

{
"id": "3d98c259-3239-4c9f-bac7-df23332c30bb",
"title": "Learn AWS Lambda",
"description": "Build serverless APIs",
"completed": false,
"created_at": "2026-03-13T09:55:34.339562"
}

Get All Todos

curl https://<your-api-id>.execute-api.localhost.localstack.cloud:4566/Prod/todos

Response:

[
{
"id": "3d98c259-3239-4c9f-bac7-df23332c30bb",
"title": "Learn AWS Lambda",
"description": "Build serverless APIs",
"completed": false,
"created_at": "2026-03-13T09:55:34.339562"
}
]

Get a Single Todo

curl https://<your-api-id>.execute-api.localhost.localstack.cloud:4566/Prod/todos/3d98c259-3239-4c9f-bac7-df23332c30bb

Response:

{
"id": "3d98c259-3239-4c9f-bac7-df23332c30bb",
"title": "Learn AWS Lambda",
"description": "Build serverless APIs",
"completed": false,
"created_at": "2026-03-13T09:55:34.339562"
}

Update a Todo

curl -X PUT https://<your-api-id>.execute-api.localhost.localstack.cloud:4566/Prod/todos/3d98c259-3239-4c9f-bac7-df23332c30bb \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn AWS Lambda", "description": "Build serverless APIs", "completed": true}'

Response:

{"message": "Todo updated successfully"}

Delete a Todo

curl -X DELETE https://<your-api-id>.execute-api.localhost.localstack.cloud:4566/Prod/todos/3d98c259-3239-4c9f-bac7-df23332c30bb

Response:

{"message": "Todo deleted successfully"}

Confirm Deletion

curl https://<your-api-id>.execute-api.localhost.localstack.cloud:4566/Prod/todos

Response:

[]

All five endpoints working correctly. The empty array at
the end confirms the delete function is working as expected.

Possible Improvements

This project covers the core serverless API pattern but there
is a lot of room to extend it further.

Add authentication with Amazon Cognito to secure the API
endpoints and restrict access to authenticated users only.

Add input validation to check the request body more thoroughly
before saving to DynamoDB. For example validating that the
title is not empty or too long.

Add pagination to the GET /todos endpoint. As the number of
items grows, scanning the entire table becomes inefficient.
DynamoDB supports pagination natively.

Store an updated_at timestamp when a todo is updated so you
can track when items were last modified.

Add a CI/CD pipeline using GitHub Actions to automatically
build and deploy the application whenever code is pushed
to the main branch.

Deploy to real AWS once the application is stable and tested
locally. With SAM the same template.yaml works on both
LocalStack and real AWS with no changes needed.

Add unit tests for each Lambda function to catch bugs
before deployment.

Conclusion

Building this project taught me more than just how to write
Lambda functions. It taught me how serverless components
connect together as a complete system.

API Gateway handles routing. Lambda handles logic. DynamoDB
handles storage. SAM ties everything together as infrastructure
as code. Each service has a clear responsibility and they work
together seamlessly.

The biggest lesson was around local development. LocalStack
completely removed the cost barrier that was slowing down my
learning. I could build, break, fix and redeploy as many times
as I needed without worrying about AWS bills. That freedom
accelerated my learning significantly.

If you are learning serverless and struggling with AWS costs,
I highly recommend setting up LocalStack. The workflow of
developing locally and deploying to real AWS when ready is
a genuinely productive way to build.

The full source code for this project is available on GitHub:
https://github.com/Emmanuel-DevOps-Portfolio/serverless-todo-api

Business Impact for Local Startups

This architecture is not just a learning project. It solves
real business problems that many Nigerian startups face every day.

Cost Efficiency

Most Nigerian startups operate on tight budgets. Traditional
server-based architectures require paying for servers 24 hours
a day even when no one is using the application.

With serverless, you only pay when the API is actually called.
For a startup with low or unpredictable traffic, this can reduce
infrastructure costs by up to 80 percent compared to running
a dedicated server.

No DevOps Team Required

Small startups in Nigeria often cannot afford a dedicated
DevOps team. Serverless removes the need to manage, patch
and monitor servers. The infrastructure manages itself.

A small team of developers can build, deploy and maintain
a production API without any server administration knowledge.

Scales With Your Growth

Nigerian startups often experience sudden traffic spikes,
during product launches, media coverage or viral moments
on social media.

A serverless API scales automatically to handle thousands
of requests per second without any manual intervention.
You do not need to provision more servers in advance or
worry about your application going down under load.

Fast Time to Market

In a competitive startup environment, speed matters.
With AWS SAM, the entire infrastructure is defined as
code and can be deployed in minutes. A new developer
joining the team can have the full environment running
locally using LocalStack without needing access to
production AWS credentials.

Real World Use Cases

This exact architecture can power many products relevant
to the Nigerian market:

Logistics and delivery tracking APIs for last mile
delivery startups.

Fintech payment notification systems for digital
payment platforms.

Agritech farm monitoring APIs for agricultural
technology companies.

E-commerce order management systems for online
retail businesses.

Healthcare appointment booking APIs for digital
health platforms.

LocalStack for African Developers

The cost barrier of cloud learning is real across Africa.
LocalStack makes it possible to learn, build and test
production-grade AWS architectures completely free.

This levels the playing field for developers in Lagos,
Abuja, Accra, Nairobi and across the continent who are
building world class products on limited budgets.

I am Emmanuel Ulu, a Cloud and DevOps Engineer and AWS
Community Builder in the Serverless category. I share
hands-on projects as I explore serverless and event-driven
architectures on AWS.

If you found this article helpful, follow me here on dev.to
for more serverless content. And if you build something
using this project, I would love to hear about it in
the comments.

Serverless

Emmanuel Ulu — Tue, 10 Mar 2026 18:58:45 +0000

Building a Serverless Website Uptime Monitor with AWS Lambda, EventBridge, and SNS - DEV Community

Introduction In modern cloud environments, ensuring that applications and websites remain...

dev.to

Building a Serverless Website Uptime Monitor with AWS Lambda, EventBridge, and SNS

Emmanuel Ulu — Tue, 10 Mar 2026 14:52:48 +0000

Introduction

In modern cloud environments, ensuring that applications and websites remain available is critical. Even a few minutes of downtime can affect users, revenue, and system reliability.

In this project, I built a simple serverless uptime monitoring system using AWS services. The system periodically checks whether a website is available and sends an alert if it becomes unreachable.

This project demonstrates how event-driven architectures can automate monitoring tasks without managing servers.

The Business Problem

Many small teams and startups rely on web applications but may not have a full monitoring stack.

Some common problems include:

Websites going down without immediate notice
Lack of automated monitoring
Delayed response to service failures
Expensive third-party monitoring tools

The goal of this project is to create a lightweight and cost-efficient monitoring system that automatically checks website availability and sends alerts when problems occur.

The Solution

Using a serverless architecture, we can automate uptime monitoring with minimal infrastructure.

Figure: Serverless architecture for automated website uptime monitoring using AWS EventBridge, Lambda, SNS, and CloudWatch. Alerts are delivered via Slack or email when the monitored service becomes unavailable.

The system works as follows:

A scheduler triggers a function at regular intervals.
The function checks the health of a target website
If the website is down, an alert notification is sent.
Logs and metrics are stored for monitoring and troubleshooting.

Architecture

The architecture uses the following AWS services:

Amazon EventBridge – schedules the monitoring job
AWS Lambda – runs the health check logic
Amazon Simple Notification Service – sends alert notifications
Amazon CloudWatch – collects logs and metrics

Workflow:

EventBridge (schedule)
        ↓
Lambda Function
        ↓
Website Health Check
        ↓
SNS Notification
        ↓
Email / Slack

Step 1: Create an SNS Topic

First, create a notification channel for alerts.

Open the AWS Console.
Navigate to SNS.
Create a new Topic.
Select Standard topic.
Add a name such as:

website-health-alerts

Next, create a subscription:

Protocol: Email
Endpoint: your email address

Confirm the subscription from your email.

Step 2: Create the Lambda Function

Next, create the function responsible for checking website health.

Navigate to Lambda
Click Create Function
Choose Author from scratch

Configuration:

Function name: website-health-check
Runtime: Python

Step 3: Add Health Check Code

Example Python code for the Lambda function:

import requests
import boto3
import os

sns = boto3.client('sns')

TOPIC_ARN = os.environ['SNS_TOPIC']

def lambda_handler(event, context):

    url = "https://google.com"

    try:
        response = requests.get(url, timeout=5)

        if response.status_code != 200:
            sns.publish(
                TopicArn=TOPIC_ARN,
                Message=f"ALERT: {url} is DOWN",
                Subject="Website Health Alert"
            )

    except Exception as e:
        sns.publish(
            TopicArn=TOPIC_ARN,
            Message=f"ERROR accessing {url}: {str(e)}",
            Subject="Website Health Alert"
        )

This code checks whether the website responds successfully.

If the site is unavailable, it sends a notification to SNS.

Step 4: Configure EventBridge Scheduler

Now we automate the monitoring.

Navigate to EventBridge
Create a Rule
Choose Schedule

Example schedule:

rate(5 minutes)

Set the target to the Lambda function.

Now AWS will automatically run the health check every five minutes.

Step 5: Monitoring with CloudWatch

All Lambda executions generate logs automatically in CloudWatch.

CloudWatch allows you to monitor:

execution logs
errors
function duration
invocation metrics

This helps with troubleshooting if the health check fails.

Testing the System

To test the monitoring system:

Change the URL in the Lambda function to an invalid website.
Wait for the scheduled execution.
An email alert should be triggered.

Example alert message:

ALERT: https://example.com is DOWN

Benefits of This Approach

This serverless solution provides several advantages:

No server management
Automatic scaling
Low operational cost
Event-driven automation
Simple monitoring setup

Because the system only runs when triggered, it is cost efficient compared to always-on monitoring services.

Possible Improvements

This project can be extended in several ways:

Store monitoring results in DynamoDB
Track response latency
Monitor multiple websites
Send Slack alerts
Build a CloudWatch dashboard
Add retry logic

Conclusion

This project demonstrates how serverless services can be used to build lightweight automation tools.

By combining EventBridge, Lambda, SNS, and CloudWatch, we created a simple monitoring system that automatically checks website availability and sends alerts when issues occur.

Serverless architectures like this are powerful for operational automation because they eliminate the need to manage infrastructure while still providing reliable and scalable solutions.

I recently joined the AWS Community Builders program in the Serverless category, and I’ll be sharing more hands-on projects as I explore event-driven architectures and serverless systems.

Starting My Journey as an AWS Community Builder (Serverless)

Emmanuel Ulu — Thu, 05 Mar 2026 10:08:26 +0000

I’m really excited to share that I was recently accepted into the AWS Community Builders program in the Serverless category.

I work as a Cloud and DevOps engineer and spend most of my time working with Kubernetes, automation, and cloud infrastructure. Over the past few months, I’ve been building hands on projects around Kubernetes clusters, CI/CD pipelines, and modern cloud systems.

Being accepted into the AWS Community Builders program means a lot to me. It’s both an opportunity and motivation to keep learning and sharing with the community.

Most of my experience so far has been around Kubernetes and DevOps infrastructure, but I’m now diving deeper into serverless and event driven architectures using AWS services like Lambda and EventBridge.

Through this blog, I’ll be sharing what I learn, the projects I build, and lessons from working with cloud infrastructure.