My work as a software engineer and technical architect is centered around building and delivering software doing things like designing systems, collaborating with dev teams and helping move solutions from idea to implementation to operation. It's a highly technical role, but not necessarily at the frontier or state of the art AI

Still, over the past months I've been paying attention to what's happening in the AI space. AI agents have caught my attention and I've been studying and experimenting the topic on my own

To me, software engineering has always been about solving problems with tech, which means understanding the what, why and how. While learning about AI agents, I kept running into one question: what actually is an agent and how is it different than an AI workflow? In this blog post I go over this distinction in a practical way

What is an AI workflow?

A workflow can be defined as a series of steps needed to complete a task. Adding "AI" to it generally just means an LLM is involved in at least one of those steps. A good and easy to understand example would be a support system ticket where tickets can be created and an AI workflow can summarize the ticket, check relevant documentation and draft a response.

High-level use case diagram for "support ticket" AI workflow sample. Own creation

The important part here is that the sequence is fixed. The model adds intelligence/reasoning inside the steps, but it's not free to decide on the whole process

What is an AI Agent?

An AI agent goes one step further than a workflow. Instead of following a fixed sequence of steps, it is given a goal and some ability (tools) to decide what actions to take.

In our previous example of the support ticket workflow, with an AI agent, the agent gets into a feedback loop where the LLM can use tools, search docs or ask user for more info. Each internal loop step inside the agent also checks if current "reasoning" is enough to resolve or if need to continue with the agentic loop

High-level use case diagram for "support ticket" using an AI agent. Own creation

The important difference here is that the agent can choose actions dynamically, like using a tool, inspecting results, and loop to refine the output and complete the task. That flexibility is what makes the agents powerful and interesting, but also significantly more complex than workflows

Why people confuse them?

It's easy to confuse workflows and agents because both look similar on the surface. Both use LLMs, tools, APIs and so on.

A workflow may already look smart enough to feel like an agent. Also, most agents are not fully autonomous either as they require a human input to start.

So the distinction is not really about whether AI is involved, It is more about how much freedom an AI system has to decide next step

• Workflows: Has a predefined path. The system is mostly developer-controlled

• Agent: Has more of a dynamic path towards a goal. The system is More system-controlled

Conclusion

In software engineering, we usually try to use the right tool for the right job. I think the same concept applies well here. Not every AI-powered system needs to be an agent.

An AI workflow is a good choice when the path is known in advance and you want something easier to understand, test and control.

An AI Agent makes more sense when the system needs freedom to decide what to do in order to reach a goal or objective

[Summary Generated with AI] This article explores AWS Lambda Managed Instances as an alternative compute option for steady-state, high-volume serverless workloads. Using a telemetry collection pipeline as the example, it proposes an architecture where API Gateway directly enqueues events into SQS, and a Managed Instances Lambda processes messages in batches. The post walks through a small CDK-based PoC and highlights practical gotchas—VPC networking, memory-to-vCPU ratios, capacity provider association behavior, and NAT vs VPC endpoints—so you can evaluate Managed Instances with realistic constraints. It closes with a simple recommendation: keep traditional Lambda as the default for bursty/unpredictable workloads, and consider Managed Instances when your workers are effectively “always on” and you can size capacity around a steady baseline.

Introduction

When architecting a serverless solution, one common question/concern is “Lambda is very costly at scale”. And that can be true depending on the traffic and flow of the service, and what the function is doing

One thing I love about lambda is that it gives you the ability to move fast and keep operational overhead at a minimum. A simple execution model, clean and easy integrations with other aws services and a powerful scaling model

But there are also tradeoffs that become evident when traffic grows or becomes "steady state". Resulting in a lambda function that is "always on"

Recently, AWS announced "Lambda Managed Instances" (Announcement Post). It caught my attention because it seems to fill the gap: "steady-state" workflows with lambda's dev experience

It's not a replacement for traditional lambda, I see it more like "stay inside lambda flow with a capacity style compute and scaling model", which is great for high volume and steady traffic

In this post I analyze a concrete use case where I think lambda managed instances fits as a compute choice. I also go over a small POC where I explore this new offering using CDK to deploy it

Use Case

For the use case, let's dive into a "collect telemetry" scenario, where multiple client devices using one or different apps send telemetry data that can result in a lot of volume. Things like clicks, screen views, custom events, metrics and so on may be collected and sent over to a "Telemetry Ingestion" service which in turn can send the data in batches to a "Telemetry Processing" service

A simplified diagram for the use case is shown as follows:

Diagram for "Telemetry Data" collection and processing use case. Own Creation

Since a single user that's navigating an app in a device can generate a lot of events, if we think at scale, the data can be quite a lot. A good candidate for using Lambda Managed Instance for this scenario could be the "Telemetry Processing":

• Would be an "always-on" service. Even if usage varies during a day, there's usually steady traffic 24/7

• Spikes in traffic like marketing campaigns can be handled gracefully by lambda's capacity provider

• Ingestion needs to stay thin. So an approach that accepts telemetry data fast works here. SQS can help in batching the data so that the lambda managed instance can process multiple telemetry data events at a time

The combination of "steady traffic" + "high volume" + "traffic spikes" makes this a good scenario to try out lambda managed instances

Architecture

So as described in the previous section, for the "Telemetry Ingestion" service a thin layer would be needed in order to accept the telemetry data and batch it. For that, using API Gateway as entry point and a SQS queue to help batch the messages works like a charm. Using a direct integration between API Gateway and SQS it's possible to avoid another compute in between those two

For the "Telemetry Processing", since we're using an SQS queue for the ingestion, the batching is controlled nicely. A DLQ can be introduced to handle failed messages that the lambda can't process, so that those messages are not automatically lost. For the compute, it's possible to use lambda with the "managed instance" variant, as it would fit nicely in the use case and would be more cost effective at scale because the queue is frequently non-empty

Architecture Component View for the "Collect Telemetry" use case. Own Creation

Let's now see how to implement a sample POC of this architecture, focusing on the "lambda managed instance" part, which is the telemetry processing piece

POC

Implementation using a IaC framework like AWS CDK is straight forward. The stack is composed of one HTTP endpoint for the API Gateway, one SQS queue + DLQ and one lambda function running on Managed Instances (ec2) with a capacity provider defined

Some things are different when defining traditional Lambda from Managed Instances. Some gotchas I learnt during the implementation:

• Since the EC2 instances that are spun up will be inside vpc in private subnets. So all the networking configuration needs to be defined in CDK as well in order for the lambda to work properly

• The memory-to-CPU ratio must match your function memory. When attaching a function to a capacity provider, a supported memory-to-CPU ratio must be chosen, which as of the writing of this article it's 2GB, 4GB or 8GB per vCPU. If the function's memory is smaller, deployment will fail

• Attaching a function to a capacity provider is one-way. As of the writing of the article, it's not possible to "go back to traditional lambda" by removing the association. To go back, a new function needs to be created

• For this POC, adding a NAT gateway works. However, because of pricing and cost, in a real scenario it might be better to consider VPC endpoints for SQS or cloudwatch instead.

For the complete code implementation of the POC, please see the following GitHub Repo

Some screenshots of the deployed stack:

Lambda with managed instance configuration. Own creation

EC2 instances managed by lambda and capacity provider. Own creation

Lambda managed instance Capacity Provider defined. Own creation

Conclusion

I think Lambda Managed Instances won't change much how people are using lambda. Traditional lambda is still the best default for unpredictable workload. But for steady-state systems where functions end up "always-on", Lambda managed instances are a great option to keep the lambda ecosystem while moving to a capacity-oriented model

The telemetry use case it's a good example of when lambda managed instances fits in nicely. using API gateway + SQS queue as a direct integration, we keep the telemetry ingestion simple and avoid unnecessary compute. The queue provides buffering and batching which a Lambda using "managed instances" can consume from.

Some gotchas I found when developing the POC for this use case are things like VPC configuration, capacity provider and lambda configuration and the fact that a function configured with a capacity provider can't "remove the capacity provider association" to go back to traditional lambda

If considering to implement lambda managed instances in a real production scenario, I would measure traffic to be able to take the decision based on that. some measures could be queue depth/arrival rate, processing throughput and cost under traditional lambda (optionally considering provisioned concurrency). Then do a comparision exercise using Managed Instances with a configuration sized for a steady traffic.

[Summary Generated with AI] This article addresses the issue of data inconsistency in distributed, event-driven systems due to dual writes, where a database update and event publication might not succeed simultaneously. It presents a fictional car workshop scenario to highlight this problem and introduces the Outbox Pattern as a solution. By using AWS services like DynamoDB Transactions and EventBridge Pipes, the Outbox Pattern ensures reliable messaging and data consistency. The system's resilience and maintainability are improved by atomically handling database and outbox writes and reliably delivering events using serverless components. For complete code samples, refer to the linked GitHub repository.

Introduction

When dealing with distributed systems, failures may happen in the communication gaps between systems. One common issue in event-driven systems is the “dual write”: update a database and then publish an event. A disruption (timeouts, retries, crashes, etc) in a part of the system will make operation results diverge, resulting in incorrect state and issues with data consistency and integrity

This post showcases a fictional use case for a Car Workshop which may run into this problem by using a naive approach. It shows how to introduce more confidence in the system by implementing the “Outbox Pattern” architecture pattern and shows how to implement such pattern using AWS Services such as DynamoDb Transactions and EventBridge pipes

For full code implementation, please Check the GitHub Repository

Use Case

As a fictional example, a car workshop does repair orders for cars that come to the building. Once a repair is finished, the system must update a database with the status as COMPLETED and trigger an asynchronous process to send an Invoice to the customer and a notification to another section of the building

Component diagram of the car workshop use case “Repair Completed”. Own Creation

While the above architecture for the use case may work most times, we can see the system relies on a fragile two-part writes: One to DynamoDb to update the repair status, and the other write to publish the event to EventBridge bus. The following is an example code snippet inside the Lambda Function that showcases this:

await ddb.update({ pk: `REPAIR#${id}`, sk: 'META', set: { status: 'COMPLETED' }});
await eventBridge.putEvents({ detail: { eventType: 'RepairCompleted', repairId: id }});
return 200;

Some potential problems from this code:

• Db updates successfully but the event bridge “putEvents” times out.

  • This results in database with the Repair as completed but no event was sent for invoicing and notification

• DB updates successfully and event bridge “putEvents” also works, but Lambda crashes before responding.

  • This will trigger a lambda retry with the same input, which will send a duplicated event for the invoicing and notification

Outbox Pattern

In System Design, Reliable messaging is an essential part. Specially in distributed systems where multiple services are connecting and integrating with each other in a choreography-style.

The Outbox Pattern aims to ensure a reliable messaging between different services and components. It is specially important in scenarios where data consistency and data integrity are critical. It does so by defining a table or entity as an “Outbox”, which will be separated from the main data entity. It temporarily stores messaged that need to be sent to other systems.

By leveraging databases ACID Transactions, we can join together two or more writes in a single atomic operation, ensuring that the data is consistent and having the “Outbox” entity be in charge of the delivery of the events

By using this pattern, we are effectively updating the needed business entities and setting the message to be sent in one go. A separate process can then send the messages to the message broker.

Outbox Pattern Diagram. Taken from https://microservices.io/patterns/data/transactional-outbox.html

Serverless Outbox Pattern

By leveraging Serverless services in AWS, we can propose a better architecture that gives more reliability on event delivery and data integrity. Using DynamoDb Transactions, DynamoDb Streams and EventBridge Pipes we can give more confidence to the system:

Component diagram of the car workshop use case “Repair Completed” implementing the “Outbox Pattern”. Own Creation

As we’re now using the “Outbox” pattern, the lambda updates the status AND writes a new entity called “Outbox” in one go, using a DynamoDb Transaction. This ensures that both writes to the database are encapsulated atomically, resulting in either both writes succeeding or none. The following is a code snippet of a sample “DynamoDb Transaction” that implements the Outbox Pattern:

    const params = {
      TransactItems: [
        {
          Update: {
            TableName: table,
            Key: {
              pk: marshall(`REPAIR#${repairId}`),
              sk: marshall('META'),
            },
            ConditionExpression: 'attribute_not_exists(#status) OR #status <> :done',
            UpdateExpression: 'SET #status = :done, completeAt = :now',
            ExpressionAttributeNames: { '#status': 'status' },
            ExpressionAttributeValues: marshall({ ':done': 'COMPLETED', ':now': now }),
          }
        },
        {
          Put: {
            TableName: table,
            Item: marshall({
              pk: `OUTBOX#${eventId}`,
              sk: `REPAIR#${repairId}`,
              entityType: 'OUTBOX',
              eventType: 'RepairCompleted',
              occurredAt: now,
              eventId,
              repairId,
            }),
            ConditionExpression: 'attribute_not_exists(pk)'
          }
        }
      ]
    };

    const command = new DynamoDb.TransactWriteItemsCommand(params);
    const response = await dynamoDbClient.send(command);

By setting DynamoDb Streams, we can setup a stream on the dynamodb table that triggers on specific database writes. Using EventBridge Pipes, we can connect the DynamoDb events with an EventBridge Bus. EventBridge pipes allows us to set up filtering, which we can use to filter by “entity type” being “OUTBOX”

EventBridge Pipe showing the event filtering by “OUTBOX” events. Own Creation

The event delivered to the EventBridge Bus can have the following structure, which is filtered and mapped using EventBridge Pipes:

{
  "detail-type": "OutboxEvent",
  "source": "carworkshop.outbox",
  "detail": {
    "eventId": "c8f2d7e6-1e2f-4b7b-8c41-0b2a2f1c9f92",
    "eventType": "RepairCompleted",
    "repairId": "R-123",
    "occurredAt": "2025-11-12T14:00:00Z",
    "source": "fleetfix.outbox"
  }
}

For a complete code sample implementation, please Check the GitHub Repository

Conclusion

One of the challenges when dealing with distributed systems is ensuring data consistency and integrity across asynchronous processes. One common issue is the “dual-write” approach where two separate writes to two separate systems may result in data discrepancies, events not sent or duplicated events

By implementing the “Outbox Pattern”, this article shows how to handle event-delivery that is consistent with the business data updates. By leveraging DynamoDb Transactions and EventBridge pipes, the pattern was implemented for a fictional “car workshop” use case where a repair is done and asynchronous process needs to be sent to handle invoicing and notifications

Incorporating the “Outbox pattern” in our architecture allows for systems that more resilient, handle failures gracefully, which ensures a more predictable and maintainable system overall

References

• Full code sample implementation in GitHub

• Outbox Pattern for Reliable Messaging - System Design

• Pattern: Transactional outbox

• Amazon DynamoDB Transactions: How it works

• Understanding EventBridge Pipes

• EventBridge Pipes in Practice

El pasado 28 de Junio de 2025 fue el AWS Community Day Colombia. Aceptaron mi charla “Lambdaless: Serverless sin Lambda” con la que pretendo dar un par de tips sobre arquitecturas serverless en aws sin lambdas

El evento: energía, comunidad y muy buena organización

Aunque había participado de varios AWS Summits en años pasados, este fue mi primer AWS Community day! No estaba muy seguro si sería diferente o similar a los summits, dado que es organizado por las comunidades y voluntarios.

El evento estuvo muy top: La logística fue fluida, los speakers e invitados estuvieron geniales y dieron swag y regalos muy geniales!

La charla: patrones “Lambdaless” para aplicar en AWS

En mi charla tuve sala llena, un público muy participativo y haciendo preguntas muy interesantes. Mostré tres patrones de arquitectura:

• API Gateway —> DynamoDb: CRUD rápido y barato con todas las de la ley: Autenticación, Observabilidad, Validaciones, Mappeo, entre otras

• Step Functions + Integraciones nativas: Orquestación de diferentes servicios en AWS para evitar el anti-patrón de “Lambdalith” o “monolitos lambda”

• AppSync API: Creación de GraphQL APIs que permiten crear pipeline functions reusables y con conexión directa a servicios como dynamodb, step functions, entre otros

Comparé costos, tiempos/latencia y carga operativa. Al final dí unos tips para decidir “Lambda o Lambdaless”

Lo que más resonó

Creo que el mayor impacto que tuvo la charla sobre los participantes fue que vieran las diferentes decisiones o “tradeoffs” que se deben considerar a la hora de proponer una arquitectura. En especial en AWS donde hay tantas opciones diferentes y con tantas implicaciones de costos, mantenibilidad, escalabilidad, latencia, entre otros

Otro tema del que sentí bastante curiosidad del público fue el de definición de Infraestructura cómo código (IaC) usando AWS CDK. Durante mi charla presenté varios ejemplos de 3 casos de uso, todos mostrando código en typescript y usando AWS CDK para los despliegues. A lo mejor mi próxima charla estará enfocada en este tema en específico

Repositorio de la charla

El código y ejemplos mostrados durante la charla se pueden encontrar en el siguiente Link de Github. Si pruebas los patrones de mi charla, o discrepas de ellos, me encantaría leerte!

Conclusiones

El AWS Community Day estuvo genial, pude conectar con algunos entusiastas del desarrollo, devops, cloud y aws. Fue una experiencia muy enriquecedora y la cual espero con ansias para el próximo año!

Mil gracias a las comunidades organizadores y voluntarios, a los sponsors, a los otros speakers y en general a los asistentes.

[Summary Generated With AI] This article outlines the process of creating a custom logo detector for the "SG Mascot" using Amazon Rekognition's Custom Labels. By preparing a dataset of positive and negative examples, we trained a model to identify the mascot in uploaded images efficiently. The solution leverages AWS services like Lambda, S3, and DynamoDB, creating a serverless architecture for scalable image analysis. Despite the tool's ease of use, the article highlights the potential cost implications and emphasizes the importance of stopping the model when not in use to minimize charges.

Introduction

Creating an identity for a brand is an important part of a business strategy. You want your brand to be easily recognized by others. At Serverless Guru we have an awesome and good-looking brand identity. One key component of that brand identity is the “SG Mascot”, which is easily recognizable and is visually appealing. It has a unique style in its drawing and colors

Image of the “SG Mascot”. Taken from https://sls.guru

The purpose of this blog post is to showcase a “custom logo detector”, that is capable of analyzing photos uploaded by people, reviewing those images and detecting if the “SG Mascot” is present in the image or not.

Imagine hosting a global event where hundreds of attendees send pictures of the event through a web application. The system will identify the ones that match the “SG Mascot” and offer, for example, some sort of ticket to a raffle or something similar. While it can be done manually and review each image one by one, it wouldn’t be such a scalable process. And since we have access to so many amazing and easy-to-use AI tools, why not automate the process?

After a bit of research, I found Rekognition Custom Labels. Since I have used Amazon Rekognition a few times in the past, I’m more or less familiar with the interface. This API allows you to identify different custom objects based on your own specific needs. All you need is a dataset to train the custom labels you want and then do inference on the resulting model!

Model Training

Preparing the Dataset

First, to train a good model that can detect the mascot accurately, we need a good dataset of images. Since this is a classification model, it’s enough to know if the SG Mascot is detected in a picture or not. So we need images that contain the mascot but also images that don’t contain the mascot to teach the model what not to detect

• Positive Examples: Images with the mascot

• Negative Examples: Images without the mascot

For the “Negative Examples”, I recurred to the COCO Dataset, which is a large, open dataset of images for machine-learning purposes. “COCO is a large-scale object detection, segmentation, and captioning dataset.“

Sample images from the COCO dataset. Images taken from https://cocodataset.org

For the “Positive Examples”, I manually gathered some images that I found for the SG Mascot. With this approach, I could only gather 13 different images of the “SG Mascot”. Since this is not enough to build a good model, I recurred to augment the dataset by generating new images from the exiting images. I did so by doing the following

• Rotating images

• Adjusting brightness and contrast

• Scaling the mascot to smaller or larger sizes

This will give a larger set of images for the “Positive” scenarios, resulting in a model that’s more robust and able to identify the SG mascot under different conditions.

After a bit of help from chatGPT, I executed the following script which was suggested by it:

const sharp = require('sharp');
const fs = require('fs');
const path = require('path');

const inputDir = './positive_images';
const outputDir = './augmented_images';

// Ensure output directory exists
if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir, { recursive: true });
}

// Augmentation settings
const rotations = [15, 45, 90, 180]; // Degrees to rotate
const scales = [0.5, 0.8, 1.2, 1.5]; // Scale factors
const brightnessFactors = [0.5, 1.5]; // Brightness adjustments

// Augment a single image
async function augmentImage(filePath, fileName) {
    const img = sharp(filePath);

    // Apply rotations
    for (const angle of rotations) {
        const outputPath = path.join(outputDir, `rotated_${angle}_${fileName}`);
        await img.rotate(angle).toFile(outputPath);
        console.log(`Generated: ${outputPath}`);
    }

    // Apply scaling
    const metadata = await img.metadata();
    for (const scale of scales) {
        const width = Math.round(metadata.width * scale);
        const height = Math.round(metadata.height * scale);
        const outputPath = path.join(outputDir, `scaled_${scale}_${fileName}`);
        await img.resize(width, height).toFile(outputPath);
        console.log(`Generated: ${outputPath}`);
    }

    // Adjust brightness
    for (const factor of brightnessFactors) {
        const outputPath = path.join(outputDir, `brightness_${factor}_${fileName}`);
        await img.modulate({ brightness: factor }).toFile(outputPath);
        console.log(`Generated: ${outputPath}`);
    }
}

// Process all images in the input directory
async function processImages() {
    const files = fs.readdirSync(inputDir);
    for (const file of files) {
        const filePath = path.join(inputDir, file);
        const fileName = path.basename(file);
        console.log(`Processing: ${fileName}`);
        await augmentImage(filePath, fileName);
    }
}

processImages()
    .then(() => console.log('Dataset augmentation completed.'))
    .catch((err) => console.error('Error during augmentation:', err));

Results of executing the “augment images” script. Original Images taken from https://sls.guru

Now the “Positive” dataset contains 130 images - way better than the previous 13 images. With this plus 130 “Negative” images taken from the COCO dataset, it’s time to train the model!

Training the Model in Rekognition

First thing we need to do is upload the dataset images to an S3 bucket. We can create a new bucket and add two folders: “Positive” and “Negative”. After uploading the respective images to each folder in the bucket, we go into the Rekognition console, “Use Custom Labels” and create a project. Then, after generating the project, we create a dataset and select “Import images from S3 bucket”. Also we need to make sure the “Automatically assign image-level labels to images” is checked. This will make the labeling automated

Dataset of images created and uploaded to the Rekognition Custom Labels. Original SG Mascot Images taken from https://sls.guru

Notice that the images were automatically labeled based on the folder name that we specified in the S3 bucket. That’s great as doing this process manually it’s quite tedious and time-consuming!

After having the dataset labeled, the project it’s ready to train the model! all we need to do is click on “Train model” and let it train for some time. In my case, it took approximately 45 minutes

After the training is done, we need to “start” the model. To do this, in the console, we go to the “Use model” tab in the results of the training, then click on “Start”. And that’s it! we’re ready to start using the model to detect the SG mascot!

Using the Model

Architecture

For our use case, we can design a simple service that leverages Event-Driven architecture and Serverless services to use the model we just trained. For this, the process starts with a user uploading a picture to an S3 bucket (it can be through a web application). The S3 bucket triggers a lambda function whenever an image gets uploaded. The Lambda function can then call the Amazon Rekognition “Detect Custom Labels” using the model we just trained, then store the results in a database like a DynamoDb Table:

Image of the backend architecture for detecting the SG Mascot in images. Own Creation

For implementing this architecture we can leverage the AWS CDK, which allows us to define these resources as typescript code. Check out the full code in my GitHub Repository

Testing

Since the project is created with the AWS CDK, we can easily create and connect these resources in the cloud using the commands “cdk bootstrap“ and “cdk deploy“.

After deploying the resources, we can upload images to the bucket manually and check the results. It seems it’s working as expected:

Cloudwatch logs for a “Positive” and a “Negative” image. Own creation

Cost

If you’re following this blog post, it’s important to note the cost of the Amazon Rekognition for detecting custom labels. It’s amazingly easy and simple to use, however the cost it’s significant even for a short POC like the one presented in this blog post.

For this blog post POC, I tested the model for a little while. Once the model is turned-on (hitting that “Start” button on the project), it starts to charge per minute, so even using it for only a small amount of time the bill resulted in 8.91 USD

Snippet of the billing for Rekognition in the AWS Console for the creation of the POC presented in this blog post. Own creation

So if you’re using it to follow this tutorial, make sure to STOP THE MODEL by hitting the “Stop” button after you’re done to avoid extra unnecessary charges

Conclusion

Automating the detection of a brand’s unique identity, like the “SG Mascot”, is a great example of how AI and machine learning can simplify and speed-up what can be a very tedious and manual process. Using Amazon Rekognition “Custom Labels”, this blog post covered the creation of a POC that analyses imaged uploaded by users and detects if the unique brand’s identity is found in the image, in this case, the “SG Mascot”

By leveraging the use of scalable and serverless services like Lambda, S3, dynamodb, we can build an cost-effective solution that integrates the components in a seamless way using the AWS CDK. While the “Custom Labels” cost can add-up with time, it’s an excellent tool for prototyping and for production systems.

References

• Rekognition Custom Labels

• Getting started with AWS CDK

• AWS SDK for Javascript - Detect Custom Labels

• COCO Image Datasets

• Serverless Guru Webpage

• Full POC Code Repository

[Summary Generated with AI] This article discusses the importance of offline capabilities in mobile applications to prevent data loss due to connectivity issues. It highlights how AWS AppSync and Amplify simplify offline data synchronization, allowing developers to focus on business logic. The article provides a proof of concept for a recipe-managing app, featuring a backend using AWS AppSync, DynamoDB, and AWS CDK for Infrastructure as Code. It explains how to connect the backend to a mobile frontend using AWS Amplify's DataStore, ensuring seamless data handling when offline. The article concludes by emphasizing the benefits of an offline-first strategy for mobile apps to enhance user experience.

Introduction

In today’s world standards, when planning to build a mobile application, it’s essential that offline capabilities are in place. This is important in order to avoid data loss, as mobile devices often suffer from bad connectivity and internet access may be limited

To offer the best user experience to users, an application that supports offline capabilities seamlessly is important. As a developer, manually managing updates that are in the device vs in the database can be very difficult to handle, as local device cache vs cloud database synchronizations may result in data being overwritten, deleted or ignored if not done properly

This is where AppSync and Amplify come to the rescue! The offline capabilities and data synchronization is already taken care by these two technologies, allowing the developers to focus on the business logic rather than spending too much time in carefully handling offline vs online synchronizations

Let’s take a look at how it works with a small POC for a simple recipe-managing app:

Recipe Managing POC

Use Cases

For illustrating the offline capabilities of AWS AppSync and Amplify, let’s build a simple poc app that lets a user manage recipes in a mobile device. Specifically, It allows for the two main use cases:

• Create recipes (Title, Description, List of Ingredients and Cooking Instructions)

• Get Recipe

A real recipe-app would have more use cases and be more robust, but for the purposes of illustrating the topic of this blog post, those should be enough

In order to fulfill these use cases, we can have a backend composed by a graphql AppSync API and a dynamodb table that holds the information. In the UI, we can use Amplify’s capabilities with DataStore for offline sync

Architecture

The architecture of the POC developed in this blog post involves a mobile app client that is using AWS Amplify to interact with AWS services. Amplify leverages the “DataStore”, which is connected to the Recipes graphql api, which uses a DynamoDb table “Recipes Database” to store recipes data

High-level overview of the architecture for the “Recipes App” POC. Own Creation

The Data Flow for this architecture starts from the mobile app client, which can be any modern framework to build mobile apps. Using an offline-first approach, the mobile framework can leverage AWS Amplify’s “DataStore” and integrate with the “Recipes API” to have the data synchronized between the device’s offline cache and the dynamodb “Recipes Database” table

Backend Implementation

Implementing this small poc is easy to do with the help of AWS CDK to define our resources as Infrastructure as Code. First, we can set-up a new cdk project with the following commands (make sure cdk’s latest version is installed in your system first)

# Install CDK globally (only if needed. run "cdk --version" to check)
npm install -g aws-cdk

# Create a new project
mkdir offline-first-recipe-manager
cd offline-first-recipe-manager
cdk init app --language typescript

This commands will create a new CDK stack called “offline-first-recipe-manager”.

After the project is bootstrapped, install the libraries for our aws resources:

npm install @aws-cdk/aws-appsync @aws-cdk/aws-dynamodb

Also make sure you have an aws account ready to use and you have a profile configured with programmatic access in your local machine. To find out how to do it, check this link

To check the implementation and code, please see the GitHub Repository

Connect the Backend to our mobile Frontend

Now that we have a backend poc ready, we can easily connect it to the mobile Frontend by using AWS Amplify’s configuration:

// If using React Native and Typescript
import Amplify from 'aws-amplify';

Amplify.configure({
  aws_appsync_graphqlEndpoint: '', // replace from the CDK output
  aws_appsync_region: 'us-east-1',
  aws_appsync_authenticationType: 'API_KEY',
  aws_appsync_apiKey: '', // replace from the CDK output
});

// If using Flutter and Dart, we can use the "initState" to initialize amplify:

@override
  void initState() {
    super.initState();
    _configureAmplify();
  }

  // Configure Amplify with the DataStore plugin
  Future<void> _configureAmplify() async {
    final dataStorePlugin =
        AmplifyDataStore(modelProvider: ModelProvider.instance);
    await Amplify.addPlugin(dataStorePlugin);
    try {
      await Amplify.configure(amplifyconfig);
      setState(() {
        _isAmplifyConfigured = true;
      });
    } catch (e) {
      print('Amplify configuration failed: $e');
    }
  }

Using the AWS Amplify’s DataStore is also easy to do. Using the SDK for the appropriate framework, we can use it to have an offline-first application:

// If using React Native and Typescript
import { DataStore } from 'aws-amplify'

async function fetchRecipes() {
  try {
    const recipes = await DataStore.query(Recipe)
    console.log('Fetched recipes:', recipes)
  } catch (error) {
    console.error('Error fetching recipes:', error)
  }
}

// If using Flutter and Dart
import 'package:amplify_flutter/amplify_flutter.dart';
import 'package:amplify_datastore/amplify_datastore.dart';

// ...
  void _queryRecipes() async {
    try {
      final recipes = await Amplify.DataStore.query(Recipe.classType);
      recipes.forEach((recipe) {
        print("Recipe: ${recipe.title}");
      });
    } catch (e) {
      print("Error querying recipes: $e");
    }
  }

By using AWS Amplify’s DataStore for fetching and saving the data instead of calling the API directly, we leave the data sync to Amplify. Even if the device is offline, the cache will store and sync later when connectivity is back

Conclusion

Building applications that handle data is a common day-to-day requirement. Thinking about mobile devices, where the connectivity can fail at times, we need to think about offline-first approach to data handling, which involves having data stored in the mobile device’s internal cache, and then synchronizing with the database (system of record)

Manually building this synchronization can be a very complex task. Luckily, AWS Amplify’s DataStore and AWS AppSync offer a seamless way to build these kind of offline-first apps. In this blog post I went over a simple POC for handling cooking recipes from a mobile device using this offline-first approach

With technologies such as AWS CDK, AppSync and DynamoDb, building the backend was simple and fast, while integrating with a mobile app was also simple by using Amplify’s configuration and SDK capabilities.

By using an offline-first strategy in your app you’re future-proofing your app and providing real value to users who may have spotty WiFi or internet connection, which may be common. Check out the GitHub Repository for the implementation and experiment with these technologies for you next project. Happy Coding!

References

• Recipes POC Github Repository

• Amplify Docs - Set Up Amplify DataStore

• Configure security credentials for the AWS CDK CLI

• AWS Blog - Amplify DataStore + GraphQL

Recently, I got curious about how easy it is nowadays to build an AI-powered app. So, I decided to give it a shot and was blown away by how easy and fast it was.

Given the some recent AWSome pre:invent announcements, I saw that the amplify team released an Amplify AI Kit for developers to build full-stack, ai-powered apps.

So, I followed the tutorial in the aws documentation for a recipes assistant. I just wanted to see how easy and fast it was to have something up and running. My aim was to create a story-telling app that could take different inputs for the story, like genre, tone and style.

Implementation

After approximately 40 minutes of implementing the tutorial (I like to read first and type the code instead of copy/pasting), I already had a simple poc ready, with authentication, somewhat nice views and inference for creating cooking recipes!

After that it was a matter of playing around with what the app would do. I added a couple of selects with options for the user to generate different kinds of stories:

• Genre: Sci-fi, Mystery, Fantasy, Romance, Horror

• Tone: Light, Humorous, Dark, Adventorous

• Style: First Person, Third Person, Fairy Tale, Poetic

After that, changed the definition in the amplify data’s resources, which defines cloud resources that will be used. So three things mainly changed: the arguments, returns and the system prompt:

const schema = a.schema({
  generateShortStory: a.generation({
    aiModel: a.ai.model('Claude 3.5 Sonnet'),
    systemPrompt: "You are a story-teller that generates short, engaging stories based on user-provided themes or genres. Each story should have a clear structure: an introduction to set the stage, a middle to develop the plot, a twist to surprise the reader, and a satisfying ending. The characters should be fictional, with at least one relatable protagonist. Adapt the tone and style based on user input. Ensure the story is concise and self-contained.",
  })
    .arguments({
      genre: a.string(),
      tone: a.string(),
      style: a.string(),
    })
    .returns(
      a.customType({
        numberOfParagraphs: a.integer(),
        story: a.string(),
      })
    )
    .authorization((allow) => allow.authenticated()),
})

After making this change and saving, while still having active the amplify sandbox environment (npx ampx sandbox), the cloud resources would compile and resources would be updated to reflect these changes! Just need to wait for a minute or two and it’s done!

After making a couple of minor tweaks to the UI, so the page looks a bit nicer, the end result was the following

Image that shows the view of the completed story-telling POC app. Own creation

Pretty good considering it took me only like a couple of hours of experimentation!

Changing the AI model is very easy as well, as I was experimenting with different Claude models. Ultimately went with the Claude Sonnet 3.5

Architecture

So, what’s under the hood? When inspecting in the AWS console about what resources are spinned up, we realize it’s some awesome AWS Serverless infrastructure that’s powering this AI-kit. So apps created with this AI-kit are ready to power your web apps and scale as easily as a serverless stack allows.

Image that shows the general architecture of apps created using the aws amplify’s AI kit. Taken from Build fullstack AI apps in minutes with the new Amplify AI Kit

The image above is the one that powers the full AI-kit from Amplify. For my simple POC app, which only uses the “generate” variant of the kit (no conversation), I discovered that the stack is a bit different. It doesn’t use dynamodb or lambda, instead aws appsync makes a direct HTTP request to bedrock, and the mapping template from appsync does the logic of formatting the response properly:

Image that shows the architecture of the short-story teller app created in this blog post using aws amplify’s generation ai kit. Own creation

Full code repository of this POC can be found here: https://github.com/LucasVera/story-telling-app

Conclusion

This experiment showed me just how far tools like AWS Amplify and Bedrock have come. In just a few hours I could get my app from idea to a working proof-of-concept. The best part is that it’s backed by a scalable and efficient serverless infrastructure!

It’s exciting to see how easy it is nowadays to experiment with AI-powered projects, and I’m looking forward to exploring and enhancing the POC even further. Even launching it may also be a good idea!

References

• https://docs.amplify.aws/react/ai/set-up-ai/

• https://aws.amazon.com/blogs/mobile/build-fullstack-ai-apps-in-minutes-with-the-new-amplify-ai-kit/

• https://ui.docs.amplify.aws/react/getting-started/usage

• POC Repo: https://github.com/LucasVera/story-telling-app

• https://docs.aws.amazon.com/appsync/latest/devguide/what-is-appsync.html

• https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html

• https://aws.amazon.com/bedrock/

This article presents a proof of concept for a real-time voting app facilitating SCRUM grooming sessions using AWS AppSync for a serverless GraphQL API and DynamoDB for storage. It outlines the architecture, data modeling, and implementation details, leveraging AppSync's real-time updates and DynamoDB's single-table design and TTL feature for an efficient voting system. [Summary Generated with AI]

Introduction

In the SCRUM agile methodology, the grooming sessions are meetings where team members get together and agree on how much effort is a particular story worth. This is measured in points. Typically, each team member would give a secret vote for the effort on a particular story, then all votes get revealed and, based on the votes, the team agrees on an effort for a story

In this blog post we will cover a proof of concept for a real-time app that facilitates the voting session that takes place as part of a grooming session. For this, we will use AWS technologies - specifically AWS AppSync for the backend real-time API and DynamoDb for any storage needs

Use Case and Architecture

For the use case, we identify two main actors for the system: “Session Creator” (SC) and “Session Participant” (SP). The SC is responsible for creating a voting session, then sharing the session with other people. Then, the SPs are responsible for joining the session. After enough SPs have joined the session, the SC can start the voting session. Each SP can cast a secret and private vote. After everyone has voted, the SC can reveal the votes and that will conclude the voting session.

For each of the actions described, it’s important to notify all participants and the creator so that updates are visible to everyone.

With that use case in mind, we can lay out a general high-level overview of the system as an AWS AppSync API that allows each actor to perform operations to interact with the system, and at the same time allow for subscription to real-time events for operations made by other actors:

The good thing is that AWS AppSync allows for easily building a serverless graphql API, which supports “subscriptions”. These subscriptions are websockets implementation which allows for server-to-client communication. So a session participant can receive events when other participants joins, vote or when a voting session starts or ends.

Sample Implementation

For implementing this backend we can leverage the usage of javascript and AWS AppSync resolvers to perform all interactions needed. For this API, it’s needed to interact with the dynamodb table and send message to other clients. With AppSync is easy to build an API using javascript resolvers. Interacting with the dynamodb table can be done through direct integrations between AppSync and DynamoDb (no need for lambda or other computing resource).

For sending real-time updates in the graphql subscription, another awesome thing about AppSync is that the heavy lifting is done by AppSync. Using configuration in the schema, we are able to connect a graphql mutation to a subscription so that everytime that mutation is requested, the response will trigger a subscription response to all susbcribed clients (SC and SPs)

Schema

For the schema we need to take into account all operations for both the SC and the SPs. Along with operations, we need to define the subscriptions so that clients can receive the real-time updates. As this is a sample implementation, for auth a simple API_KEY approach will be used however in production is recommended to set-up a more robust auth method. The following shows a sample graphql schema with the operations and the subscriptions:

schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

type Query @aws_api_key {
  getSession(sessionId: String!): Session
}
type Mutation @aws_api_key {
  createSession(participant: ParticipantInput!): Session
  startSession(sessionId: String!): Session
  endSession(sessionId: String!): Session
  addParticipant(sessionId: String!, participant: ParticipantInput!): Participant
  removeParticipant(sessionId: String!, participantEmail: String!): Participant
  updateParticipantVote(sessionId: String!, participantEmail: String!, vote: Int!): Participant
}
type Subscription @aws_api_key {
  onParticipantAdded(sessionId: String!): Participant
    @aws_subscribe(mutations: ["addParticipant"])
  onParticipantRemoved(sessionId: String!): Participant
    @aws_subscribe(mutations: ["removeParticipant"])
  onParticipantVoted(sessionId: String!): Participant
    @aws_subscribe(mutations: ["updateParticipantVote"])
  onSessionStarted(sessionId: String!): Session
    @aws_subscribe(mutations: ["startSession"])
  onSessionEnded(sessionId: String!): Session
    @aws_subscribe(mutations: ["endSession"])
}

Notice the use of “@aws_subscribe” when defining the subscription. We specify the mutation that will be connected and that’s it! AWS AppSync takes care of the rest.

Data Modeling

For the data modeling needs, we need to keep track of sessions created, session participants that joined a particular session and votes for a session. Using DynamoDb Single-Table Design principles we can keep track of all this information in one table. Using a unique id for each session, we can tie together sessions, participants and votes, as shown in the following image

Without going too much into details of single table design, notice that we can store different entities depending on the PK+SK combination. In this case, we identify two entities: Session Details and Session Participants.

• Session Details

  • PK: SESSION#<session_id>

  • SK: SESSION#<session_id>#DETAILS

• Session Participant

  • PK: SESSION#<session_id>

  • SK: SESSION#<session_id>#PARTICIPANT#<participant_email>

This gives us flexibility when reading information for a particular session, as we can either read all entries for a session, or read some of it depending on the query pattern we specify.

Another thing to highlight from the data modeling is the usage of DynamoDb TTL. This feature allows for self-cleaning of the dynamodb table of old sessions that may no longer be active. The awesome thing is that it’s done automatically by DynamoDb once the “expirationTime” timestamp has passed.

Code

The following repository contains a partial implementation of this API: GitHub Repository

Conclusion

Using AWS AppSync and DynamoDb, this proof of concept shows an simple implementation for a real-time, serverless voting system that’s useful for SCRUM grooming sessions.

The capabilities of AWS AppSync simplify the implementation of graphql subscriptions for the real-time updates. Using DynamoDb for data storage needs allows for scalable and performant operations while leveraging the use of single-table design for cohesive data storage and DynamoDb TTL for self-cleaning of inactive sessions.

This architecture allows for scalable and low-latency interactions between participants in a grooming session, resulting in effective and efficient SCRUM ceremonies.

References

• SCRUM Backlog Grooming: Scrum Grooming Meeting: Backlog Refinement Meetings Best Practices

• AWS AppSync:

  • What is AppSync: AWS Documentation

  • Subscriptions for Real-time updates in AppSync: AWS Documentation

• DynamoDb:

  • Main Documentation Page: AWS Documentation

  • Single-Table Design: The What, Why, and When of Single-Table Design with DynamoDB

  • No SQL Workbench for Dynamodb Data Modeling: AWS Documentation

• Sample code implementation: GitHub Repository

[generated with AI] AWS AppSync simplifies the creation and management of GraphQL APIs by connecting data sources to resolvers through functions, enhancing front-end and back-end collaboration. This article explores the advantages of using AppSync’s direct integration capabilities, showcasing examples with DynamoDB, OpenSearch, and HTTP data sources to improve performance and reduce costs by eliminating unnecessary AWS Lambda usage. Leveraging direct integrations not only optimizes operations but also simplifies architecture and promotes reusability within the API.

Introduction

AWS AppSync is a serverless services that makes it very easy to build and maintain GraphQL APIs. It works by connecting “data sources” (such as lambda) to the “resolvers” through “functions”. Each function has one data source associated and also executes logic.

With AppSync, we can define an entire API schema and business logic in a single place, allowing for front-end and back-end developers to collaborate more efficiently. The following image shows the high-level of a typical AppSync API architecture.

Image that shows the architecture of a graphql API in AWS AppSync. Source: Own Creation

Each resolver function in an appsync API can be written in javascript or VTL (Velocity Template Language). In this blog post we’ll be focusing on javascript resolvers as they are more popular. It’s not a full-feature javascript engine, rather it’s a sub-set of javascript that allows to execute some simple logic in conjunction with the resolver’s data source execution.

However, It’s common to see developers defaulting to use AWS Lambda as a data source for graphql operations that may not need one. AWS Lambda is a fantastic serverless compute that uses the Functions-as-a-Service model (FaaS) to execute code. While the approach works, it introduces latency due to Lambda’s ephemeral execution environment, incurring in cold starts. It also incurs additional costs - specially in high frequency operations.

The following image shows an example of an AppSync’s architecture that can be improved

Image that shows an improvement on performance and cost for appsync api that only interact with a dynamodb database. Source: Own Creation

In this blog post we’ll take a look at AppSync’s direct integration capabilities. Using direct integration may remove a lambda if it’s not needed. This results in higher performance and lower costs. It can also help simplify an architecture and at the same time, having reusable resolver functions promotes re-usability within the API.

Example 1: DynamoDb

DynamoDb Is a serverless NoSQL database service offered by AWS. It’s main advantage is that it provides fast and predictable performance regardless of scale. DynamoDb is an ideal database choice for serverless application.

In data-driven APIs, the most common operations are CRUD operations: Create, Read, Update and Delete operations to a database. So using the direct integration with appsync and dynamodb is a very common use case. The following is a sample snippet of a resolver function that interacts with a dynamodb table.

export function request (ctx) {
  const { args } = ctx;
  const { blogPost } = args;

  // Any validation logic or transformation/mapping logic

  return {
    operation: 'UpdateItem',
    key: util.dynamodb.toMapValues({ BlogPostId: blogPost.id }),
    update: {
      expression: 'SET #BlogPost = :blogPost',
      expressionNames: { '#BlogPost': 'BlogPost' },
      expressionValues: {
        ':blogPost': util.dynamodb.toDynamoDB(blogPost),
      }
    },
  };
}

export function response (ctx) {
  const { result } = ctx;
  // ... any transformation/mapping logic, etc

  return result.Attributes.BlogPost;
}

Code snippet that shows an AppSync Javascript Function Resolver which directly interacts with a dynamodb table. Source: Own Creation (Gist Link)

Notice in the code that the resolver has capabilities of mapping, validating and even doing a bit of computation. So the most common use cases around CRUD operations can be covered in pure function resolvers without needing a lambda in between.

Example 2: Open Search

Amazon Open Search is a managed service that helps run open search (and elastic search) clusters at scale. It shines in analytics, monitoring and click streams.

With AWS AppSync, we can use integrate directly from a resolver function to perform a query in open search, as shown in the following code snippet.

import { util } from '@aws-appsync/utils';

// Searches for posts in the OpenSearch index
export function request(ctx) {
  const { args } = ctx;
  const { searchTerm } = args;

  // ... Any other logic to build the query

  return {
    operation: 'GET',
    path: '/post/_search',
    params: {
      body: {
        from: 0,
        size: 20,
        query: {
          match: {
            content: searchTerm || '',
          },
        },
      },
    },
  };
}


export function response(ctx) {
  const { result, error } = ctx;

  // Handle errors
  if (error) {
    util.error(error.message, error.type);
  }

  // Extract and return search hits from the response
  const results = result.hits.hits.map(hit => hit._source);

  // ... Any other business logic to process the results

  return results;
}

Code snippet that shows an AppSync Javascript Function Resolver which directly interacts with an open search cluster. Source: Own Creation

Same as with the Example 1, notice there is room for validation/mapping/error handling in the resolver function itself. Using this direct integration method without having a lambda in between to execute complex search queries will likely saves costs and increase performance.

Example 3: HTTP call

There is a Data Source for AppSync called HTTP. With this Data Source, we specify an endpoint, then in the resolver we can include query parameters, body, path, HTTP method and headers. This is useful when we’re fetching data from third-party APIs, microservices or even other AWS resources that don’t have a direct integration.

The following shows an example of an external API that verifies the validity of an email from the input.

import { util } from '@aws-appsync/utils';

export function request (ctx) {
  const { args, env: { VERIFY_EMAIL_API_KEY = null } } = ctx;

  if (!VERIFY_EMAIL_API_KEY) util.error('No email verification api key provided', 'ValidateEmailError', null, null);

  // ... any other additional logic for validation/mapping/preparation

  return {
    method: 'GET',
    params: {
      query: {
        email: args.email,
        apikey: VERIFY_EMAIL_API_KEY,
      }
    },
    resourcePath: `/verify-email`
  };
}

export function response (ctx) {
  const {
    result,
    error,
  } = ctx;

  if (error) {
    // error handling
  }

  const { body } = result;
  if (!body) util.error("Email is not valid", 'ValidateEmailError', null, null);

  // Any additional logic or checks

  return {
    isValid: true,
  };
}

Code snippet that shows an AppSync Javascript Function Resolver which directly interacts with a verification email third party endpoint. Source: Own Creation

Notice in the code snippet that we can specify different details like the HTTP method GET, query parameters and path.

It is also possible to interact with other AWS resources that don’t have a direct integration with AppSync using this “HTTP Data Source”. For example it’s possible to add a message to an SQS queue using the direct integration with HTTP. AppSync will sign the request of the HTTP method using the current AppSync execution role.

Summary

We explored how can AppSync integrate with services such as DynamoDb and OpenSearch, and even with HTTP endpoints. These direct integrations, compared with an architecture that involves using lambdas, allow to reduce costs and enhance performance. It can also simplify the architecture of the GraphQL API. This approach also promotes reusability as the resolvers may be used in other graphql operations.

References

• AWS API Documentation:

  • AppSync Javascript’s supported features

  • DynamoDb Direct Integration

  • OpenSearch Direct Integration

  • HTTP Direct Integration

• Get Started With AppSync Javascript Resolvers

• AppSync Best Practices

Earlier this year I discovered the book 97 Things Every Programmer Should Know. It's a book which has a bunch of amazing wisdom regarding software engineering. I didn't go one by one in order but jumped around in between the items, and could relate through most of them.

It reminded me of many times in my career where I didn't follow these concepts. There was a learning in those times and some items described in this book resonated with me immediately.

As software developers, sometimes we think that getting better as a developer and advancing in our careers involves technical expertise. So we get obsessed with learning that new framework, new technology, etc. But in my experience, while being technically proficient is important, the non-technical aspects are what allow a developer from going to "good" to "amazing" developer.

I recently gave a talk to my dev team and shared three concepts from the book. While I haven't read all the items, I shared the three that resonated with me the most so far. In this blog post I wanted to share them because I think they help developers improve.

1. What Would the User Do

By Giles Colborne

This concept highlights that we, as software developers, are not the users. Users of the software have different mental models and problem-solving approaches. Sometimes we create assumptions based on user's input or actions, or assume that the users will understand and use the software.

Observing users is really insightful as well. Using observability and analytics tools that help gather what users do when using the software is really helpful in understanding what are the pain points users face.

One example that I think it's easy to relate to is user input. Sometimes when dealing with user input we, as software developers, assume that the formatting would be as we expected and programmed. However, as mentioned in this concept, "we are not the users". That means we need to think about the different possibilities for the user input.

In the following example I present a function that's receiving a phone number from the user. The function assumes the format to be in a certain way. However, users may be able to send a phone number in different ways:

Without the concept

function validatePhoneNumber (phoneNumber) {
  // Assume users will enter phone numbers in the '123-456-7890' format
  const regex = /^\d{3}-\d{3}-\d{4}$/;
  return regex.test(phoneNumber);
}

// Example usage
const userInput = '123-456-7890';
const isValid = validatePhoneNumber(userInput); // Worksfor the expected format only

In this example we see a simple function validatePhoneNumber, which validates if a phone number is valid or not. The function expects the format 123-456-7890 for phone numbers. But if we ask the question ¿What would the user do?, the answer is that the user will probably use other types of inputs:

Applying the concept

function validatePhoneNumber (phoneNumber) {
  const regex = /^\d{3}-\d{3}-\d{4}$/;
  if (!regex.test(phoneNumber)) {
    throw new Error('Invalid phone number format. Please use the format: 123-456-7890');
  }
  return true;
}

// Example usage
const input = '(123) 456-7890';
try {
  validatePhoneNumber(input);
  console.log('Phone number is valid');
} catch (error) {
  console.error(error.message);
}

After applying the concept to this simple function, we can refactor our code to have better error handling to gracefully handle other formats for phone numbers that the user can input. Our code will probably result in a better user experience because the user can receive feedback about the expected format.

2. No "Magic Happens Here"

By Alan Griffiths

This is a concept that developers (myself included) break a lot. It's very easy to assume things "just work" without knowing how they work. This applies to many things: functions or classes, API calls, Async processes and even other people or other teams!

Having an understanding of critical dependencies ensures our own software components are interacting correctly with other processes. "Magic" components or software can fail. When we understand what happens under the hood, we can align better with error handling and ensure a better experience. This makes our software more robust

When building software that interacts with unfamiliar processes/components, take the time to understand it

This concept also applies to other people or teams. From a developer POV, it's easy to just code and be in a "bubble" where we just assume other people/teams just work. Product Managers, Business Analyst, QA Testers, etc. Imagine just how chaotic things will be without them

For the following example, we have a simple function that sends an email. The function uses an unfamiliar "magical" process that sends the message. Assuming it will just work, without understanding the underlying process, makes the function susceptible to unhandled exceptions, and potentially using the process in a wrong way:

Without the concept:

async function sendEmail (recipient, subject, message) {
  const queueMessage = { recipient, subject, message, behavior: "send" };

  // magically sends the email
  await sendToSqsQueue(queueMessage);
}

// Example usage
const recipient = "test@test.com";
const subject = "Hello!";
const message = "This is a test email.";
await sendEmail(recipient, subject, message);

This function is sending an email. However It doesn't handle any potential errors that may occur during the process. Also, it sends the message with the behavior as send. Without understanding the purpose of the behavior parameter, it's hard to improve or maintain the code.

Applying the concept:

async function sendEmail (recipient, subject, message) {
  try {
    const queueMessage = { recipient, subject, message, behavior: "sendEmail" };
    await sendToSqsQueue(queueMessage);
    return true;
  } catch (error) {
    console.error("Failed to send email:", error);
    return false;
  }
}

// Example usage
const isEmailSent = await sendEmail(recipient, subject, message);
if (isEmailSent) {
  console.log("Email sent successfully!");
}
else {
  console.log("Failed to send email. Please try again.");
}

Now, after inspecting and understanding the unfamiliar sendToSqsQueue process, error handling can be appropriately implemented. Also, the behavoir parameter can be set to a better, more performant alternative

Notice that it's not necessary to memorize every small detail about an unfamiliar process - Sometimes just reading the documentation of a "magical" API or process can be enough!

3. The Boy Scout Rule

By Robert C. Martin (Uncle Bob)

This concept is about continuous improvement and refactoring. The boy scouts have a rule: "Always leave the campground cleaner than you found it". Transposed to the software world, it could be similar to "Always leave the code a little bit cleaner than you found it".

This rule is about being able to refactor code as you implement changes in a codebase. Little improvements over time can make a huge difference, specially in a large repository.

I think this is a great rule, as long as it doesn't involve huge refactoring. Ultimately, when working in a change we don't want to break what's already working! The level of refactoring comes to the level of comfort and familiarity with the process (see concept 2). Improvements that impact readability and maintainability are greatly appreciated

A high-performing software team can adopt this rule, which prevents gradual deterioration of the codebase. The larger a codebase becomes, the more difficult changes become if not following a maintainability and refactoring culture. This concept aims to improve code quality every time someone touches a module

For the code example, a function with several bad practices is shown. When a new feature gets implemented, also a small portion of the function is refactored to improve maintainability and readability:

Without the concept:

function calcOrder (odr) {
  let x = 0;

  // Sum up item prices
  for (let i = 0; i < odr.length; i++) {
    x += odr[i].prc * odr[i].qty;
  }
  // Apply discount if applicable
  if (odr.length > 5) {
    x = x - (x * 0.1);
  }
  // Special handling for specific product IDs
  if (odr.some(e => e.id === 'ABC123')) {
    x += 100;
  }

  return x;
}

This is a sample function that has some bad practices. Bad naming convention for variables, magic strings and numbers, not following the Single Responsibility Principle are among the most apparent.

Applying the concept:

function calcOrder (odr) {
  let total = 0; // Improved variable name

  for (let i = 0; i < odr.length; i++) {
    total += odr[i].prc * odr[i].qty;
  }
  if (odr.length > 5) {
    total = total - (total * 0.1);
  }
  if (odr.some(e => e.id === 'ABC123')) {
    total += 100;
  }

  // New feature: discount for orders over $500
  if (total > 500) {
    total -= 20;
  }

  return total;
}

When implementing a new feature in this function, aside from implementing the required change, the developer also takes the effort to make a small readability improvement: changing the variable called x to something more appropriate, like total. Notice the function wasn't all refactored, only a small portion was. The idea is to refactor small portions of code at a time to avoid big refactors that can result in more harm than good

Summary

1. What Would the User Do? We’re building a digital product for the users. But we are not the users - Think how would users interact with the software and take appropriate action

2. Don't Rely on "Magic Happens Here": Don’t assume a process or component “just works” - have an understanding of critical dependencies. Also applies to other people/roles

3. The Boy Scout Rule: Continuous improvement - leave the codebase a bit better that what you found it. Make small refactors aimed towards maintainability and readability

Conclusion

By Following the concepts explained here, you can become a better software developer. These concepts are not purely technical, but I see them more on how to improve in the "Collaboration", "Teamwork" and "Purpose".

In my experience, awesome software developers have great non-technical skills, and the concepts presented here can help a software developer go from "good" to "great" or "awesome"!

References

• 97 Things Every Programmer Should Know

At the beginning of my career, I remember my first software company introducing me to "unit tests." Back then, it was literally a checklist of tasks that I had to manually verify before checking in my code to version control. Over time, these tests have evolved. Now they cover real use cases, edge cases, and more complex scenarios. There’s something fascinating about seeing a test fail because of a code change; it means the test is doing its job. It provides a sense of security and confidence that the codebase is "protected".

As I learned more about automated tests and integrated them into code repositories, I noticed something was off: some tests seemed to be written just for the sake of it. It was easy to create a lot of passing tests, but not all of them were necessarily useful. Over time, I realized that the best tests are the ones that focus on the business logic - the real purpose of software systems. These tests ensure the core functionality works as expected and reflect the real-world scenarios that the software will encounter.

To me, the most valuable tests also act as documentation for the project. They describe the logic and rules the software is following. Rather than aiming for "100% code coverage," it's often more valuable to focus on tests that cover real use cases and different scenarios within the product and business logic.

Earlier this year, I stumbled upon Gerard Meszaros' article, Write Tests for People. In this article, Meszaros asks a fundamental question: "Who am I writing the test for?" The answer is that tests should be written for the person trying to understand your code. Good tests can act as clear documentation that helps developers understand how the system behaves.

This mindset resonated with me. It’s something we as developers can sometimes overlook, myself included. In this blog post, I want to share some examples of unit tests that I believe are truly useful, not because they contribute to some arbitrary percentage of code coverage, but because they provide clarity and real value to the project.

Practical Examples

Example 1: Calculate Discount

Imagine we have a function that calculates a discount given a price and a discount percentage. The function also needs to validate some of its input, as shown below:

function calculateDiscount (price, discountPercentage) {
  if (price <= 0 || discountPercentage < 0 || discountPercentage > 100) {
    throw new Error("Invalid input");
  }
  const discount = (price * discountPercentage) / 100;
  return price - discount;
}

Bad Test Example ❌

test('test price calculation', () => {
  expect(calculatePrice(100, 20)).toBe(80);
});

What’s wrong with this test?

• This test is lacking context. The test name is vague and doesn't tell us what specific scenario is being tested.

• It doesn't tell us anything about the logic. There’s no indication of why this particular discount and price are being used or what the business rule behind them is.

• It's not readable and doesn't give future developers any insight into the functionality, making it hard to maintain or change in the future

Improved Version ✅

describe("calculateDiscount", () => {
  test('should throw an error for negative price', () => {
    const price = -100;
    const discount = 20;

    expect(() => calculateDiscount(price, discount)).toThrow('Invalid input');
  });

  test('should throw an error for discount greater than 100%', () => {
    const price = 100;
    const discount = 120;

    expect(() => calculateDiscount(price, discount)).toThrow('Invalid input');
  });

  test('should apply a 20% discount on a $100 product', () => {
    const price = 100;
    const discount = 20;

    const result = calculateDiscount(price, discount);

    expect(result).toBe(80);
  });

  test('should return the full price when discount is 0%', () => {
    const price = 100;
    const discount = 0;

    const result = calculateDiscount(price, discount);

    expect(result).toBe(100);
  });
});

Why is this a better test?

• Names are clear and descriptive. They explain the scenarios being tested

• Each test describes a real-world scenario, which adds clarity in the use cases that the function covers (valid and invalid inputs)

• The tests follows a structured pattern (like the AAA Pattern). This makes it easy to understand and correlate the different scenarios together

• The tests cover different scenarios like the error handling, which is an important part of the business logic

Example 2: Discount eligibility

For the second example, we have a function that verifies the eligibility for a discount based on an age. An example implementation is described below:

function isEligibleForDiscount (age) {
  if (age < 0 || age > 120) {
    throw new Error("Invalid age");
  }
  return age >= 65;
}

Bad Test Example ❌

test('check discount eligibility', () => {
  expect(isEligibleForDiscount(70)).toBe(true);
});

What’s wrong with this test?

• The name is vague and generic. It doesn't give info on the scenario

• Edge cases are not covered as only one value is used

• the test doesn't give any context on the logic of the function and doesn't explain why is it using the provided input and output

Improved Version ✅

describe('isEligibleForDiscount', () => {
  test('should return true for age 70 (eligible for senior discount)', () => {
    const age = 70;
    const result = isEligibleForDiscount(age);
    expect(result).toBe(true);
  });

  test('should return false for age 50 (not eligible for senior discount)', () => {
    const age = 50;
    const result = isEligibleForDiscount(age);
    expect(result).toBe(false);
  });

  test('should return true for age 65 (boundary value)', () => {
    const age = 65;
    const result = isEligibleForDiscount(age);
    expect(result).toBe(true);
  });

  test('should throw an error for negative age', () => {
    const age = -5;
    expect(() => isEligibleForDiscount(age)).toThrow('Invalid age');
  });

  test('should throw an error for age over 120', () => {
    const age = 130;
    expect(() => isEligibleForDiscount(age)).toThrow('Invalid age');
  });
});

Why is this a better test?

• The tests uses descriptive names that tell the story behind the scenario

• The tests covers different values for input and expected outputs, including the edge cases

• The tests give business context about the underlying logic in the test

• The tests follow a structured pattern, which helps in relating the different cases and understanding them

Conclusion

Unit tests can be a powerful tool to not only safeguard our code from bugs and issues, but also to provide clarity and documentation. The key is focusing on real-world use cases and covering the business logic that our software product uses.

The goal isn't to "write tests until we hit 100% test coverage" - rather the objective should be creating tests that offer insights and help in understanding the underlying business logic.

Let's focus on writing tests that matter!

When discussing challenges in the education system, we can identify that measuring student’s attention is challenging, especially in a virtual environment, where there is a lack of closeness between students and the educator. It’s known through various research efforts that students in virtual environments engage and participate less in the virtual classroom than those in a normal classroom. As a consequence, students in virtual environments find the learning experience more challenging, and as a result, their learning is negatively affected.

One way to mitigate this problem is when the teacher implements “active learning” strategies, which consist of different activities that stimulate and engage the students:

• Propose debates

• Q&A sessions

• Ask student’s opinions

• Group discussions

• Facilitate student-to-student interactions

However, to properly implement these strategies, an educator needs to balance their explanations with these active learning strategies. One important metric for balancing that is the “engagement level” of each student. In a virtual environment, this is very challenging to measure.

Measuring Attention Level

In 2020, a group of researchers from Georgia Southern University presented an approach to identify the attentiveness of students. They conducted an experiment in which students’ faces were recorded while they were in a class. It gave a dataset of face pictures, which they proceeded to label as attentive or inattentive, based on expert supervision (human labeling). After that, they trained a machine learning model based on the data set which identifies the attention level of a student's face.

After getting a working model for identifying attention level, they correlated that model with emotions identified using AWS Rekognition. They made a correlation between the model attention level and the emotions identified by AWS Rekognition. As part of that correlation, they crafted the following formula which helps in identifying attention levels based on the AWS Rekognition emotions for a face:

^{Taken from Tabassum, T., Allen, A. A., & De, P. (2020). Non-intrusive Identification of Student Attentiveness and Finding Their Correlation with Detectable Facial Emotions. ACM Southeast Conference - ACMSE 2020 - Session 1, 127-134.}

The values of the formula can be found in the following correlation table:

^{Taken from Tabassum, T., Allen, A. A., & De, P. (2020). Non-intrusive Identification of Student Attentiveness and Finding Their Correlation with Detectable Facial Emotions. ACM Southeast Conference - ACMSE 2020 - Session 1, 127-134.}

Disclaimer

Using this formula we can get the attention level of a student’s face, but it’s important to mention this is an approximation using a correlation between the different emotions of a face and the student’s attention level. Therefore, it’s an academic exercise and should not be considered the reality of a student’s engagement with the class. It’s only an approximation that serves as a starting point for analyzing trends and adapting the teaching strategies accordingly. It’s critical for educators and technologists to use these tools as supplements, not replacements, in a live education setting.

Architecture

So, we want to create a system that measures and gives recommendations to the teacher as the virtual class progresses. In this post, I present an approach using event-driven and serverless architecture to accomplish the following tasks:

• Capture screenshots of students’ faces as they participate in a virtual class

• Automatically identify and analyze all students’ faces, and get emotion coefficients using AWS Rekognition

• Determine the attention level of each student and the overall attention level for the class

• Recommend an activity to the teacher

So, we can identify a couple of modules or services to accomplish it, as shown in the following high-level overview:

As marked in the diagram, this blog post will cover the “Screenshot Analyzer” system. The “Teacher Recommender” will be covered in a future blog post

Expanding on the “Screenshot Analyzer” system, we can delve into the detailed design with the following diagram that shows the AWS resources and services that we’ll be using to build the solution:

In the image, we can see that the idea is to have a Node.js console application take screenshots of the virtual class video in a set interval of time. Each screenshot gets uploaded to an S3 bucket where a Lambda function gets triggered every time a new screenshot gets created. This Lambda is responsible for analyzing the screenshot, extracting the faces, and posting the results in a DynamoDB table.

Solution

Screenshot App

For the screenshot application, we can use the npm package “screenshot-desktop” to take the screenshots from our node.js application. Using a simple “setInterval” in javascript, we can set a recurring timer that takes a screenshot, and then uploads the image buffer into an S3 bucket using the AWS SDK for javascript (v3), as shown in the following code snippet:

  setInterval(async () => {
  const screenshotTime = getTimestamp()
  // For example:
  // - /classes/2022-01-01/classid-123456/screenshotid-9518945.jpg
  // - /classes/2022-01-01/classid-123456/screenshotid-3159841.jpg
  const screenshotFilePath = `${basePath}/screenshotid-${screenshotTime}.${SCREENSHOTS_FORMAT}`
  try {
    const imgBuffer = await screenshot({ format: SCREENSHOTS_FORMAT })
    const metadata = {
      classId: classId.toString(),
      classStartedAtTimestamp: getTimestamp(startDate).toString(),
      screenshotTime: screenshotTime.toString(),
      screenshotBasePath: basePath,
    }
    await aws.s3.uploadToS3(BUCKET_NAME, screenshotFilePath, imgBuffer, metadata)
  } catch (error) {
    console.log('err', error)
    logMsg('Error taking and saving screenshot.', error, { screenshotTime, screenshotFilePath })
  }
}, SCREENSHOT_INTERVAL_SECONDS * 1000)

(Full code repo can be found in the References section at the end of the article)

Screenshot Analyzer

After a new screenshot gets added to the S3 bucket, we “hook up” a Lambda to the S3 so that the Lambda gets triggered automatically when a new screenshot gets uploaded. Using the Serverless Framework, this can be done easily as shown in the following code snippet:

events: [
    {
      s3: {
        bucket: `${process.env.BUCKET_NAME || '${env:BUCKET_NAME}'}-${process.env.STAGE || '${env:STAGE}'}`,
        event: 's3:ObjectCreated:*',
        existing: true,
        rules: [{ suffix: '.jpg' }],
        forceDeploy: true, // Used to force cloudformation to update the trigger no matter what
      }
    }
  ]

The reference to the bucket is saved in an environment variable for easier management across different stages and deployments.

In the Lambda code, the following bullet points are needed to complete the analysis:

• Download the screenshot from S3

• Identify each face that’s in the screenshot, along with bounding borders and emotions of each face

• Use the “sharp” npm package to extract and save each individual face as its own image

• Upload each cropped face into another S3 bucket for future reference

• Save the results into a DynamoDB Table for other consumers to use

The following code snippet shows the Lambda handler processor, which orchestrates those tasks:

const processEvent = async (eventRecord: S3EventRecord): Promise => {
  const {
    bucket: { name: imageBucketName },
    object: { key: imageObjectKey },
  } = eventRecord.s3
  try {
    const faceAnalysisResults = await AttentionService.analyzeImage(imageObjectKey)
    const { Body, Metadata: screenshotMetadata } = await aws.s3.getObject(imageBucketName, imageObjectKey)
    const {
      classid: classId,
      classstarteddatetimestamp: classStartedDateTimestamp,
      screenshottime: screenshotTime,
      screenshotbasepath: screenshotBasePath,
    } = screenshotMetadata


    const completeFaceAnalysisResults = await extractFaces(faceAnalysisResults, Body as Readable, screenshotTime, classId)


    await AttentionService.publishResults(
      completeFaceAnalysisResults,
      classId,
      classStartedDateTimestamp,
      screenshotTime,
      screenshotBasePath,
      imageObjectKey
    )
  }
  catch (ex) {
    console.error('Error processing s3 event record', inspect(eventRecord))
  }
}

When analyzing the image, we use AWS Rekognition to detect faces and get the levels of emotions per face, as shown in the code snippet below. Note that to calculate the attention level of a face, we use the emotions detected by AWS Rekognition (which gets calculated using the formula explained in the above sections).

const analyzeImage = async (s3ObjectKey: string): Promise => {
  try {
    const results = await aws.rekognition.detectFaces(BUCKET_NAME, s3ObjectKey)
    const createdAt = getTimestamp()
    return results.FaceDetails
      // .filter(face => shouldDiscardReading(face)) // (TODO): uncomment this line to discard faces with low confidence
      .map((face, i) => ({
        ...face,
        index: i + 1,
        analysisCreatedAt: createdAt,
        Landmarks: undefined,
        attentionLevel: roundNum(calculateAttentionLevel(face.Emotions) * 100, 2), // convert to percentage
        isUncertainAnalysis: isUncertainAnalysis(face.Emotions),
      }))
  }
  catch (ex) {
    console.error('Error calculating screenshot raw attention', ex, s3ObjectKey)
  }
}

For extracting the faces and cropping them, we use the “sharp” npm package, which has an easy-to-use API for this kind of operation (as long as we have the “bounding box” from the AWS Rekognition analysis results) as shown in the code snippet below:

const { BoundingBox } = faceAnalysisResult;
const screenshot = await streamToBuffer(screenshotStream);
const {
  height: screenshotHeight,
  width: screenshotWidth,
} = await sharp(screenshot).metadata();


const faceHeight = Math.round(BoundingBox.Height * screenshotHeight) + (pixelsOffset * 2);
const faceWidth = Math.round(BoundingBox.Width * screenshotWidth) + (pixelsOffset * 2);
const faceTop = Math.round(BoundingBox.Top * screenshotHeight) - pixelsOffset;
const faceLeft = Math.round(BoundingBox.Left * screenshotWidth) - pixelsOffset;


// Limits the face extraction to the screenshot size
const height = faceHeight > screenshotHeight ? screenshotHeight : faceHeight;
const width = faceWidth > screenshotWidth ? screenshotWidth : faceWidth;
const top = faceTop <= 0 ? screenshotHeight : faceTop;
const left = faceLeft <= 0 ? screenshotWidth : faceLeft;
// Extracts the face from the screenshot
const faceBuffer = await sharp(screenshot).extract({
  height,
  width,
  top,
  left,
}).toBuffer();
return faceBuffer;

(Full code repo can be found in the References section at the end of the article)

Future Work

While this article gave an overview of the solution as a whole, it only delved into the “screenshot analyzer” section. In future articles, we will explore other components, especially the “Teacher recommender” system, which provides tailored activity suggestions based on the data that was collected by the screenshot analysis.

Stay tuned for future updates where we will dive deeper into these components!

Conclusion

In this article, we covered a “learning recommendation system”, which aims to improve the challenge of measuring and enhancing student engagement in virtual learning environments. By using the machine learning capabilities built into AWS Rekognition, we can detect and extract the faces of students in a virtual classroom, then analyze them and save them for future use by a teacher recommender app for tailor-made recommendations that aim to improve the learning experience.

Using serverless architecture, we designed an effective and efficient system that accomplishes the goal of analyzing and calculating student engagement in a virtual classroom.

Stay tuned for the teacher recommender system in a future article!

References

• Paper for calculating attention level:

  • Tabassum, T., Allen, A. A., & De, P. (2020). Non-intrusive Identification of Student Attentiveness and Finding Their Correlation with Detectable Facial Emotions. ACM Southeast Conference - ACMSE 2020 - Session 1, 127-134.

• AWS Rekognition “Detect Faces” Documentation:

  • https://docs.aws.amazon.com/rekognition/latest/dg/faces.html

  • https://docs.aws.amazon.com/rekognition/latest/dg/faces-detect-images.html

  • https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DetectFaces.html

• Screenshot App Full Code: https://github.com/LucasVera/eafit-screenshot-app

• Screenshot Analyzer Full Code: https://github.com/LucasVera/screenshot-analyzer

• Link to my master’s Thesis (Spanish): https://repository.eafit.edu.co/items/191b580f-8415-489e-a5a5-e42776712258

Introduction

In a typical e-commerce application, a user browses through a catalog of products, chooses some products, and then proceeds to checkout. In the checkout process, the user needs to pay for the selected products. Once the payment process is completed, some post-payment activities need to be executed in order to process the order and the products that the user paid for.

These “post-payment” activities usually refer to tasks that may need to be performed in a particular sequence, but at the same time, some other tasks may be performed in parallel. There is also the need to do error handling.

For this use case, a powerful pattern is to use an orchestrator service that handles all the activities in a streamlined way. Using AWS Step Functions is a great way to orchestrate these tasks.

Let’s dive into an example use case, along with some high-level requirements, and showcase a couple of features and a combination of services.

Requirements

Let’s imagine a typical e-commerce application, where a user can browse through different products, add them to some sort of “shopping basket” and then, once it’s satisfied, can continue with the payment process. After the payment process is done, there are some activities that the e-commerce system must perform, like updating the inventory of the products, sending an order with enough details to a fulfillment center, sending the customer a notification with order details, arrival date, etc. This article will focus on the “post-payment” activities, which, in a typical e-commerce site, come after the payment process is finished. The following is a sample of what some requirements could look like for building such an “feature”:

• After the user finishes payment, a “post-payment activities” process must be triggered

• The “post-payment activities” process should do the following:

  • Verify that payment was completed successfully

    • If payment was not completed successfully, send a general error notification to the user and don’t continue with the rest of the flow

  • Upon successful payment verification, initiate the following tasks in parallel for order processing. Products need to be grouped by fulfillment center and then, for each product group, do the following:

    • Update inventory system

    • Send order details to the fulfillment center

  • After both tasks are completed, perform the following tasks:

    • Send a confirmation email to the customer with details about the order, arrival date, etc

    • Update the customer’s order history with the new order

  • Each step must handle errors gracefully. If an error happens in one of the tasks:

    • Log the error for manual review and send a notification email to the customer support team

A high-level diagram of the system is shown below:

High-level overview of a typical e-commerce application, expanding on the post-payment activities

Notice that the image only shows the functional tasks. Other tasks like error handling are technical aspects that need to be taken into account in the solution.

The Solution

The solution to meet the requirements should involve a way to sequence different separate processes. Looking at the requirements, we can simplify the solution to a system that is capable of sequencing the different tasks in a particular order, while at the same time handling parallel steps and error handling. In this case, a simplified flowchart of the solution could look like the following image

Post-Payment Activities Flow chart describing a streamlined way to meet requirements of a typical e-commerce application

As we can see in the flowchart image, the post-payment activities can be arranged in a specific sequence, with error handling in between steps. We can also leverage parallel processing where we can in a way that makes sense and also follows the requirements. Notice also that this flowchart is agnostic of underlying technology/service. While this article wants to highlight the benefits of step functions, while making an architecture decision it’s important to consider other solutions and proposals. Let’s take a look at two possible solutions involving two different patterns, along with its pros and cons:

Orchestrator Pattern

An “Orchestrator” is a central control unit which is responsible for sequencing different processes. Much like the conductor in an orchestra, it dictates the flow of operations and ensures that each piece plays at the correct time. The “orchestrator” is responsible for initiating processes, coordinating inter-process communication, handling failures and ensuring the workflow goes smoothly. This creates a system that allows for easier monitoring and managing complex workflows

Choreographer Pattern

The “Choreographer” is a decentralization pattern. There is no single entity which controls the sequence of the processes. Instead, each individual process knows which other process is next for execution after its own completion, and when to do so. This is accomplished by writing and reading messages. Each process emits messages after finishing, which gets picked up by other processes. This creates a loosely coupled system where individual processes only need to understand messages they care about.

Comparison

While both patterns can help build a system that handles the requirements, choosing the orchestrator pattern offers a centralized way to handle processes, allowing easier error handling and even recovery if needed. Monitoring and observability are also simplified, which facilitates troubleshooting.

AWS Step Functions

AWS Step Functions is a serverless orchestrator service that streamlines a particular workflow into a set of states. It excels in handling complex workflows that have multiple steps and sequencing those steps. At the same time, it’s great for handling errors, parallel processing, and integrating with other AWS services. One great benefit of it is its ability to visually represent and edit the workflow through the aws console, which also lets you execute it and see each step’s inputs and outputs clearly.

Given the nature of the requirements of implementing the logic for completing the tasks in a particular sequence, and the requirement to handle errors, choosing AWS Step Functions to act as an orchestrator is a natural solution.

Building this solution using AWS Step Functions is possible through the AWS console. While it’s a great tool to visually build the step function workflow and execute it to debug it, it can also help in exporting the JSON that corresponds to the workflow steps and configuration. This way it’s possible to paste the JSON in a Cloudformation template to deploy the step function through Infrastructure as Code tools like CloudFormation.

Assumptions

In order to keep this article from getting too complex, let’s make a couple of assumptions regarding the following points:

• How the data looks after finishing the payment process

• How data is related between the customer’s chosen products, payment and the input to start the post-payment activities

• Simplify inventory management to a DynamoDB update

• Simplify how to send products to fulfillment centers (invoke a Lambda function)

• Simplify how to send notifications to customers (send a message to an SNS topic)

• Simplify how to send notifications to the customer support team (send a message to an SNS topic)

With this in mind, let’s explore a bit on how the data looks like before jumping into the actual implementation.

Customer Session

In order to simplify the way the data is handled, let’s make the following simplified data modeling in order to cover the customer’s chosen products and payment status. Before sending for payment, let’s imagine a “session” gets generated. This session contains the following information:

• Chosen products

• Payment Status

Let’s also assume that this data gets stored in a simple DynamoDb Table that uses a SessionId (uuid) as the primary key to identify the payment session of each customer. Some sample data modeling might look like the following:

Table name: CustomerPaymentSession

• SessionId (PK): String

• CustomerId: String

• PaymentStatus: String

• Products: List

Let’s also make an assumption that each product has the following structure:

• fulfillmentCenterId: String

• id: String

• name: String

• price: Number

• quantity: Number

As so, an example of a “customer session” may look like the following:

{
  "SessionId": "a48eb859-c71e-4566-9b05-d8e5e46d8a25",
  "CustomerId": "123",
  "PaymentStatus": "Success",
  "Products": [
    {
      "fulfillmentCenterId": "300aa993-ef76-4ff4-87f6-cb57380057aa",
      "id": "587a2bd7-000d-4f28-b240-d7b57473ecbd",
      "name": "T-Shirt",
      "price": 10,
      "quantity": 5
    },
    {
      "fulfillmentCenterId": "300aa993-ef76-4ff4-87f6-cb57380057aa",
      "id": "9f44cb7f-6c60-4f30-87ca-081206d3a6a2",
      "name": "Pants",
      "price": 15,
      "quantity": 2
    },
    {
      "fulfillmentCenterId": "55ca7c2b-8b00-4419-98d7-f4f959464c97",
      "id": "21a90825-3c6d-4121-9be6-8aa10b72b60d",
      "name": "Shoes",
      "price": 18,
      "quantity": 7
    }
  ]
}

‍Sample Implementation

When using the AWS console and the workflow studio, we can do a simple implementation. With the help of the assumptions and the previous analysis, the result would look like the following:

Visual representation of the step function in the aws console

Let’s zoom in to cover each part and explain more clearly:

Data Flow

Zoom-in to the first three steps of the step function workflow

Here we have the start of the step function workflow, the verification of the payment status and a Lambda function that fetches and groups products to continue with the flow.

1. In the first step, we get the input used to invoke the step function. According to the assumptions and the simplified data model, the step function should be initiated with the SessionId parameter, as is the primary key to the “CustomerPaymentSession” DynamoDb Table, which holds the customer’s products and payment result:

{
    "SessionId": "a48eb859-c71e-4566-9b05-d8e5e46d8a25"
}

With this input, we can fetch the payment record with the given SessionId and check if payment was executed successfully. The most suited dynamodb operation in this case is a “GetItem”, which is declared and configured in the step function itself:

{
    "TableName": "post-payment-records",
    "Key": {
        "SessionId": {
            "S.$": "$.SessionId"
        }
    }
}

Notice the usage of $. When referencing a value in the input, we use the $ at the end of the field name, then the value starts with the sign followed by the field name we want to reference. In this case, the input contains SessionId, so we reference it using $.SessionId. Similarly, we can map the output of the DynamoDB operation using the Step Functions “Transform result” feature, which lets us reference values in the result and map them in a way that makes sense. In this case, we can configure the following mapping:

{
"SessionId.$": "$.Item.SessionId.S",
"PaymentStatus.$": "$.Item.PaymentStatus.S",
"CustomerId.$": "$.Item.CustomerId.S",
"Products.$": "$.Item.Products.L"
}

‍An example output of this step would be the following:

{
  "Products": [
    {
      "M": {
        "quantity": {
          "N": "5"
        },
        "fulfillmentCenterId": {
          "S": "300aa993-ef76-4ff4-87f6-cb57380057aa"
        },
        "price": {
          "N": "10"
        },
        "name": {
          "S": "T-Shirt"
        },
        "id": {
          "S": "587a2bd7-000d-4f28-b240-d7b57473ecbd"
        }
      }
    },
    {
      "M": {
        "quantity": {
          "N": "2"
        },
        "fulfillmentCenterId": {
          "S": "300aa993-ef76-4ff4-87f6-cb57380057aa"
        },
        "price": {
          "N": "15"
        },
        "name": {
          "S": "Pants"
        },
        "id": {
          "S": "9f44cb7f-6c60-4f30-87ca-081206d3a6a2"
        }
      }
    },
    {
      "M": {
        "quantity": {
          "N": "7"
        },
        "fulfillmentCenterId": {
          "S": "55ca7c2b-8b00-4419-98d7-f4f959464c97"
        },
        "price": {
          "N": "18"
        },
        "name": {
          "S": "Shoes"
        },
        "id": {
          "S": "21a90825-3c6d-4121-9be6-8aa10b72b60d"
        }
      }
    }
  ],
  "CustomerId": "123",
  "SessionId": "a48eb859-c71e-4566-9b05-d8e5e46d8a25",
  "PaymentStatus": "Success"
}

‍2. In this step, we need to verify the payment status given by DynamoDB in the previous step. We can make use of a “Choice State” from Step Functions, which takes an input and evaluates it against certain conditions to determine the next step. For our use case, we only care that PaymentStatus is exactly Success. We can do so like in the Step Functions configuration shown below:

Condition to check if payment was successful using a step function’s “choice” step

3. For Step 3, We need to fetch and group products so that they can be processed in groups and can be sent to fulfillment center in groups. As shown in previous steps, the data for each product has a fulfillmentCenterId. For simplicity of this article, let’s imagine a Lambda function takes care of this task, and returns the grouped products by fulfillmentCenterId, as shown below:

[
  {
    "fulfillmentCenterId": "300aa993-ef76-4ff4-87f6-cb57380057aa",
    "products": [
      {
        "fulfillmentCenterId": "300aa993-ef76-4ff4-87f6-cb57380057aa",
        "id": "587a2bd7-000d-4f28-b240-d7b57473ecbd",
        "name": "T-Shirt",
        "price": "10",
        "quantity": "5"
      },
      {
        "fulfillmentCenterId": "300aa993-ef76-4ff4-87f6-cb57380057aa",
        "id": "9f44cb7f-6c60-4f30-87ca-081206d3a6a2",
        "name": "Pants",
        "price": "15",
        "quantity": "2"
      }
    ]
  },
  {
    "fulfillmentCenterId": "55ca7c2b-8b00-4419-98d7-f4f959464c97",
    "products": [
      {
        "fulfillmentCenterId": "55ca7c2b-8b00-4419-98d7-f4f959464c97",
        "id": "21a90825-3c6d-4121-9be6-8aa10b72b60d",
        "name": "Shoes",
        "price": "18",
        "quantity": "7"
      }
    ]
  }
]

Zoom-in of the step function, to show a “Parallel step” within a “Map step”

4. Step 4 receives the grouped products array as input. Since we need to loop through each product group, we can use the Step Function’s “Map state” to do so. We just specify the path of the array to loop and it will run what’s inside the box for each entry in the array.

5. For each product group, we need to perform two tasks: update product inventory and send to fulfillment center for further processing. We can leverage the usage of a “Parallel State” to complete these tasks in parallel, this way the tasks take less time to complete than if they were sequential. For simplicity of the article, we’ll not jump into details on how each task is done.

Zoom-in of the next portion of the step function, which shows the next set of tasks and the end of the execution

6. After each product group finishes executing each task successfully, it means all inventories were updated successfully and products sent to their respective fulfillment centers. So in this case, we can proceed to perform two tasks: send a “success” notification to the customer and update the order history. Again, we can leverage the usage of a “Parallel Step” to execute both tasks in parallel. For simplicity’s sake, I will not go into detail of each step.

7. After the notification is sent and the history is updated, we are done! We can end the execution of the step function there.

Zoom-in to show the error scenarios in the step function

3.E, 6.E, 7.E (Error Scenarios): Notice that so far we have covered the “happy path”, where all individual steps succeed. But this is not always the case, as things can fail for a number of reasons. For example, the payment of the user may not have completed successfully, maybe the products couldn’t be sent to the fulfillment centers or maybe the success notification couldn’t be sent. In any case, the requirement is to handle these error scenarios.

With Step Functions, we can set a “catch” configuration. In that catch we can specify which kind of errors we want to capture and where the Step Functions route the error scenarios. So in this case, we can set a simple catch that routes failures to the “Send Notification to Support Team” SNS topic, so that the customer support team can get notifications on failures and take appropriate action:

Configuration of the “Catch” handlers in steps

To handle “non-success” payments in the customer session, we can define a default rule in the “Choice Step” for Step 2. This allows us to define where to go if the rest of the choices are not evaluated as true, as shown in the image below:

Configuration of the step function “choice” state for default rule

Conclusion

In summary, this article outlines a streamlined approach for automating post-payment activities through AWS Step Functions, emphasizing the orchestration of tasks, parallel processing, and error management. By comparing orchestrator and choreographer patterns, it highlights the effectiveness of a centralized orchestration model, implemented in a practical AWS Step Functions workflow. This solution not only meets the requirements of post-payment processing of a typical e-commerce application, but also offers scalability, reliability, and seamless integration with AWS services, presenting a forward-looking framework for handling complex workflows in cloud environments.

References

• https://aws.amazon.com/step-functions/

• https://aws.amazon.com/blogs/compute/orchestrating-dependent-file-uploads-with-aws-step-functions/

• https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html

• https://camunda.com/blog/2023/02/orchestration-vs-choreography/

• https://docs.aws.amazon.com/lambda/latest/dg/services-stepfunctions.html