DEV Community: Jacek Kościesza

Videos GraphQL API with AppSync, Lambda, DynamoDB - FakeTube #6

Jacek Kościesza — Thu, 02 Oct 2025 08:23:19 +0000

In the last episode, we established a solid backend foundation using a traditional REST API with API Gateway, Lambda, and an Aurora Serverless PostgreSQL database. This approach works well, but in the world of modern cloud-native architectures, we often explore alternative patterns to address different needs, especially regarding data fetching efficiency and flexibility.

This time, we're shifting our focus to a modern approach using a GraphQL-based API with AWS AppSync and a NoSQL database, Amazon DynamoDB. This will allow us to compare the database modeling process, performance, and scalability of both solutions. We'll continue to leverage Infrastructure as Code (IaC) with the AWS Cloud Development Kit (CDK) to define and deploy our resources.

Our high-level architecture diagram will now evolve to incorporate these new GraphQL components - AppSync, DynamoDB and (optional) Lambda function.

The sequence diagram is worth a thousand words. This high level diagram shows two variants of our architecture:

1) Lambda resolver as an intermediary between AppSync and DynamoDB

First it runs DynamoDB Query command to get a paginated list of videos sorted by publishedAt and then runs BatchGetItem query to get channels for those videos and merges the two results.

2) DynamoDB resolver to directly integrate AppSync with DynamoDB

First it queries DynamoDB for the paginated list of videos sorted by publishedAt and then it uses a field-level resolver to get the channel for each video.

We will discuss, implement and compare both variants.

Let's dive in!

Database

For this iteration, we're moving to a NoSQL database and our solution of choice will be Amazon DynamoDB a key-value database designed for high performance or as AWS put it in the tagline:

Serverless, fully managed, distributed NoSQL database with single-digit millisecond performance at any scale

Before we can store any data, we need a "blueprint". Just as we defined our relational schema with an ERD (Entity Relationship Diagram) and DDL (Data Definition Language) statements previously, we must now design a schema tailored for our NoSQL database.

Schema

Unlike the rigid structure of relational databases with predefined tables and relationships, NoSQL databases like DynamoDB offer a more flexible model.

Single table design

One of the most powerful and initially counterintuitive concepts in DynamoDB is single-table design. While our relational background taught us to normalize data into separate tables (like videos and channels), with this approach, we'll store different types of items within a single table.

DynamoDB does not support the complex join operations that are fundamental to relational databases like PostgreSQL. This absence of joins is a key motivator for the single-table design pattern.

By leveraging generic primary keys like PK (Partition Key), SK (Sort Key) and additional indexes like GSI (Global Secondary Indexes) or LSI (Local Secondary Indexes), we can efficiently model relationships between data and create highly performant queries.

I highly recommend watching Fundamentals of Amazon DynamoDB Single Table Design with Rick Houlihan to better understand the modelling process.

ERD (Entity Relationship Diagram)

As a first step, let's visualize our (super simple) ERD diagram and the relationship between videos and channels using Mermaid ERD (Entity Relationship Diagram)

cloud/lib/dynamodb-erd.md

erDiagram
    channel {        
    }

    video {        
    }

    channel ||--o{ video : "has many"

Access patterns

Now, let's try to identify all the access patterns for the Home page feature (plus let's think also about the incoming Watch page feature).

Identified Access Patterns	Feature
Get all videos sorted by `publishedAt`	Home page
Get channel by `channelId`	Home page
Get video by `videoId`	Watch page

Let's also go through all those access patterns and think which Table, GSI (Global Secondary Index) or LSI (Local Secondary Index) we have to query to get a given result. What are the key conditions or filter expressions needed?

Access Pattern	Table/GSI/LSI	Key Condition
Get all videos sorted by `publishedAt`	GSI1	GSI1_PK="video"
Get channel by `channelId`	Table	PK=channelId and SK=channelId Example PK="c#AmazonNovaReel" and SK="c#AmazonNovaReel"
Get video by `videoId`	Table	PK=videoId and SK=videoId Example PK="v#q9Gm7a6Wwjk" and SK="v#q9Gm7a6Wwjk"

NoSQL Workbench

Let's create the data model in NoSQL Workbench for DynamoDB - cross-platform GUI application that you can use for modern database development and operations.

Data model

Click "Create new data model" from the "Getting started" section on the top-right. Click "Select" from the "Make model from scratch" section on the left. Fill out the form like this:

Field	Value
Name	FakeTube
Author	Jacek Kościesza
Description	YouTube clone

and finally click the "Create" button.

DynamoDB table

Now let's create a DynamoDB table. Click the "Create new table" button from the "No table selected" section located in the centre.

Complete the form as follows:


Table name	FakeTube

In the "Primary key attributes" section check "Add sort key" option and define both - partition and sort keys:


Partition key	PK	String
Sort key	SK	String

In the "Other attributes" click "Add an attribute" button and create all the needed attributes:

Attribute name	Attribute type
GSI1_PK	String
GSI1_SK	String
EntityType	String
id	String
avatar	String
name	String
title	String
thumbnail	String
duration	String
url	String
publishedAt	String
channelId	String

In the "Global secondary indexes" section click "Add global secondary index", check "Add sort key" option and fill the form like this:


Global secondary index name	GSI1
Partition key	GSI1_PK
Sort key	GSI1_SK
Projection type	ALL

Finally click the "Add table definition" button.

Here's that exported data model after those steps:

cloud/lib/NoSQL_Workbench_model_#1.json

{
  "ModelName": "FakeTube",
  "ModelMetadata": {
    "Author": "Jacek Kościesza",
    "DateCreated": "Sep 23, 2025, 06:15 PM",
    "DateLastModified": "Sep 23, 2025, 06:28 PM",
    "Description": "YouTube clone",
    "AWSService": "Amazon DynamoDB",
    "Version": "3.0"
  },
  "DataModel": [
    {
      "TableName": "FakeTube",
      "KeyAttributes": {
        "PartitionKey": {
          "AttributeName": "PK",
          "AttributeType": "S"
        },
        "SortKey": {
          "AttributeName": "SK",
          "AttributeType": "S"
        }
      },
      "NonKeyAttributes": [
        {
          "AttributeName": "GSI1_PK",
          "AttributeType": "S"
        },
        {
          "AttributeName": "GSI1_SK",
          "AttributeType": "S"
        },
        {
          "AttributeName": "EntityType",
          "AttributeType": "S"
        },
        {
          "AttributeName": "id",
          "AttributeType": "S"
        },
        {
          "AttributeName": "avatar",
          "AttributeType": "S"
        },
        {
          "AttributeName": "name",
          "AttributeType": "S"
        },
        {
          "AttributeName": "title",
          "AttributeType": "S"
        },
        {
          "AttributeName": "thumbnail",
          "AttributeType": "S"
        },
        {
          "AttributeName": "duration",
          "AttributeType": "S"
        },
        {
          "AttributeName": "url",
          "AttributeType": "S"
        },
        {
          "AttributeName": "publishedAt",
          "AttributeType": "S"
        },
        {
          "AttributeName": "channelId",
          "AttributeType": "S"
        }
      ],
      "GlobalSecondaryIndexes": [
        {
          "IndexName": "GSI1",
          "KeyAttributes": {
            "PartitionKey": {
              "AttributeName": "GSI1_PK",
              "AttributeType": "S"
            },
            "SortKey": {
              "AttributeName": "GSI1_SK",
              "AttributeType": "S"
            }
          },
          "Projection": {
            "ProjectionType": "ALL"
          }
        }
      ],
      "DataAccess": {
        "MySql": {}
      },
      "SampleDataFormats": {},
      "BillingMode": "PAY_PER_REQUEST"
    }
  ]
}

Data

Now let's add some data. Click the "Visualizer" tab in the side menu, then click the "Actions" button in the top-right corner and select the "Edit data" option.

We will start with minimalistic example with only one channel and one video:

Attribute name	Attribute value
PK	c#AmazonNovaReel
SK	c#AmazonNovaReel
EntityType	channel
id	AmazonNovaReel
avatar	/channels/AmazonNovaReel/AmazonNovaReel.png
name	Amazon Nova Reel

Attribute name	Attribute value
PK	v#q9Gm7a6Wwjk
SK	v#q9Gm7a6Wwjk
GSI1_PK	video
GSI1_SK	2025-03-03T15:58:23Z
EntityType	video
title	The Amazing World of Octopus!
thumbnail	/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png
duration	/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.mp4
publishedAt	2025-03-03T15:58:23Z
channelId	AmazonNovaReel

Here's how our exported data model changed after those steps:

cloud/lib/NoSQL_Workbench_model_#2.json (diff)

...
      "GlobalSecondaryIndexes": [
        {
          "IndexName": "GSI1",
          "KeyAttributes": {
            "PartitionKey": {
              "AttributeName": "GSI1_PK",
              "AttributeType": "S"
            },
            "SortKey": {
              "AttributeName": "GSI1_SK",
              "AttributeType": "S"
            }
          },
          "Projection": {
            "ProjectionType": "ALL"
          }
        }
      ],
+     "TableData": [
+       {
+         "PK": {
+           "S": "c#AmazonNovaReel"
+         },
+         "SK": {
+           "S": "c#AmazonNovaReel"
+         },
+         "EntityType": {
+           "S": "channel"
+         },
+         "id": {
+           "S": "AmazonNovaReel"
+         },
+         "avatar": {
+           "S": "/channels/AmazonNovaReel/AmazonNovaReel.png"
+         },
+         "name": {
+           "S": "Amazon Nova Reel"
+         }
+       },
+       {
+         "PK": {
+           "S": "v#q9Gm7a6Wwjk"
+         },
+         "SK": {
+           "S": "v#q9Gm7a6Wwjk"
+         },
+         "GSI1_PK": {
+           "S": "video"
+         },
+         "GSI1_SK": {
+           "S": "2025-03-03T15:58:23Z"
+         },
+         "EntityType": {
+           "S": "video"
+         },
+         "id": {
+           "S": "q9Gm7a6Wwjk"
+         },
+         "title": {
+           "S": "The Amazing World of Octopus!"
+         },
+         "thumbnail": {
+           "S": "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png"
+         },
+         "duration": {
+           "S": "PT0M6.214542S"
+         },
+         "url": {
+           "S": "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.mp4"
+         },
+         "publishedAt": {
+           "S": "2025-03-03T15:58:23Z"
+         },
+         "channelId": {
+           "S": "AmazonNovaReel"
+         }
+       }
+     ],
      "DataAccess": {
        "MySql": {}
      },
      "SampleDataFormats": {},
      "BillingMode": "PAY_PER_REQUEST"
    }
  ]
}

Finally, let's add the rest of our videos. You can find the final JSON file with the exported data model here:

cloud/lib/NoSQL_Workbench_model_#3.json

GitHub: feat(home): nosql workbench model (#7)

DynamoDB

Moving on, let's translate all of that to the AWS CDK construct.

cloud/lib/dynamodb.ts

import * as cdk from "aws-cdk-lib";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import { Construct } from "constructs";

export class DynamoDB extends Construct {
  public table: dynamodb.Table;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.table = new dynamodb.Table(this, "dynamodb-table", {
      tableName: "FakeTube",
      partitionKey: {
        name: "PK",
        type: dynamodb.AttributeType.STRING,
      },
      sortKey: {
        name: "SK",
        type: dynamodb.AttributeType.STRING,
      },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    this.table.addGlobalSecondaryIndex({
      partitionKey: { name: "GSI1_PK", type: dynamodb.AttributeType.STRING },
      indexName: "GSI1",
      sortKey: { name: "GSI1_SK", type: dynamodb.AttributeType.STRING },
      projectionType: dynamodb.ProjectionType.ALL,
    });

    new cdk.CfnOutput(this, "DynamoDBTableExport", {
      value: this.table.tableName,
    });
  }
}

It's worth noting two options, which we didn't discuss in NoSQL Workbench section.

billingMode: Set to PAY_PER_REQUEST, which is a flexible billing option capable of serving requests without capacity planning.
removalPolicy: Set to DESTROY, which will delete the table during stack deletion. WARNING: this is fine for development environment, but for production environment we will have to change it to RETAIN or SNAPSHOT

Stack

Now, let's deploy the stack with our DynamoDB table.

cloud/lib/faketube-stack.ts (diff)

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { Aurora } from "./aurora";
+import { DynamoDB } from "./dynamodb";
import { Gateway } from "./gateway";
import { Home } from "./home";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
    const aurora = new Aurora(this, "aurora", { vpc });
+   new DynamoDB(this, "dynamodb");
    const gateway = new Gateway(this, "gateway");

    new Home(this, "home", {
      aurora,
      gateway,
    });
  }
}

cloud/lib/faketube-stack.ts

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { Aurora } from "./aurora";
import { DynamoDB } from "./dynamodb";
import { Gateway } from "./gateway";
import { Home } from "./home";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
    const aurora = new Aurora(this, "aurora", { vpc });
    new DynamoDB(this, "dynamodb");
    const gateway = new Gateway(this, "gateway");

    new Home(this, "home", {
      aurora,
      gateway,
    });
  }
}

Just a final check with cdk diff what will be created:

and we can run cdk deploy.

GitHub: feat(home): dynamodb (#7)

Seed

To seed our database with data we will use AWS CLI and batch-write-item command.

Channels

Let's start with channels. We will first prepare JSON file with PutRequest commands:

cloud/lib/channels.seed.json

{
  "FakeTube": [
    {
      "PutRequest": {
        "Item": {
          "PK": {
            "S": "c#AmazonNovaReel"
          },
          "SK": {
            "S": "c#AmazonNovaReel"
          },
          "EntityType": {
            "S": "channel"
          },
          "id": {
            "S": "AmazonNovaReel"
          },
          "avatar": {
            "S": "/channels/AmazonNovaReel/AmazonNovaReel.png"
          },
          "name": {
            "S": "Amazon Nova Reel"
          }
        }
      }
    }
  ]
}

and we are ready to invoke batch-write-item command:

aws dynamodb batch-write-item --request-items file://lib/channels.seed.json

{
    "UnprocessedItems": {}
}

Tye UnprocessedItems object is empty, which means that everything was processed successfully.

Videos

Next, videos data. We can't put everything into one big JSON file. We will have to divide it into maximum 25 command chunks, otherwise we will get an error like this:

failed to satisfy constraint: Map value must satisfy constraint: [Member must have length less than or equal to 25, Member must have length greater than or equal to 1]

So, let's create two separate files, first one with 25 commands, second one with 7 commands, which gives our 32 videos in total from the initial video set prepared earlier.

cloud/lib/videos_#1.seed.json

{
  "FakeTube": [
    {
      "PutRequest": {
        "Item": {
          "PK": {
            "S": "v#q9Gm7a6Wwjk"
          },
          "SK": {
            "S": "v#q9Gm7a6Wwjk"
          },
          "GSI1_PK": {
            "S": "video"
          },
          "GSI1_SK": {
            "S": "2025-03-03T15:58:23Z"
          },
          "EntityType": {
            "S": "video"
          },
          "id": {
            "S": "q9Gm7a6Wwjk"
          },
          "title": {
            "S": "The Amazing World of Octopus!"
          },
          "thumbnail": {
            "S": "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png"
          },
          "duration": {
            "S": "PT0M6.214542S"
          },
          "url": {
            "S": "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.mp4"
          },
          "publishedAt": {
            "S": "2025-03-03T15:58:23Z"
          },
          "channelId": {
            "S": "AmazonNovaReel"
          }
        }
      }
    },
    {
      "PutRequest": {
        "Item": {
          "PK": {
            "S": "v#QYUGZ3ueoHQ"
          },
          "SK": {
            "S": "v#QYUGZ3ueoHQ"
          },
          "GSI1_PK": {
            "S": "video"
          },
          "GSI1_SK": {
            "S": "2025-03-03T14:22:54Z"
          },
          "EntityType": {
            "S": "video"
          },
          "id": {
            "S": "QYUGZ3ueoHQ"
          },
          "title": {
            "S": "Magic Wheels: The Future of Cars"
          },
          "thumbnail": {
            "S": "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.png"
          },
          "duration": {
            "S": "PT0M6.047708S"
          },
          "url": {
            "S": "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.mp4"
          },
          "publishedAt": {
            "S": "2025-03-03T14:22:54Z"
          },
          "channelId": {
            "S": "AmazonNovaReel"
          }
        }
      }
    },
    ... (23 more)
  ]
}

cloud/lib/videos_#2.seed.json

{
  "FakeTube": [
    {
      "PutRequest": {
        "Item": {
          "PK": {
            "S": "v#SJOCLMEuoh0"
          },
          "SK": {
            "S": "v#SJOCLMEuoh0"
          },
          "GSI1_PK": {
            "S": "video"
          },
          "GSI1_SK": {
            "S": "2025-03-07T14:20:26Z"
          },
          "EntityType": {
            "S": "video"
          },
          "id": {
            "S": "SJOCLMEuoh0"
          },
          "title": {
            "S": "Tree Guardians: Protecting Nature's Champions"
          },
          "thumbnail": {
            "S": "/videos/SJOCLMEuoh0/SJOCLMEuoh0.png"
          },
          "duration": {
            "S": "PT0M6.047708S"
          },
          "url": {
            "S": "/videos/SJOCLMEuoh0/SJOCLMEuoh0.mp4"
          },
          "publishedAt": {
            "S": "2025-03-07T14:20:26Z"
          },
          "channelId": {
            "S": "AmazonNovaReel"
          }
        }
      }
    },
    {
      "PutRequest": {
        "Item": {
          "PK": {
            "S": "v#M8V1FcKde2g"
          },
          "SK": {
            "S": "v#M8V1FcKde2g"
          },
          "GSI1_PK": {
            "S": "video"
          },
          "GSI1_SK": {
            "S": "2025-03-07T14:36:03Z"
          },
          "EntityType": {
            "S": "video"
          },
          "id": {
            "S": "M8V1FcKde2g"
          },
          "title": {
            "S": "Street Volunteers: Collecting for a Cause"
          },
          "thumbnail": {
            "S": "/videos/M8V1FcKde2g/M8V1FcKde2g.png"
          },
          "duration": {
            "S": "PT0M6.047708S"
          },
          "url": {
            "S": "/videos/M8V1FcKde2g/M8V1FcKde2g.mp4"
          },
          "publishedAt": {
            "S": "2025-03-07T14:36:03Z"
          },
          "channelId": {
            "S": "AmazonNovaReel"
          }
        }
      }
    },
    ... (5 more)
  ]
}

Let's invoke batch-write-item commands:

aws dynamodb batch-write-item --request-items file://lib/videos_#1.seed.json

{
    "UnprocessedItems": {}
}

aws dynamodb batch-write-item --request-items file://lib/videos_#2.seed.json

{
    "UnprocessedItems": {}
}

Seems that it all worked. We can verify it using AWS Console and Explore table items feature:

GitHub: feat(home): dynamodb seed (#7)

API

This time, we're building our API with GraphQL instead of the traditional REST API. But why?

GraphQL is an open-source query language for APIs and a server-side runtime created by Facebook, open-sourced about 10 years ago. Since then, its adoption and ecosystem have grown immensely. A key difference is that with GraphQL, the client requests exactly the data it needs, solving the common REST problems of over-fetching (getting too much data) and under-fetching (needing multiple requests).

For this project, we'll use AWS AppSync, a dedicated service on Amazon Web Services that simplifies building a GraphQL API.

Key characteristics of GraphQL:

Product-centric: Designed to meet the needs of the client.
Hierarchical: Data is structured intuitively, reflecting its relationships.
Strong-typing: All data is defined by a schema, ensuring a clear contract.
Client-specified response: The client is in control of the data it receives.
Self-documenting: The API's capabilities are automatically known, making it easy to explore and use.

You can dive deeper into its principles on the official Introduction to GraphQL documentation.

Schema

Time to design the API! We'll do that by defining a GraphQL schema. There are three main operation types supported by GraphQL:

Query - fetch data from a GraphQL server
Mutation - modify data with a GraphQL server
Subscription - get real-time updates from a GraphQL server

The GraphQL type system is extendable and AWS AppSync takes advantage of that by defining its own types like AWSDateTime (which we are going to use). For the complete list see AWS AppSync scalars.

Our tooling will have to be aware of those types, so let's define those types in the cloud/lib/root.graphql:

type Query
type Mutation
type Subscription

scalar AWSDateTime

With that done, we can now create our own object types like Channel , Video, VideosPage and extend Query type with our own operation like listVideos:

cloud/lib/home/home.graphql

type Channel {
  id: ID!
  avatar: String!
  name: String!
}

type Video {
  id: ID!
  title: String!
  thumbnail: String!
  duration: String!
  url: String!
  publishedAt: AWSDateTime!
  channel: Channel!
}

type VideosPage {
  items: [Video!]!
  nextToken: String
}

extend type Query {
  listVideos(nextToken: String, limit: Int = 24): VideosPage!
}

We will have to merge our schema files into one schema.graphql file, which we will send to AWS AppSync. Lucky for us, there is a CLI tool for that: graphql-schema-utilities.

Let's install it:

npm install --save-dev graphql-schema-utilities

and add a graphql command to the package.json which will merge our schema files:

cloud/package.json (diff)

  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
-   "cdk": "cdk"
+   "cdk": "cdk",
+   "graphql": "rm -f ./lib/schema.graphql && graphql-schema-utilities --includeDirectives --schema \"{root.graphql,./lib/**/*.graphql}\" --output ./lib/schema.graphql"
  },

Now, let's run it and verify if schema.graphql files was created:

npm run graphql

cloud/lib/schema.graphql

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

scalar AWSDateTime

type Channel {
  id: ID!
  avatar: String!
  name: String!
}

type Mutation

type Query {
  listVideos(nextToken: String, limit: Int = 24): VideosPage!
}

type Subscription

type Video {
  id: ID!
  title: String!
  thumbnail: String!
  duration: String!
  url: String!
  publishedAt: AWSDateTime!
  channel: Channel!
}

type VideosPage {
  items: [Video!]!
  nextToken: String
}

All worked as expected.

GitHub: feat(home): graphql schema (#7)

AppSync

We will now focus on the AWS AppSync - serverless GraphQL and Pub/Sub API. As far as I know it's a very unique service and there is no direct one-to-one equivalent (in terms of GraphQL features) in other cloud providers like Microsoft Azure or Google Cloud.

Next up, we will define our AppSync construct using AWS CDK:

cloud/lib/appsync.ts

import * as appsync from "aws-cdk-lib/aws-appsync";
import * as cdk from "aws-cdk-lib";
import * as path from "path";
import { Construct } from "constructs";

import { DynamoDB } from "./dynamodb";

interface Props extends cdk.StackProps {
  dynamodb: DynamoDB;
}

export class AppSync extends Construct {
  public api: appsync.GraphqlApi;
  public dynamodbDS: appsync.DynamoDbDataSource;

  constructor(scope: Construct, id: string, { dynamodb }: Props) {
    super(scope, id);

    this.api = new appsync.GraphqlApi(this, "appsync-graphql-api", {
      name: "faketube",
      definition: appsync.Definition.fromFile(
        path.join(__dirname, "schema.graphql")
      ),
      authorizationConfig: {
        defaultAuthorization: {
          authorizationType: appsync.AuthorizationType.API_KEY,
          apiKeyConfig: {
            expires: cdk.Expiration.after(cdk.Duration.days(365)),
          },
        },
      },
    });

    this.dynamodbDS = this.api.addDynamoDbDataSource(
      "faketube",
      dynamodb.table
    );

    new cdk.CfnOutput(this, "GraphQLUrlExport", {
      value: this.api.graphqlUrl,
    });

    new cdk.CfnOutput(this, "GraphQLApiKeyExport", {
      value: this.api.apiKey || "",
    });
  }
}

It's not very complicated, two things worth noting:

definition: Set to our merged schema definition file schema.graphql
authorizationConfig: Set default authorization to API Keys. WARNING: we set expiration time of our API Key to 365 days, which is fine for our experiments, but can introduce a security vulnerability for the production environment, so we will have to fix that later
dynamodbDS: We also defined DynamoDB data source, which we will use to create our DynamoDB resolvers

Stack

Time to add our AppSync construct to the stack and deploy it.

cloud/lib/faketube-stack.ts (diff)

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

+import { AppSync } from "./appsync";
import { Aurora } from "./aurora";
import { DynamoDB } from "./dynamodb";
import { Gateway } from "./gateway";
import { Home } from "./home";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
    const aurora = new Aurora(this, "aurora", { vpc });
-   new DynamoDB(this, "dynamodb");
+   const dynamodb = new DynamoDB(this, "dynamodb");
    const gateway = new Gateway(this, "gateway");
+   new AppSync(this, "appsync", { dynamodb });

    new Home(this, "home", {
      aurora,
      gateway,
    });
  }
}

cdk diff

cdk deploy

Good time to save our exported outputs from the stack (API Key and GraphQL endpoint URL) as environment variables.

export FAKETUBE_AWS_APPSYNC_GRAPHQL_API_KEY=da2-7f7v2t5b5zd2noa6ut7xlbu6gu
export FAKETUBE_AWS_APPSYNC_GRAPHQL_ENDPOINT=https://5tzz3rnyjrhldnpnsnf4dyf6ea.appsync-api.eu-west-1.amazonaws.com/graphql

GitHub: feat(home): appsync (#7)

Home

Our next step is to create two variants of our architecture, highlighted in the sequence diagram from the introduction section:

DynamoDB resolver
Lambda resolver

DynamoDB resolver

cloud/lib/home/home.ts (diff)

import * as apigw from "aws-cdk-lib/aws-apigateway";
import * as path from "path";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as apigwv2 from "aws-cdk-lib/aws-apigatewayv2";
import { Construct } from "constructs";
import { HttpLambdaIntegration } from "aws-cdk-lib/aws-apigatewayv2-integrations";

+import { AppSync } from "../appsync";
+import { AppsyncResolver } from "../appsyncResolver";
import { Aurora } from "../aurora";
import { Gateway } from "../gateway";
import { Lambda } from "../lambda";

interface Props {
+ appsync: AppSync;
  aurora: Aurora;
  gateway: Gateway;
}

export class Home extends Construct {
-  constructor(scope: Construct, id: string, { aurora, gateway }: Props) {
+  constructor(
+    scope: Construct,
+    id: string,
+    { appsync, aurora, gateway }: Props
+  ) {
    super(scope, id);

    const listVideosLambda = new Lambda(this, "listVideos", {
      name: "listVideos",
      description: "Retrieve a paginated list of videos",
      entry: path.join(__dirname, "functions", "listVideos.lambda.ts"),
      environment: {
        SERVICE_NAME: "Home",
        LOG_LEVEL: "INFO",
        AURORA_SECRET_ARN: aurora.credentials.secretArn,
        AURORA_CLUSTER_ARN: aurora.cluster.clusterArn,
        AURORA_DATABASE_NAME: aurora.defaultName,
      },
    });
    aurora.cluster.grantDataApiAccess(listVideosLambda.function);

+   this.dynamodbResolver(appsync);
    this.rest(gateway.rest, listVideosLambda.function);
    this.http(gateway.http, listVideosLambda.function);
  }

+  dynamodbResolver(appsync: AppSync): void {
+    new AppsyncResolver(this, "listVideosResolver", {
+      name: "listVideos",
+      typeName: "Query",
+      entry: path.join(__dirname, "resolvers", "listVideos.resolver.js"),
+      appsync,
+    });
+
+    new AppsyncResolver(this, "getChannelResolver", {
+      name: "channel",
+      typeName: "Video",
+      entry: path.join(__dirname, "resolvers", "getChannel.resolver.js"),
+      appsync,
+    });
+  }

  rest(rest: apigw.RestApi, handler: lambda.IFunction): void {
    const videos = rest.root.addResource("videos", {
      defaultCorsPreflightOptions: {
        allowHeaders: apigw.Cors.DEFAULT_HEADERS,
        allowMethods: ["GET", "OPTIONS"],
        allowOrigins: this.node.tryGetContext("corsOrigins") || [],
      },
    });

    videos.addMethod("GET", new apigw.LambdaIntegration(handler));
  }

  http(http: apigwv2.HttpApi, handler: lambda.IFunction): void {
    const integration = new HttpLambdaIntegration("VideosIntegration", handler);

    http.addRoutes({
      path: "/videos",
      methods: [apigwv2.HttpMethod.GET],
      integration,
    });
  }
}

We actually create two resolvers here. One is listVideos query resolvers and second one is channel field resolver. In order to reduce a boilerplate, we also created AppsyncResolver helper construct, which looks like this:

cloud/lib/appsyncResolver.ts

import * as aws_appsync from "aws-cdk-lib/aws-appsync";
import { Construct } from "constructs";

import { AppSync } from "./appsync";

interface Props {
  name: string;
  typeName: string;
  entry: string;
  appsync: AppSync;
  dataSource?: aws_appsync.BaseDataSource;
}

export class AppsyncResolver extends Construct {
  public resolver: aws_appsync.Resolver;

  constructor(
    scope: Construct,
    id: string,
    { name, typeName, entry, appsync, dataSource }: Props
  ) {
    super(scope, id);

    this.resolver = new aws_appsync.Resolver(this, name, {
      api: appsync.api,
      fieldName: name,
      typeName,
      dataSource: dataSource || appsync.dynamodbDS,
      code: aws_appsync.Code.fromAsset(entry),
      runtime: aws_appsync.FunctionRuntime.JS_1_0_0,
    });
  }
}

Those (listVideos and getChannel) are JavaScript resolvers, which are defined like this:

cloud/lib/home/resolvers/listVideos.resolver.js

import * as ddb from "@aws-appsync/utils/dynamodb";

export function request(ctx) {
  const nextToken = ctx.args.nextToken;
  const limit = ctx.args.limit;

  return ddb.query({
    query: {
      GSI1_PK: { eq: "video" },
    },
    index: "GSI1",
    scanIndexForward: true,
    limit,
    nextToken,
  });
}

export function response(ctx) {
  if (ctx.error) {
    util.error(ctx.error.message, ctx.error.type);
  }

  const videos = ctx.result.items || [];
  const nextToken = ctx.result.nextToken;

  const page = {
    items: videos,
    nextToken,
  };

  return page;
}

cloud/lib/home/resolvers/getChannel.resolver.js

import { get } from "@aws-appsync/utils/dynamodb";
import { util } from "@aws-appsync/utils";

export function request(ctx) {
  const channelId = ctx.source.channelId;

  return get({
    key: {
      PK: `c#${channelId}`,
      SK: `c#${channelId}`,
    },
  });
}

export function response(ctx) {
  if (ctx.error) {
    util.error(ctx.error.message, ctx.error.type);
  }

  const channel = ctx.result;

  return channel;
}

As a final step, let's update our stack, deploy it and test our GraphQL API using cURL.

cloud/faketube-stack.ts (diff)

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { AppSync } from "./appsync";
import { Aurora } from "./aurora";
import { DynamoDB } from "./dynamodb";
import { Gateway } from "./gateway";
import { Home } from "./home";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
    const aurora = new Aurora(this, "aurora", { vpc });
    const dynamodb = new DynamoDB(this, "dynamodb");
    const gateway = new Gateway(this, "gateway");
-   new AppSync(this, "appsync", { dynamodb });
+   const appsync = new AppSync(this, "appsync", { dynamodb });  

    new Home(this, "home", {
+     appsync,
      aurora,
      gateway,
    });
  }
}

cdk diff

cdk deploy

To test our API we will send a listVideos query like this:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FAKETUBE_AWS_APPSYNC_GRAPHQL_API_KEY" \
  -d '{
    "query": "query ListVideos($limit: Int) { page: listVideos(limit: $limit) { items { id title thumbnail duration url publishedAt channel { id avatar name } } nextToken } }",
    "variables": {
      "limit": 2
    }
  }' \
  $FAKETUBE_AWS_APPSYNC_GRAPHQL_ENDPOINT | jq

Here's the result:

{
  "data": {
    "page": {
      "items": [
        {
          "id": "1ccSDKMvpGA",
          "title": "Exploring the Magic of Motorhomes",
          "thumbnail": "/videos/1ccSDKMvpGA/1ccSDKMvpGA.png",
          "duration": "PT0M6.047708S",
          "url": "/videos/1ccSDKMvpGA/1ccSDKMvpGA.mp4",
          "publishedAt": "2025-03-05T16:01:54Z",
          "channel": {
            "id": "AmazonNovaReel",
            "avatar": "/channels/AmazonNovaReel/AmazonNovaReel.png",
            "name": "Amazon Nova Reel"
          }
        },
        {
          "id": "51KK6cQwqdo",
          "title": "Desert Motorcycle Adventure",
          "thumbnail": "/videos/51KK6cQwqdo/51KK6cQwqdo.png",
          "duration": "PT0M6.047708S",
          "url": "/videos/51KK6cQwqdo/51KK6cQwqdo.mp4",
          "publishedAt": "2025-03-04T16:37:57Z",
          "channel": {
            "id": "AmazonNovaReel",
            "avatar": "/channels/AmazonNovaReel/AmazonNovaReel.png",
            "name": "Amazon Nova Reel"
          }
        }
      ],
      "nextToken": "eyJ2ZXJzaW9uIjozLCJ0b2tlbiI6IkFnVjQwRkFHKzNjNUNOUGlsdVNJYWJjdUZkTWdLUllEZjNqdWIrUHFSWmtMZ3pnQWV3QUNBQWRCY0hCVGVXNWpBQkZGYm1OeWVYQjBhVzl1UTI5dWRHVjRkQUFWWVhkekxXTnllWEIwYnkxd2RXSnNhV010YTJWNUFFUkJjelZrTVd0U1IxUkRjMjFQU3pkbmJXbGtPRWxWWmtWb1JEZGtXRUpEUjNkbmFFSTFWbTlNU1c1YU9UZE9lVk5PZHpkUFpISktOVmxKTlZkdlZtRnZZMEU5UFFBQkFBZGhkM010YTIxekFFdGhjbTQ2WVhkek9tdHRjenBsZFMxM1pYTjBMVEU2TkRRME5qazNNVEUxTVRRd09tdGxlUzgxTURka1pqQmpOQzFrTW1OaExUUTVPREV0T1RRek1TMDBZbUU0WlRjMlptWTNNRFFBdUFFQ0FRQjQweFhTdzVEZHNVb1NFZ0lQYlkxMnVlcjRTRHo4eGdTWDE4b0RoM3ZlYWtjQlk4M2YxMGh1UnVxQkZGTm11MDQ0MEFBQUFINHdmQVlKS29aSWh2Y05BUWNHb0c4d2JRSUJBREJvQmdrcWhraUc5dzBCQndFd0hnWUpZSVpJQVdVREJBRXVNQkVFRE5MbWprZWEwcms2RlZCN3F3SUJFSUE3U2RwSDcxTCtLc3hUTm4xOWYwdG95SlZBblE3MWNIdXArcVJhQmlLYU5hdENwc2RwcjcxczdCY2hQcmtMZ0NxQ1MwanhnSTJxM0hpcXdMY0NBQUFRQUJwN2NoSVlLREFOYW82dDhIbXkrNS9NQ3RzZHVHT0YwT3V4cEh3Wms1eEQ5Y3Nzbm9XLzdRajc0OFpTRGpDUHkvLy8vLzhBQUFBQkFBQUFBQUFBQUFBQUFBQUJBQUFDQjZkZkRyRHRST05rc2ljTXNPZXFjWHROaXg3Y0NmRDRnNUhlR1dNdFdxRWtUbUkzK2s5U3dRUys3Q3JqRHJvbC9jbEN2VzdOTWNkYW1Pd1FhTXB0QjZmNEdXaExKY0psR2RTWXd5dEhRRE9jdmRRamszcC80a1J5ZUk4MzFsRDNvU0drSjlxSmlHcjk5NTZ4TzN4Z1RVZFRHNGEveDRBTTB1R0UvN0NXZ25YUXRPalM2TGZRZElxRHdNNnFZYlZXSitZTkUrWXM0TnUrVDZOQ0hhd3J3enVJaVJyZTh3bWx4dUo2MnVGY3hIL21Jb3NBRS9IbWxROUlocjd6VXRaSGhBV25lakVON3hGMGhFVHZTenBKRUtxS0JWZ1FQKzBycW9IYUpTY005dUwyTmJpc0phQ3R1TEdLbnRLalZqZHZ5QmR1N2h2OHkzWjBIY3lvVmk4cWViMHQ3K1JkMkNzYVZVTHUwLy9XSlo1c08wUlRXQ3VZUGFhaDFvK3JpbVNFVTlDYnFaZGd1L0FUS2IzdTJBelZ6VHlKWnZKVVhHUEhZNkNkejdKOW93eXJObjA3RWNRTW40VmdqTnVxRzdzdUZWRFBKdmN0MytmeGZaamVXTk1KSzJ1MlkvUC9EZ2d3RUNHbE1MUnVkRkNocWxtSFFkenl4OWV2NlVPNEdMa0E1bW1mN0N2Ymhyek5VSytnL2dXejFPNW5OSHJodUVoeDd0dDlxUEpnblpIUzdUbWpyd3A0U2VHbUpFY1dkWG1FcElBaFF4RjNZN3d6Tm55U1ZCOU1kdFZjNlRxK3hXazZkelBVdnlqWGE2NkJzSkw4bis0aFYrVk4xekpoeWJLeXhMYU9xblZTZldGZE1lRmYxUVFyOHB0STUydllSdjgwdnJFMGhpd24rYXUzS2FIcXFBY3c1emQzSEVRUU8xYVZXeVNCNWR2OFBEZ0FaekJsQWpFQTJHVUVNK2dZakR0QUtvcWdieUZBTnBCKytuK0Fpc3VuZjhiVk9vYkNCck4wODh0Z0VTaW8rT01YeGhZUGF2eEVBakJsRlZZVGVXQ0hNcldiZmcyNkZ1QTdoaVg0QWpEeE5pY2Y1S202K0ZEVnhhcEUzR3lWc0lTVXJpOFJPUTVnV25rPSJ9"
    }
  }
}

GitHub: feat(home): appsync dynamodb resolver (#7)

Lambda resolver

Next, the seconds variant of our architecture, using Lambda resolver.

We will need a separate query for this e.g. listVideosLambdaProxy, so let's update our GraphQL schema:

cloud/lib/home/home.graphql (diff)

type Channel {
  id: ID!
  avatar: String!
  name: String!
}

type Video {
  id: ID!
  title: String!
  thumbnail: String!
  duration: String!
  url: String!
  publishedAt: AWSDateTime!
  channel: Channel!
}

type VideosPage {
  items: [Video!]!
  nextToken: String
}

extend type Query {
  listVideos(nextToken: String, limit: Int = 24): VideosPage!
+ listVideosProxy(nextToken: String, limit: Int = 24): VideosPage!
}

npm run graphql

With that done, we can now define our lambda resolver in the Home construct:

cloud/lib/home/home.tsx (diff)

import * as apigw from "aws-cdk-lib/aws-apigateway";
import * as path from "path";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as apigwv2 from "aws-cdk-lib/aws-apigatewayv2";
import { Construct } from "constructs";
import { HttpLambdaIntegration } from "aws-cdk-lib/aws-apigatewayv2-integrations";

import { AppSync } from "../appsync";
import { AppsyncResolver } from "../appsyncResolver";
import { Aurora } from "../aurora";
import { Gateway } from "../gateway";
import { Lambda } from "../lambda";

interface Props {
  appsync: AppSync;
  aurora: Aurora;
  gateway: Gateway;
}

export class Home extends Construct {
  constructor(
    scope: Construct,
    id: string,
    { appsync, aurora, gateway }: Props
  ) {
    super(scope, id);

    const listVideosLambda = new Lambda(this, "listVideos", {
      name: "listVideos",
      description: "Retrieve a paginated list of videos",
      entry: path.join(__dirname, "functions", "listVideos.lambda.ts"),
      environment: {
        SERVICE_NAME: "Home",
        LOG_LEVEL: "INFO",
        AURORA_SECRET_ARN: aurora.credentials.secretArn,
        AURORA_CLUSTER_ARN: aurora.cluster.clusterArn,
        AURORA_DATABASE_NAME: aurora.defaultName,
      },
    });
    aurora.cluster.grantDataApiAccess(listVideosLambda.function);

    this.dynamodbResolver(appsync);
+   this.lambdaResolver(appsync);
    this.rest(gateway.rest, listVideosLambda.function);
    this.http(gateway.http, listVideosLambda.function);
  }

  dynamodbResolver(appsync: AppSync): void {
    new AppsyncResolver(this, "listVideosResolver", {
      name: "listVideos",
      typeName: "Query",
      entry: path.join(__dirname, "resolvers", "listVideos.resolver.js"),
      appsync,
    });

    new AppsyncResolver(this, "getChannelResolver", {
      name: "channel",
      typeName: "Video",
      entry: path.join(__dirname, "resolvers", "getChannel.resolver.js"),
      appsync,
    });
  }

+  lambdaResolver(appsync: AppSync): void {
+    const listVideosProxyLambda = new Lambda(this, "listVideosProxy", {
+      name: "listVideosProxy",
+      description: "Retrieve a paginated list of videos",
+      entry: path.join(__dirname, "functions", "listVideosProxy.lambda.ts"),
+      environment: {
+        SERVICE_NAME: "Home",
+        LOG_LEVEL: "INFO",
+      },
+    });
+
+    const lambdaDS = appsync.api.addLambdaDataSource(
+      `listVideosProxyDS`,
+      listVideosProxyLambda.function
+    );
+
+    lambdaDS.createResolver("listVideosProxy", {
+      typeName: "Query",
+      fieldName: "listVideosProxy",
+    });
+  }
+
  rest(rest: apigw.RestApi, handler: lambda.IFunction): void {
    const videos = rest.root.addResource("videos", {
      defaultCorsPreflightOptions: {
        allowHeaders: apigw.Cors.DEFAULT_HEADERS,
        allowMethods: ["GET", "OPTIONS"],
        allowOrigins: this.node.tryGetContext("corsOrigins") || [],
      },
    });

    videos.addMethod("GET", new apigw.LambdaIntegration(handler));
  }

  http(http: apigwv2.HttpApi, handler: lambda.IFunction): void {
    const integration = new HttpLambdaIntegration("VideosIntegration", handler);

    http.addRoutes({
      path: "/videos",
      methods: [apigwv2.HttpMethod.GET],
      integration,
    });
  }
}

Now, the lambda boilerplate (known from the previous episode), which will return an empty page of videos (without actually making any DynamoDB requests yet):

cloud/lib/home/functions/listVideosProxy.lambda.ts

import error from "@middy/http-error-handler";
const env = require("middy-env");
import middy from "@middy/core";
import validator from "@middy/validator";
import { AppSyncResolverEvent } from "aws-lambda";
import { captureLambdaHandler } from "@aws-lambda-powertools/tracer/middleware";
import { injectLambdaContext } from "@aws-lambda-powertools/logger/middleware";
import { Logger } from "@aws-lambda-powertools/logger";
import { LogLevel } from "@aws-lambda-powertools/logger/types";
import { logMetrics } from "@aws-lambda-powertools/metrics/middleware";
import { Metrics } from "@aws-lambda-powertools/metrics";
import { Tracer } from "@aws-lambda-powertools/tracer";
import { transpileSchema } from "@middy/validator/transpile";

import { Video } from "../video";
import { Page } from "../page";

const serviceName = process.env.SERVICE_NAME!;
const logLevel = (process.env.LOG_LEVEL || "ERROR") as LogLevel;

const metrics = new Metrics({ namespace: serviceName });
const logger = new Logger({ logLevel, serviceName });
const tracer = new Tracer({ serviceName });

interface Arguments {
  nextToken?: string;
  limit?: number;
}

export const lambdaHandler = async (
  event: AppSyncResolverEvent<Arguments, Page<Video[]>>
) => {
  try {
    console.log("event", JSON.stringify(event));

    const { nextToken, limit } = event.arguments || {};

    const page: Page<Video> = {
      items: [],
    };
    console.log("Page:", page);

    return page;
  } catch (e: any) {
    console.error(e);
    return {
      items: [],
    };
  }
};

const envMap = {
  names: {
    serviceName: ["SERVICE_NAME"],
    logLevel: ["LOG_LEVEL"],
    corsOrigins: ["CORS_ORIGINS"],
  },
};

const eventSchema = {
  type: "object",
  properties: {
    arguments: {
      type: "object",
      properties: {
        nextToken: {
          type: ["string", "null"],
        },
        limit: {
          type: "integer",
          minimum: 1,
        },
      },
      additionalProperties: true,
    },
  },
};

export const handler = middy(lambdaHandler)
  .use(captureLambdaHandler(tracer))
  .use(logMetrics(metrics, { captureColdStartMetric: true }))
  .use(injectLambdaContext(logger, { logEvent: true }))
  .use(env(envMap))
  .use(validator({ eventSchema: transpileSchema(eventSchema) }))
  .use(
    error({ logger: (message) => logger.error("http-error-handler", message) })
  );

The page of videos returned by our Lambda resolver will be a little bit different than that returned by API Gateway. There will be no currentPage and hasNexPage, but a nextToken instead. We have to make those properties optional.

cloud/lib/home.page.ts (diff)

export interface Page<T> {
  items: T[];
- currentPage: number;
+ currentPage?: number;
- hasNextPage: boolean;
+ hasNextPage?: boolean;
+ nextToken?: string;
}

cdk deploy

To test our API we will send a listVideosProxy query like this:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FAKETUBE_AWS_APPSYNC_GRAPHQL_API_KEY" \
  -d '{
    "query": "query ListVideosProxy($limit: Int) { page: listVideosProxy(limit: $limit) { items { id title thumbnail duration url publishedAt channel { id avatar name } } nextToken } }",
    "variables": {
      "limit": 2
    }
  }' \
  $FAKETUBE_AWS_APPSYNC_GRAPHQL_ENDPOINT | jq

The output is:

{
  "data": {
    "page": {
      "items": [],
      "nextToken": null
    }
  }
}

GitHub: feat(home): appsync lambda resolver boilerplate (#7)

DynamoDB

Finally we have to write real DynamoDB queries in our Lambda function. For that we will need to use two DynamoDB related libraries from the AWS SDK v3, so let's install them first:

npm install --save-dev @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Now, we are ready to finish the lambda resolver function.

cloud/lib/home/functions/listVideosProxy.lambda.ts (diff)

import error from "@middy/http-error-handler";
const env = require("middy-env");
import middy from "@middy/core";
import validator from "@middy/validator";
import { AppSyncResolverEvent } from "aws-lambda";
import { captureLambdaHandler } from "@aws-lambda-powertools/tracer/middleware";
+import { DynamoDB } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
import { injectLambdaContext } from "@aws-lambda-powertools/logger/middleware";
import { Logger } from "@aws-lambda-powertools/logger";
import { LogLevel } from "@aws-lambda-powertools/logger/types";
import { logMetrics } from "@aws-lambda-powertools/metrics/middleware";
import { Metrics } from "@aws-lambda-powertools/metrics";
import { Tracer } from "@aws-lambda-powertools/tracer";
import { transpileSchema } from "@middy/validator/transpile";

+import { Channel } from "../channel";
import { Video } from "../video";
import { Page } from "../page";

const serviceName = process.env.SERVICE_NAME!;
const logLevel = (process.env.LOG_LEVEL || "ERROR") as LogLevel;

const metrics = new Metrics({ namespace: serviceName });
const logger = new Logger({ logLevel, serviceName });
const tracer = new Tracer({ serviceName });

interface Arguments {
  nextToken?: string;
  limit?: number;
}

+const dynamodb = DynamoDBDocument.from(new DynamoDB());
+
export const lambdaHandler = async (
  event: AppSyncResolverEvent<Arguments, Page<Video[]>>
) => {
  try {
    console.log("event", JSON.stringify(event));

    const { nextToken, limit } = event.arguments || {};
+
+   const { Items, LastEvaluatedKey } = await dynamodb.query({
+      TableName: "FakeTube",
+      IndexName: "GSI1",
+      KeyConditions: {
+        GSI1_PK: {
+          ComparisonOperator: "EQ",
+          AttributeValueList: ["video"],
+        },
+      },
+      Limit: limit,
+      ExclusiveStartKey: nextToken ? JSON.parse(nextToken) : undefined,
+    });
+
+    const videos = (Items || []) as VideoItem[];
+
+    const uniqueChannelIds = Array.from(
+      new Set(videos.map((video) => video.channelId))
+    );
+
+    const channels = (
+      await dynamodb.batchGet({
+        RequestItems: {
+          ["FakeTube"]: {
+            Keys: uniqueChannelIds.map((channelId) => ({
+              PK: `c#${channelId}`,
+              SK: `c#${channelId}`,
+            })),
+          },
+        },
+      })
+    ).Responses!["FakeTube"] as Channel[];
+
+    const videosWithChannel: Video[] = videos.map((video) => ({
+      id: video.id,
+      title: video.title,
+      thumbnail: video.thumbnail,
+      duration: video.duration,
+      url: video.url,
+      publishedAt: video.publishedAt,
+      channel: (() => {
+        const c = channels.find((channel) => channel.id === video.channelId)!;
+        return { id: c.id, name: c.name, avatar: c.avatar };
+      })(),
+    }));    

    const page: Page<Video> = {
-     items: [],
+     items: (videosWithChannel || []) as Video[],
+     nextToken: LastEvaluatedKey
+       ? JSON.stringify(LastEvaluatedKey)
+       : undefined,
    };
    console.log("Page:", page);

    return page;
  } catch (e: any) {
    console.error(e);
    return {
      items: [],
    };
  }
};

+interface VideoItem {
+  id: string;
+  title: string;
+  thumbnail: string;
+  duration: string;
+  url: string;
+  publishedAt: string;
+  channelId: string;
+}

const envMap = {
  names: {
    serviceName: ["SERVICE_NAME"],
    logLevel: ["LOG_LEVEL"],
    corsOrigins: ["CORS_ORIGINS"],
  },
};

...

cloud/lib/home/home.ts (diff)

import * as apigw from "aws-cdk-lib/aws-apigateway";
import * as path from "path";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as apigwv2 from "aws-cdk-lib/aws-apigatewayv2";
import { Construct } from "constructs";
import { HttpLambdaIntegration } from "aws-cdk-lib/aws-apigatewayv2-integrations";

import { AppSync } from "../appsync";
import { AppsyncResolver } from "../appsyncResolver";
import { Aurora } from "../aurora";
+import { DynamoDB } from "../dynamodb";
import { Gateway } from "../gateway";
import { Lambda } from "../lambda";

interface Props {
  appsync: AppSync;
  aurora: Aurora;
+ dynamodb: DynamoDB;
  gateway: Gateway;
}

export class Home extends Construct {
  constructor(
    scope: Construct,
    id: string,
-   { appsync, aurora, gateway }: Props
+   { appsync, aurora, dynamodb, gateway }: Props
  ) {
    super(scope, id);

    const listVideosLambda = new Lambda(this, "listVideos", {
      name: "listVideos",
      description: "Retrieve a paginated list of videos",
      entry: path.join(__dirname, "functions", "listVideos.lambda.ts"),
      environment: {
        SERVICE_NAME: "Home",
        LOG_LEVEL: "INFO",
        AURORA_SECRET_ARN: aurora.credentials.secretArn,
        AURORA_CLUSTER_ARN: aurora.cluster.clusterArn,
        AURORA_DATABASE_NAME: aurora.defaultName,
      },
    });
    aurora.cluster.grantDataApiAccess(listVideosLambda.function);

    this.dynamodbResolver(appsync);
-   this.lambdaResolver(appsync);
+   this.lambdaResolver(appsync, dynamodb);
    this.rest(gateway.rest, listVideosLambda.function);
    this.http(gateway.http, listVideosLambda.function);
  }

  dynamodbResolver(appsync: AppSync): void {
    new AppsyncResolver(this, "listVideosResolver", {
      name: "listVideos",
      typeName: "Query",
      entry: path.join(__dirname, "resolvers", "listVideos.resolver.js"),
      appsync,
    });

    new AppsyncResolver(this, "getChannelResolver", {
      name: "channel",
      typeName: "Video",
      entry: path.join(__dirname, "resolvers", "getChannel.resolver.js"),
      appsync,
    });
  }

- lambdaResolver(appsync: AppSync): void {
+ lambdaResolver(appsync: AppSync, dynamodb: DynamoDB): void {
    const listVideosProxyLambda = new Lambda(this, "listVideosProxy", {
      name: "listVideosProxy",
      description: "Retrieve a paginated list of videos",
      entry: path.join(__dirname, "functions", "listVideosProxy.lambda.ts"),
      environment: {
        SERVICE_NAME: "Home",
        LOG_LEVEL: "INFO",
      },
    });
+   dynamodb.table.grantReadData(listVideosProxyLambda.function);

    const lambdaDS = appsync.api.addLambdaDataSource(
      `listVideosProxyDS`,
      listVideosProxyLambda.function
    );

    lambdaDS.createResolver("listVideosProxy", {
      typeName: "Query",
      fieldName: "listVideosProxy",
    });
  }

  rest(rest: apigw.RestApi, handler: lambda.IFunction): void {
    const videos = rest.root.addResource("videos", {
      defaultCorsPreflightOptions: {
        allowHeaders: apigw.Cors.DEFAULT_HEADERS,
        allowMethods: ["GET", "OPTIONS"],
        allowOrigins: this.node.tryGetContext("corsOrigins") || [],
      },
    });

    videos.addMethod("GET", new apigw.LambdaIntegration(handler));
  }

  http(http: apigwv2.HttpApi, handler: lambda.IFunction): void {
    const integration = new HttpLambdaIntegration("VideosIntegration", handler);

    http.addRoutes({
      path: "/videos",
      methods: [apigwv2.HttpMethod.GET],
      integration,
    });
  }
}

cloud/lib/faketube-stack.ts (diff)

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { AppSync } from "./appsync";
import { Aurora } from "./aurora";
import { DynamoDB } from "./dynamodb";
import { Gateway } from "./gateway";
import { Home } from "./home";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
    const aurora = new Aurora(this, "aurora", { vpc });
    const dynamodb = new DynamoDB(this, "dynamodb");
    const gateway = new Gateway(this, "gateway");
    const appsync = new AppSync(this, "appsync", { dynamodb });

    new Home(this, "home", {
      appsync,
      aurora,
+     dynamodb,
      gateway,
    });
  }
}

To test our solution, we have to deploy it, but first let's temporarily comment out DynamoDB resolver version. It has that channel field resolver which will interfere with our Lambda resolver.

cloud/lib/home/home.ts (diff)

    const listVideosLambda = new Lambda(this, "listVideos", {
      name: "listVideos",
      description: "Retrieve a paginated list of videos",
      entry: path.join(__dirname, "functions", "listVideos.lambda.ts"),
      environment: {
        SERVICE_NAME: "Home",
        LOG_LEVEL: "INFO",
        AURORA_SECRET_ARN: aurora.credentials.secretArn,
        AURORA_CLUSTER_ARN: aurora.cluster.clusterArn,
        AURORA_DATABASE_NAME: aurora.defaultName,
      },
    });
    aurora.cluster.grantDataApiAccess(listVideosLambda.function);

-   this.dynamodbResolver(appsync);
+   // this.dynamodbResolver(appsync);
    this.lambdaResolver(appsync, dynamodb);
    this.rest(gateway.rest, listVideosLambda.function);
    this.http(gateway.http, listVideosLambda.function);

cdk deploy

To test our API we will send a listVideosProxy query again:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: $FAKETUBE_AWS_APPSYNC_GRAPHQL_API_KEY" \
  -d '{
    "query": "query ListVideosProxy($limit: Int) { page: listVideosProxy(limit: $limit) { items { id title thumbnail duration url publishedAt channel { id avatar name } } nextToken } }",
    "variables": {
      "limit": 2
    }
  }' \
  $FAKETUBE_AWS_APPSYNC_GRAPHQL_ENDPOINT | jq

This is the outcome:

{
  "data": {
    "page": {
      "items": [
        {
          "id": "QYUGZ3ueoHQ",
          "title": "Magic Wheels: The Future of Cars",
          "thumbnail": "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.png",
          "duration": "PT0M6.047708S",
          "url": "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.mp4",
          "publishedAt": "2025-03-03T14:22:54Z",
          "channel": {
            "id": "AmazonNovaReel",
            "avatar": "/channels/AmazonNovaReel/AmazonNovaReel.png",
            "name": "Amazon Nova Reel"
          }
        },
        {
          "id": "q9Gm7a6Wwjk",
          "title": "The Amazing World of Octopus!",
          "thumbnail": "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png",
          "duration": "PT0M6.214542S",
          "url": "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.mp4",
          "publishedAt": "2025-03-03T15:58:23Z",
          "channel": {
            "id": "AmazonNovaReel",
            "avatar": "/channels/AmazonNovaReel/AmazonNovaReel.png",
            "name": "Amazon Nova Reel"
          }
        }
      ],
      "nextToken": "{\"GSI1_SK\":\"2025-03-03T15:58:23Z\",\"SK\":\"v#q9Gm7a6Wwjk\",\"PK\":\"v#q9Gm7a6Wwjk\",\"GSI1_PK\":\"video\"}"
    }
  }
}

GitHub: feat(home): appsync lambda resolver dynamodb (#7)

Frontend

The backend part is ready, so we can shift our focus to the frontend. Let's start with Amplify configuration for GraphQL.

Amplify

We have to add GraphQL endpoint URL and default authentication mode, which will be the API Key.

web/amplify-configuration.ts (diff)

import { ResourcesConfig } from "aws-amplify";

export const config: ResourcesConfig = {
  API: {
    REST: {
      faketubeHttp: {
        region: process.env.NEXT_PUBLIC_FAKETUBE_AWS_REGION!,
        endpoint:
          process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_ENDPOINT!,
      },
      faketubeRest: {
        region: process.env.NEXT_PUBLIC_FAKETUBE_AWS_REGION!,
        endpoint:
          process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_ENDPOINT!,
      },
    },
+   GraphQL: {
+     endpoint: process.env.NEXT_PUBLIC_FAKETUBE_AWS_APPSYNC_GRAPHQL_ENDPOINT!,
+     apiKey: process.env.NEXT_PUBLIC_FAKETUBE_AWS_APPSYNC_GRAPHQL_API_KEY!,
+     defaultAuthMode: "apiKey",
+   },
  },
};

export default config;

Since we used two new environment variables in the amplify configuration, we have to configure them in .env file. We will also extend our switch for the API type and set it to graphql_dynamodb_resolver (which will be our default variant).

web/.env (diff)

NEXT_PUBLIC_FAKETUBE_AWS_REGION=eu-west-1
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_ENDPOINT=https://exzg8ug9ya.execute-api.eu-west-1.amazonaws.com/prod
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_NAME=faketubeRest
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_ENDPOINT=https://po560wpeeg.execute-api.eu-west-1.amazonaws.com
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_NAME=faketubeHttp
+NEXT_PUBLIC_FAKETUBE_AWS_APPSYNC_GRAPHQL_ENDPOINT=https://5tzz3rnyjrhldnpnsnf4dyf6ea.appsync-api.eu-west-1.amazonaws.com/graphql
+NEXT_PUBLIC_FAKETUBE_AWS_APPSYNC_GRAPHQL_API_KEY=da2-7f7v2t5b5zd2noa6ut7xlbu6gu

-# mock | rest | http
+# mock | api_gateway_rest | api_gateway_http | graphql_dynamodb_resolver | graphql_lambda_resolver
-NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH=http
+NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH=graphql_dynamodb_resolver

Before we forget, let's also open AWS Console and update environment variables in Amplify Hosting, so that they will be used with the next build.

Now, the most important part. Integration with the AppSync based GraphQL API will be in the fetchGraphQL function. We will also add and clean up some logic related to the API type choice (it adds some complexity, but that's the price for having everything in one place and exploring different possibilities).

cloud/lib/home/useListVideosGraphQL.tsx (diff)

import { get } from "aws-amplify/api";
+import { generateClient } from "aws-amplify/api";
-import { useInfiniteQuery } from "@tanstack/react-query";
+import { InfiniteData, useInfiniteQuery } from "@tanstack/react-query";

import { Page } from "./pagination";
import { Video } from "./video";
import { VIDEOS } from "./videos.data";
+
+const client = generateClient();

export const PAGE_SIZE = 24;
const DELAY_MS = 1000;

const fetchMock = async (
  currentPage: number,
  pageSize: number = PAGE_SIZE
): Promise<Page<Video>> => {
  await new Promise((resolve) => setTimeout(resolve, DELAY_MS));

  const start = currentPage * pageSize;
  const end = start + pageSize;

  return {
    items: VIDEOS.slice(start, end),
    currentPage,
    hasNextPage: end < VIDEOS.length,
  };
};

enum ApiType {
  MOCK = "mock",
- REST = "rest",
- HTTP = "http",
+ API_GATEWAY_REST = "api_gateway_rest",
+ API_GATEWAY_HTTP = "api_gateway_http",
+ GRAPHQL_DYNAMODB_RESOLVER = "graphql_dynamodb_resolver",
+ GRAPHQL_LAMBDA_RESOLVER = "graphql_lambda_resolver",
}

const getApiName = (): string => {
  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
-   case ApiType.REST:
+   case ApiType.API_GATEWAY_REST:
      return process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_NAME!;
-   case ApiType.HTTP:
+   case ApiType.API_GATEWAY_HTTP:
      return process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_NAME!;
    default:
      throw new Error("Invalid API switch configuration");
  }
};

const fetchApi = async (
  currentPage: number,
  pageSize: number = PAGE_SIZE
): Promise<Page<Video>> => {
  try {
    const restOperation = get({
      apiName: getApiName(),
      path: "/videos",
      options: {
        queryParams: {
          page: currentPage.toString(),
          pageSize: pageSize.toString(),
        },
      },
    });

    const { body } = await restOperation.response;
    const response = await body.json();

    console.log("Response from API:", response);

    const page = response as unknown as Page<Video>;

    return page;
  } catch (error) {
    console.error("Error fetching videos:", error);
    return {
      items: [],
      currentPage,
      hasNextPage: false,
    };
  }
};

+export const Query = (variant: "" | "Proxy") => `
+  query listVideos${variant}($nextToken: String, $limit: Int) {
+    page: listVideos${variant}(nextToken: $nextToken, limit: $limit) {    
+      items {
+        id
+        title
+        thumbnail
+        duration
+        url
+        publishedAt
+        channel {
+          id
+          avatar
+          name
+        }
+      }
+      nextToken
+    }
+  }
+`;
+
+export interface Result {
+  data: {
+    page: Page<Video>;
+  };
+}
+
+const fetchGraphQL = async (
+  nextToken: string | undefined,
+  limit: number = PAGE_SIZE
+) => {
+  try {
+    const result = (await client.graphql({
+      query: Query(
+        process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH ===
+          ApiType.GRAPHQL_LAMBDA_RESOLVER
+          ? "Proxy"
+          : ""
+      ),
+      variables: { nextToken, limit },
+    })) as Result;
+
+    console.log(JSON.stringify(result, null, 2));
+
+    return result?.data.page;
+  } catch (e: unknown) {
+    console.error(e);
+    return {
+      items: [],
+    };
+  }
+};
+
+const fetch = (page: number | undefined | string) => {
+  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
+    case ApiType.API_GATEWAY_REST:
+    case ApiType.API_GATEWAY_HTTP:
+      return fetchApi(+(page || 0));
+    case ApiType.GRAPHQL_DYNAMODB_RESOLVER:
+    case ApiType.GRAPHQL_LAMBDA_RESOLVER:
+      return fetchGraphQL(page?.toString());
+    default:
+      return fetchMock(+(page || 0));
+  }
+};
+
+const getInitialPageParam = (): number | undefined => {
+  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
+    case ApiType.GRAPHQL_DYNAMODB_RESOLVER:
+    case ApiType.GRAPHQL_LAMBDA_RESOLVER:
+      return undefined;
+    default:
+      return 0;
+  }
+};
+
+const getNextPageParam = (
+  lastPage: Page<Video>
+): number | undefined | string => {
+  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
+    case ApiType.GRAPHQL_DYNAMODB_RESOLVER:
+    case ApiType.GRAPHQL_LAMBDA_RESOLVER:
+      return lastPage.nextToken;
+    default:
+      return lastPage.hasNextPage ? lastPage.currentPage! + 1 : undefined;
+  }
+};
+

export const useListVideos = () => {
- return useInfiniteQuery({
+ return useInfiniteQuery<
+   Page<Video>,
+   Error,
+   InfiniteData<Page<Video>, number | undefined | string>,
+   string[],
+   number | undefined | string
+ >({
    queryKey: ["listVideos"],
-   queryFn: ({ pageParam: page }) =>
-     process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH === ApiType.MOCK
-       ? fetchMock(page)
-       : fetchApi(page),
-   initialPageParam: 0,
-   getNextPageParam: (lastPage) =>
-     lastPage.hasNextPage ? lastPage.currentPage + 1 : undefined,
+   queryFn: ({ pageParam: page }) => fetch(page),
+   initialPageParam: getInitialPageParam(),
+   getNextPageParam,
  });
};

cloud/lib/home/useListVideos.tsx

import { get } from "aws-amplify/api";
import { generateClient } from "aws-amplify/api";
import { InfiniteData, useInfiniteQuery } from "@tanstack/react-query";

import { Page } from "./pagination";
import { Video } from "./video";
import { VIDEOS } from "./videos.data";

const client = generateClient();

export const PAGE_SIZE = 24;
const DELAY_MS = 1000;

const fetchMock = async (
  currentPage: number,
  pageSize: number = PAGE_SIZE
): Promise<Page<Video>> => {
  await new Promise((resolve) => setTimeout(resolve, DELAY_MS));

  const start = currentPage * pageSize;
  const end = start + pageSize;

  return {
    items: VIDEOS.slice(start, end),
    currentPage,
    hasNextPage: end < VIDEOS.length,
  };
};

enum ApiType {
  MOCK = "mock",
  API_GATEWAY_REST = "api_gateway_rest",
  API_GATEWAY_HTTP = "api_gateway_http",
  GRAPHQL_DYNAMODB_RESOLVER = "graphql_dynamodb_resolver",
  GRAPHQL_LAMBDA_RESOLVER = "graphql_lambda_resolver",
}

const getApiName = (): string => {
  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
    case ApiType.API_GATEWAY_REST:
      return process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_NAME!;
    case ApiType.API_GATEWAY_HTTP:
      return process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_NAME!;
    default:
      throw new Error("Invalid API switch configuration");
  }
};

const fetchApi = async (
  currentPage: number,
  pageSize: number = PAGE_SIZE
): Promise<Page<Video>> => {
  try {
    const restOperation = get({
      apiName: getApiName(),
      path: "/videos",
      options: {
        queryParams: {
          page: currentPage.toString(),
          pageSize: pageSize.toString(),
        },
      },
    });

    const { body } = await restOperation.response;
    const response = await body.json();

    console.log("Response from API:", response);

    const page = response as unknown as Page<Video>;

    return page;
  } catch (error) {
    console.error("Error fetching videos:", error);
    return {
      items: [],
      currentPage,
      hasNextPage: false,
    };
  }
};

export const Query = (variant: "" | "Proxy") => `
  query listVideos${variant}($nextToken: String, $limit: Int) {
    page: listVideos${variant}(nextToken: $nextToken, limit: $limit) {    
      items {
        id
        title
        thumbnail
        duration
        url
        publishedAt
        channel {
          id
          avatar
          name
        }
      }
      nextToken
    }
  }
`;

export interface Result {
  data: {
    page: Page<Video>;
  };
}

const fetchGraphQL = async (
  nextToken: string | undefined,
  limit: number = PAGE_SIZE
) => {
  try {
    const result = (await client.graphql({
      query: Query(
        process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH ===
          ApiType.GRAPHQL_LAMBDA_RESOLVER
          ? "Proxy"
          : ""
      ),
      variables: { nextToken, limit },
    })) as Result;

    console.log(JSON.stringify(result, null, 2));

    return result?.data.page;
  } catch (e: unknown) {
    console.error(e);
    return {
      items: [],
    };
  }
};

const fetch = (page: number | undefined | string) => {
  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
    case ApiType.API_GATEWAY_REST:
    case ApiType.API_GATEWAY_HTTP:
      return fetchApi(+(page || 0));
    case ApiType.GRAPHQL_DYNAMODB_RESOLVER:
    case ApiType.GRAPHQL_LAMBDA_RESOLVER:
      return fetchGraphQL(page?.toString());
    default:
      return fetchMock(+(page || 0));
  }
};

const getInitialPageParam = (): number | undefined => {
  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
    case ApiType.GRAPHQL_DYNAMODB_RESOLVER:
    case ApiType.GRAPHQL_LAMBDA_RESOLVER:
      return undefined;
    default:
      return 0;
  }
};

const getNextPageParam = (
  lastPage: Page<Video>
): number | undefined | string => {
  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
    case ApiType.GRAPHQL_DYNAMODB_RESOLVER:
    case ApiType.GRAPHQL_LAMBDA_RESOLVER:
      return lastPage.nextToken;
    default:
      return lastPage.hasNextPage ? lastPage.currentPage! + 1 : undefined;
  }
};

export const useListVideos = () => {
  return useInfiniteQuery<
    Page<Video>,
    Error,
    InfiniteData<Page<Video>, number | undefined | string>,
    string[],
    number | undefined | string
  >({
    queryKey: ["listVideos"],
    queryFn: ({ pageParam: page }) => fetch(page),
    initialPageParam: getInitialPageParam(),
    getNextPageParam,
  });
};

One more small change is needed to the pagination functionality. We already did the same thing for the backend.

web/app/Home/pagination.ts (diff)

export interface Page<T> {
  items: T[];
- currentPage: number;
+ currentPage?: number;
- hasNextPage: boolean;
+ hasNextPage?: boolean;
+ nextToken?: string;
}

Now we are ready for the end-to-end testing in our browser.

GitHub: feat(home): graphql api integration (#7)

Trademark Notice

It turns out that FakeTube is an already registered trademark. I started a rebranding process, but it will take a while.

Videos REST API with API Gateway, Lambda, Aurora Serverless - FakeTube #5

Jacek Kościesza — Sat, 23 Aug 2025 12:17:32 +0000

faketube.app

In the previous episodes, we created a solid frontend foundation for our project - application shell and home page with a responsive UI and infinite scrolling.

But as we know, a YouTube clone without a proper backend is like a car without an engine — it looks good, but it won’t go anywhere.

We'll start building the core backend services for our project. Starting with a traditional approach with a REST API and SQL database, we will later move to a modern approach with a GraphQL based API and NoSQL database.

We'll leverage the power of AWS and Infrastructure as Code (IoC) with the AWS Cloud Development Kit (CDK) to define and deploy our resources.

So far our high level architecture diagram wasn't very impressive - we only used AWS Amplify service to host our web application. Of course there are many services under the hood like Route 53, CloudFront, Certificate Manager, Lambda and S3, but Amplify provides level of abstraction, so that we don't have to think about it.

In this episode we will add a few pieces. Think of it as creating a custom LEGO set for our backend, but this time, the LEGO bricks are Amazon API Gateway, AWS Lambda, and Amazon Aurora Serverless.

On the frontend side we will use AWS Amplify for Next.js library, which will simplify fetching data from the API Gateway.

This sequence diagram should give us a high level idea of the solution.

Let's get building!

CDK (Cloud Development Kit)

The Cloud Development Kit is an open-source framework that lets you define your cloud application resources using familiar programming languages. Instead of writing complex JSON or YAML templates, you can use languages like TypeScript, Python, or Java to define your infrastructure.

Install

To get started, you'll need to install the CDK CLI globally.

sudo npm install -g aws-cdk

We can verify installation by checking CDK version

cdk --version
2.1025.0 (build 409f8e7)

Init

Let's create our AWS CDK FakeTube app. There is a quite good Tutorial: Create your first AWS CDK app provided by AWS, so don't hesitate to check it out for more details.

A CDK project should be in its own directory, with its own local module dependencies, so let's create and navigate to a faketube directory.

mkdir faketube && cd faketube

Create CDK project using cdk init command, specifying app template and typescript language.

cdk init app --language typescript

Name of the app is derived from the parent directory we just created (faketube), so that's great, but we want to have high level folder hierarchy like

web
mobile
cloud

so, let's rename that folder.

cd .. && mv faketube cloud && cd cloud

GitHub: feat(home): cdk init app (#7)

Stack

Our application, defined in cloud/bin/faketube.ts has a single stack, called FaketubeStack defined in cloud/lib/faketube-stack.ts.

Let's change it to a PascalCase naming convention and remove commented out example code, so that we have a clean, empty stack without any resource.

cloud/bin/faketube.ts (diff)

#!/usr/bin/env node
import * as cdk from "aws-cdk-lib";
-import { FaketubeStack } from "../lib/faketube-stack";
+import { FakeTubeStack } from "../lib/faketube-stack";

const app = new cdk.App();
-new FaketubeStack(app, "FaketubeStack", {
+new FakeTubeStack(app, "FakeTubeStack", {

cloud/lib/faketube-stack.ts (diff)

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
-// import * as sqs from 'aws-cdk-lib/aws-sqs';

-export class FaketubeStack extends cdk.Stack {
+export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
-
-   // The code that defines your stack goes here
-
-    // example resource
-    // const queue = new sqs.Queue(this, 'FaketubeQueue', {
-    //   visibilityTimeout: cdk.Duration.seconds(300)
-    // });
  }
}

cloud/lib/faketube-stack.ts

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
  }
}

Bootstrap

Before we deploy our stack, we will hve to run the cdk bootstrap command. This is a one-time operation per AWS account and region. It creates a special Amazon S3 bucket and an AWS Identity and Access Management (IAM) role that the CDK uses to deploy your resources.

cdk bootstrap

Simple Storage Service (S3)

Identity and Access Management (IAM)

Diff

Before deploying any changes, it's a great practice to run cdk diff. This command compares your local code with the deployed stack and shows you a preview of the changes that will be made. It's like a safety check to ensure you're not making any unintended modifications.

cdk diff

Our stack is empty, so the result is not very interesting at the moment, but it will be when we define some resource.

Deploy

Finally, to deploy your stack, you use the cdk deploy command. The CDK takes your code, synthesizes it into a CloudFormation template, and then deploys that template to your AWS account. This means CloudFormation is the underlying engine that actually provisions the resources, while CDK provides a much more intuitive and programmatic way to define them.

cdk deploy

CloudFormation

GitHub: feat(home): rename cdk stack (#7)

Database

Now that we've prepared our backend project, it's time to shift our focus to the database. For this part of the project, we'll start with a traditional and well-understood approach using a relational database (RDB). Our database of choice will be Amazon Aurora Serverless v2 with its PostgreSQL-compatible edition. This gives us a highly scalable and resilient database without the hassle of managing servers.

In a future article, we'll explore an alternative approach using a NoSQL database like DynamoDB. We'll compare the database modeling process, performance, and scalability to see how each solution fits different needs. For now, we'll stick with a relational model to establish a solid foundation for our data.

To begin, we'll first define our database schema using an Entity-Relationship Diagram (ERD). This will help us visualize the relationships between our data. Following this, we'll write the Data Definition Language (DDL) SQL syntax to create the structure of our database, specifically the channels and videos tables.

With our tables in place, the next step is to populate them. We'll prepare seed data (based on our already defined mock data) to ensure that we can fully test our new backend API. This will give us a realistic dataset to work with.

Next step will be to use our CDK project to create our Aurora Serverless v2 cluster and database in AWS, ensuring our entire infrastructure is defined as code.

Finally, we'll use the AWS CLI (Command Line Interface) to execute our SQL scripts, setting up our database tables directly and populating them. This will complete the database portion of our backend and get us ready to connect our API.

Schema

ERD (Entity Relationship Diagram)

First, let's define our database schema using a Mermaid ERD (Entity Relationship Diagram). This will give us a clear visual of our channels and videos tables and how they relate to each other.

For our columns, we'll use a VARCHAR data type with an arbitrary maximum length. For instance, a YouTube video ID is always 11 characters long, so we'll define that specifically. For the other columns, we'll choose reasonable default lengths to get started.

cloud/lib/aurora-erd.md

erDiagram
    channels {
        VARCHAR(30) id PK "Primary Key"
        VARCHAR(500) avatar "NOT NULL"
        VARCHAR(255) name "NOT NULL"
    }

    videos {
        VARCHAR(11) id PK "Primary Key"
        VARCHAR(100) title "NOT NULL"
        VARCHAR(500) thumbnail "NOT NULL"
        VARCHAR(20) duration "NOT NULL"
        VARCHAR(500) url "NOT NULL"
        TIMESTAMP published_at "NOT NULL"
        VARCHAR(30) channel_id FK "Foreign Key, NOT NULL"
    }

    channels ||--o{ videos : "has many"

It's worth noting a small technical detail I ran into: I initially tried to use the INTERVAL data type for the video duration, but it caused some issues with the AWS CLI based queries.

An error occurred (UnsupportedResultException) when calling the ExecuteStatement operation: The result contains the unsupported data type INTERVAL.

I plan to revisit this in the future, as there might be a workaround like adjusting the intervalstyle. For now, we'll use a simpler data type to keep things moving.

DDL (Data Definition Language)

We define the database schema using DDL statements split into separate files for each table. This approach is necessary because the aws rds-data execute-statement AWS CLI command (which we will use later) does not support multiple SQL statements in a single call. As a result, attempting to run a single schema file containing multiple CREATE TABLE statements will produce a ValidationException error.

An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.

By splitting the schema definition, we can execute each CREATE TABLE statement individually and avoid this error.

The cloud/lib/channels.schema.sql file defines the channels table:

CREATE TABLE channels (
    id VARCHAR(30) PRIMARY KEY,
    avatar VARCHAR(500) NOT NULL,
    name VARCHAR(255) NOT NULL    
);

The cloud/lib/videos.schema.sql file defines the videos table, including a foreign key constraint referencing the channels table:

CREATE TABLE videos (
    id VARCHAR(11) PRIMARY KEY,
    title VARCHAR(100) NOT NULL,    
    thumbnail VARCHAR(500) NOT NULL,
    duration VARCHAR(20) NOT NULL,
    url VARCHAR(500) NOT NULL,
    published_at TIMESTAMP WITH TIME ZONE NOT NULL,    
    channel_id VARCHAR(30) NOT NULL,

    CONSTRAINT fk_videos_channel_id 
        FOREIGN KEY (channel_id) 
        REFERENCES channels(id) 
        ON DELETE CASCADE
);

GitHub: feat(home): database schema (#7)

Seed

To populate our database with initial data for testing, we will use SQL based seed files. Similar to the DDL section, we split the seed data into separate files for each table.

The cloud/lib/channels.seed.sql file inserts the initial data for the channels table:

INSERT INTO channels (id, avatar, name) VALUES
('AmazonNovaReel', '/channels/AmazonNovaReel/AmazonNovaReel.png', 'Amazon Nova Reel');

The cloud/lib/videos.seed.sql file inserts the data for the videos table:

INSERT INTO videos (id, title, thumbnail, duration, url, published_at, channel_id) VALUES
('q9Gm7a6Wwjk', 'The Amazing World of Octopus!', '/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png', 'PT0M6.214542S', '/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.mp4', '2025-03-03T15:58:23Z', 'AmazonNovaReel'),
('QYUGZ3ueoHQ', 'Magic Wheels: The Future of Cars', '/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.png', 'PT0M6.047708S', '/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.mp4', '2025-03-03T14:22:54Z', 'AmazonNovaReel'),
('SkrDa20qGGo', 'Dancing Pets: A Fun Animal Show', '/videos/SkrDa20qGGo/SkrDa20qGGo.png', 'PT0M6.047708S', '/videos/SkrDa20qGGo/SkrDa20qGGo.mp4', '2025-03-04T15:13:16Z', 'AmazonNovaReel'),
('snI0xHnk9vw', 'Learning with Fun: The Magic of Numbers', '/videos/snI0xHnk9vw/snI0xHnk9vw.png', 'PT0M6.047708S', '/videos/snI0xHnk9vw/snI0xHnk9vw.mp4', '2025-03-04T15:53:08Z', 'AmazonNovaReel'),
('tO-6SL2drHA', 'Learning with Fun: The Magic of Science', '/videos/tO-6SL2drHA/tO-6SL2drHA.png', 'PT0M6.047708S', '/videos/tO-6SL2drHA/tO-6SL2drHA.mp4', '2025-03-04T16:10:52Z', 'AmazonNovaReel'),
('51KK6cQwqdo', 'Desert Motorcycle Adventure', '/videos/51KK6cQwqdo/51KK6cQwqdo.png', 'PT0M6.047708S', '/videos/51KK6cQwqdo/51KK6cQwqdo.mp4', '2025-03-04T16:37:57Z', 'AmazonNovaReel'),
('6Pz1MlphyvA', 'Amazing Soccer Tricks', '/videos/6Pz1MlphyvA/6Pz1MlphyvA.png', 'PT0M6.047708S', '/videos/6Pz1MlphyvA/6Pz1MlphyvA.mp4', '2025-03-04T16:54:19Z', 'AmazonNovaReel'),
('rX4LkHQLKSw', 'Tennis Magic: The Spin of Champions', '/videos/rX4LkHQLKSw/rX4LkHQLKSw.png', 'PT0M6.047708S', '/videos/rX4LkHQLKSw/rX4LkHQLKSw.mp4', '2025-03-04T17:12:16Z', 'AmazonNovaReel'),
('mYiQU9_bvAA', 'Mud Monster Truck Adventure', '/videos/mYiQU9_bvAA/mYiQU9_bvAA.png', 'PT0M6.047708S', '/videos/mYiQU9_bvAA/mYiQU9_bvAA.mp4', '2025-03-05T15:47:29Z', 'AmazonNovaReel'),
('1ccSDKMvpGA', 'Exploring the Magic of Motorhomes', '/videos/1ccSDKMvpGA/1ccSDKMvpGA.png', 'PT0M6.047708S', '/videos/1ccSDKMvpGA/1ccSDKMvpGA.mp4', '2025-03-05T16:01:54Z', 'AmazonNovaReel'),
('8ibeIVJKsYQ', 'Rocket Science: Blast Off!', '/videos/8ibeIVJKsYQ/8ibeIVJKsYQ.png', 'PT0M6.047708S', '/videos/8ibeIVJKsYQ/8ibeIVJKsYQ.mp4', '2025-03-05T16:20:43Z', 'AmazonNovaReel'),
('PcxHBLxkNuA', 'The Magic of Magnets', '/videos/PcxHBLxkNuA/PcxHBLxkNuA.png', 'PT0M6.047708S', '/videos/PcxHBLxkNuA/PcxHBLxkNuA.mp4', '2025-03-05T16:30:52Z', 'AmazonNovaReel'),
('j5az8g8QEZ4', 'Snail''s Slow and Steady Adventure', '/videos/j5az8g8QEZ4/j5az8g8QEZ4.png', 'PT0M6.047708S', '/videos/j5az8g8QEZ4/j5az8g8QEZ4.mp4', '2025-03-05T16:44:19Z', 'AmazonNovaReel'),
('j4aY8zGqcLQ', 'Rattlesnake''s Dance: A Wild Adventure', '/videos/j4aY8zGqcLQ/j4aY8zGqcLQ.png', 'PT0M6.047708S', '/videos/j4aY8zGqcLQ/j4aY8zGqcLQ.mp4', '2025-03-05T16:56:10Z', 'AmazonNovaReel'),
('ZG5ixKK6ABs', 'Classic Golf: The Art of the Swing', '/videos/ZG5ixKK6ABs/ZG5ixKK6ABs.png', 'PT0M6.047708S', '/videos/ZG5ixKK6ABs/ZG5ixKK6ABs.mp4', '2025-03-05T17:18:03Z', 'AmazonNovaReel'),
('cJanxpcCwq0', 'Retro Hockey: A Blast from the Past', '/videos/cJanxpcCwq0/cJanxpcCwq0.png', 'PT0M6.047708S', '/videos/cJanxpcCwq0/cJanxpcCwq0.mp4', '2025-03-05T17:34:12Z', 'AmazonNovaReel'),
('7qgegT-6tq8', 'Exploring Magical Festivals', '/videos/7qgegT-6tq8/7qgegT-6tq8.png', 'PT0M6.047708S', '/videos/7qgegT-6tq8/7qgegT-6tq8.mp4', '2025-03-06T15:15:29Z', 'AmazonNovaReel'),
('wCYxsFwXVAk', 'Adventure Awaits: Mountain Hiking', '/videos/wCYxsFwXVAk/wCYxsFwXVAk.png', 'PT0M6.047708S', '/videos/wCYxsFwXVAk/wCYxsFwXVAk.mp4', '2025-03-06T15:30:21Z', 'AmazonNovaReel'),
('aD5_u3q6KUM', 'City Adventure: Walking Tour', '/videos/aD5_u3q6KUM/aD5_u3q6KUM.png', 'PT0M6.047708S', '/videos/aD5_u3q6KUM/aD5_u3q6KUM.mp4', '2025-03-06T15:52:52Z', 'AmazonNovaReel'),
('aFwvWFVIUww', 'Live from the Big Conference!', '/videos/aFwvWFVIUww/aFwvWFVIUww.png', 'PT0M6.047708S', '/videos/aFwvWFVIUww/aFwvWFVIUww.mp4', '2025-03-06T16:06:33Z', 'AmazonNovaReel'),
('zGl4juMoUow', 'RTS Battle: Strategy in Action', '/videos/zGl4juMoUow/zGl4juMoUow.png', 'PT0M6.047708S', '/videos/zGl4juMoUow/zGl4juMoUow.mp4', '2025-03-06T16:20:51Z', 'AmazonNovaReel'),
('cCps60RZP4g', 'Retro Platformer Adventure', '/videos/cCps60RZP4g/cCps60RZP4g.png', 'PT0M6.047708S', '/videos/cCps60RZP4g/cCps60RZP4g.mp4', '2025-03-06T16:34:34Z', 'AmazonNovaReel'),
('LvQMMXWXOvE', 'Chess Showdown: The Ultimate Battle', '/videos/LvQMMXWXOvE/LvQMMXWXOvE.png', 'PT0M6.047708S', '/videos/LvQMMXWXOvE/LvQMMXWXOvE.mp4', '2025-03-06T16:54:22Z', 'AmazonNovaReel'),
('z-dBt8MpAnA', 'Chess Showdown: The Ultimate Battle', '/videos/z-dBt8MpAnA/z-dBt8MpAnA.png', 'PT0M6.047708S', '/videos/z-dBt8MpAnA/z-dBt8MpAnA.mp4', '2025-03-06T17:16:39Z', 'AmazonNovaReel'),
('k1DF_Rcan6M', 'Standing Up for Change: Peaceful Road Block', '/videos/k1DF_Rcan6M/k1DF_Rcan6M.png', 'PT0M6.047708S', '/videos/k1DF_Rcan6M/k1DF_Rcan6M.mp4', '2025-03-07T14:05:46Z', 'AmazonNovaReel'),
('SJOCLMEuoh0', 'Tree Guardians: Protecting Nature''s Champions', '/videos/SJOCLMEuoh0/SJOCLMEuoh0.png', 'PT0M6.047708S', '/videos/SJOCLMEuoh0/SJOCLMEuoh0.mp4', '2025-03-07T14:20:26Z', 'AmazonNovaReel'),
('M8V1FcKde2g', 'Street Volunteers: Collecting for a Cause', '/videos/M8V1FcKde2g/M8V1FcKde2g.png', 'PT0M6.047708S', '/videos/M8V1FcKde2g/M8V1FcKde2g.mp4', '2025-03-07T14:36:03Z', 'AmazonNovaReel'),
('saYIayqn6I0', 'Charity Run: Running Together for a Cause', '/videos/saYIayqn6I0/saYIayqn6I0.png', 'PT0M6.047708S', '/videos/saYIayqn6I0/saYIayqn6I0.mp4', '2025-03-07T14:48:26Z', 'AmazonNovaReel'),
('NzB9W_14tgE', 'Hair Magic: A Girl''s New Haircut', '/videos/NzB9W_14tgE/NzB9W_14tgE.png', 'PT0M6.047708S', '/videos/NzB9W_14tgE/NzB9W_14tgE.mp4', '2025-03-07T15:01:18Z', 'AmazonNovaReel'),
('RQmLNnELeFQ', 'Fashion Forward: Catwalk Chic', '/videos/RQmLNnELeFQ/RQmLNnELeFQ.png', 'PT0M6.047708S', '/videos/RQmLNnELeFQ/RQmLNnELeFQ.mp4', '2025-03-07T15:13:21Z', 'AmazonNovaReel'),
('8tS7B-c0b_8', 'Easy Soup Cooking Fun', '/videos/8tS7B-c0b_8/8tS7B-c0b_8.png', 'PT0M6.047708S', '/videos/8tS7B-c0b_8/8tS7B-c0b_8.mp4', '2025-03-07T15:42:59Z', 'AmazonNovaReel'),
('EoptO2hf3tY', 'How to Use a Yo Yo: Fun Tricks for Beginners', '/videos/EoptO2hf3tY/EoptO2hf3tY.png', 'PT0M6.047708S', '/videos/EoptO2hf3tY/EoptO2hf3tY.mp4', '2025-03-07T16:08:48Z', 'AmazonNovaReel');

GitHub: feat(home): database seed (#7)

Aurora

The database is a core component of our backend, and for this project, we're using Amazon Aurora Serverless v2. It's a version of Amazon's cloud-native relational database service that automatically scales capacity up and down. The one we're using is a PostgreSQL-compatible edition, meaning it works just like a standard PostgreSQL database, but with the added benefits of Aurora's high performance and scalability. To set all of this up, we'll use the Amazon Relational Database Service Construct Library.

cloud/lib/aurora.ts

import { Construct } from "constructs";
import * as cdk from "aws-cdk-lib";
import * as ec2 from "aws-cdk-lib/aws-ec2";
import * as rds from "aws-cdk-lib/aws-rds";
import * as secretsmanager from "aws-cdk-lib/aws-secretsmanager";

import { VPC } from "./vpc";

interface Props {
  vpc: VPC;
}

export class Aurora extends Construct {
  public readonly defaultName = "faketube";
  public readonly cluster: rds.DatabaseCluster;

  public get credentials(): secretsmanager.Secret {
    return this.cluster.node.children.filter(
      (child) => child instanceof rds.DatabaseSecret
    )[0] as rds.DatabaseSecret;
  }

  constructor(scope: Construct, id: string, { vpc }: Props) {
    super(scope, id);

    this.cluster = new rds.DatabaseCluster(this, "rds-database-cluster", {
      clusterIdentifier: this.defaultName,
      defaultDatabaseName: this.defaultName,
      engine: rds.DatabaseClusterEngine.auroraPostgres({
        version: rds.AuroraPostgresEngineVersion.VER_16_6,
      }),
      enableDataApi: true,
      vpc: vpc.vpc,
      vpcSubnets: {
        subnetType: ec2.SubnetType.PRIVATE_ISOLATED,
      },
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      writer: rds.ClusterInstance.serverlessV2("writer"),
      readers: [rds.ClusterInstance.serverlessV2("reader1")],
      serverlessV2MinCapacity: 0,
      serverlessV2MaxCapacity: 1,
      serverlessV2AutoPauseDuration: cdk.Duration.hours(0.5),
    });

    new cdk.CfnOutput(this, "AuroraClusterArn", {
      value: this.cluster.clusterArn,
    });

    new cdk.CfnOutput(this, "AuroraClusterSecretArn", {
      value: this.credentials.secretArn,
    });
  }
}

Let's look at some key properties and a few things about the code itself:

public get credentials()
It's a getter method which will give us credentials to our database cluster. We will need this later in the Lambda function which will query our database.

engine
This is where we specify the database engine. We're going with auroraPostgres and version 16.6, which gives us a PostgreSQL-compatible Aurora database.

enableDataApi
Enabling the Data API allows our applications to communicate with the database over HTTP, which is super helpful for serverless architectures like ours. No need to manage those pesky long-lived database connections!

removalPolicy
When we decide to tear down our CDK stack, this parameter tells AWS to also delete the database cluster and all its data. So it's perfect our experiments, but for the production environment we will have to change it to SNAPSHOT or RETAIN.

serverlessV2MinCapacity
serverlessV2MaxCapacity
serverlessV2AutoPauseDuration
These three properties work together to define the scaling behavior of the Aurora Serverless v2 cluster. Min/Max Capacity define the lower and upper bounds for the database's capacity, allowing it to automatically scale up to handle peak loads and scale down to save costs. We set Min Capacity to 0, which means that it will scale down to a complete idle state when there are no active connections or queries for Auto Pause Duration.

vpc
vpcSubnets

You must always launch a database in a VPC. Use the vpcSubnets attribute to control whether your instances will be launched privately or publicly

Without it we will get this error during deployment:

ValidationError: Provide either vpc or instanceProps.vpc, but not both

So, let's define it.

VPC

We will use a very basic VPC (Virtual Private Cloud), which is a logically isolated virtual network. Subnet type will be PRIVATE_ISOLATED, which

do not route from or to the Internet, and as such do not require NAT gateways. They can only connect to or be connected to from other instances in the same VPC

cloud/lib/vpc.ts

import { Construct } from "constructs";
import * as ec2 from "aws-cdk-lib/aws-ec2";

export class VPC extends Construct {
  public readonly vpc: ec2.Vpc;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.vpc = new ec2.Vpc(this, "vpc", {
      vpcName: "sitetube",
      createInternetGateway: false,
      subnetConfiguration: [
        {
          name: "aurora",
          subnetType: ec2.SubnetType.PRIVATE_ISOLATED,
          cidrMask: 24,
        },
      ],
    });
  }
}

Stack

Now, let's deploy the stack. We'll do this in two distinct steps to give us better control and visibility over the resources being created. First, we'll deploy our VPC, and then in the second step, we'll deploy the Aurora database cluster.

VPC

cloud/lib/faketube-stack.ts (diff)

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
+
+import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
+
+    new VPC(this, "vpc");
  }
}

cloud/lib/faketube-stack.ts

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new VPC(this, "vpc");
  }
}

cdk diff

cdk deploy

Aurora

cloud/lib/faketube-stack.ts (diff)

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

+import { Aurora } from "./aurora";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

-   new VPC(this, "vpc");
+   const vpc = new VPC(this, "vpc");
+   new Aurora(this, "aurora", { vpc });
  }
}

cloud/lib/faketube-stack.ts

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { Aurora } from "./aurora";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
    new Aurora(this, "aurora", { vpc });
  }
}

cdk diff

cdk deploy

During the CDK deployment we got this warning.

[Warning at /FakeTubeStack/aurora/rds-database-cluster] Cluster rds-database-cluster only has serverless readers and no reader is in promotion tier 0-1.Serverless readers in promotion tiers >= 2 will NOT scale with the writer, which can lead to availability issues if a failover event occurs. It is recommended that at least one reader has scaleWithWriter set to true [ack: @aws-cdk/aws-rds:noFailoverServerlessReaders]

Choosing the minimum Aurora Serverless v2 capacity setting for a cluster, gives some more context to that

If you have a DB cluster with Aurora Serverless v2 reader DB instances, the readers don't scale along with the writer DB instance when the promotion tier of the readers isn't 0 or 1. In that case, setting a low minimum capacity can result in excessive replication lag. That's because the readers might not have enough capacity to apply changes from the writer when the database is busy. We recommend that you set the minimum capacity to a value that represents a comparable amount of memory and CPU to the writer DB instance

As at the moment we are using our database only for reading data, we will ignore this issue for now, but we will come back to that later.

SQL

With our database now ready, the next step is to put our SQL scripts to work. We’ll use the AWS Command Line Interface (CLI) to execute our schema definitions and then seed the database with initial data. After these commands are run, we'll verify that everything is working correctly by sending a test query.

Outputs

With the infrastructure successfully deployed, the AWS Cloud Development Kit (CDK) provides us with key outputs from our stack. We'll use these values to define environment variables for subsequent AWS CLI commands.

✅  FakeTubeStack

✨  Deployment time: 25.05s

Outputs:
FakeTubeStack.auroraRdsArn4D18277C = arn:aws:rds:eu-west-1:091167074253:cluster:faketube
FakeTubeStack.auroraRdsSecretArnB6A3C5A0 = arn:aws:secretsmanager:eu-west-1:091167074253:secret:aurorardsdatabaseclusterSec-AD0YMbY5cBGY-tqs2K5

export FAKETUBE_AWS_AURORA_CLUSTER_ARN=arn:aws:rds:eu-west-1:091167074253:cluster:faketube
export FAKETUBE_AWS_AURORA_CLUSTER_SECRET_ARN=arn:aws:secretsmanager:eu-west-1:091167074253:secret:aurorardsdatabaseclusterSec-AD0YMbY5cBGY-tqs2K5
export FAKETUBE_AWS_AURORA_DATABASE_NAME=faketube

Schema

We can finally execute our Data Definition Language (DDL) scripts to create the database schema. When executing SQL statements using AWS CLI, we may encounter this error:

An error occurred (DatabaseResumingException) when calling the ExecuteStatement operation: The Aurora DB instance db-AQPANXFFWTE7LBPLXB63OKB3A4 is resuming after being auto-paused. Please wait a few seconds and try again.

It's self explanatory, just wait a few seconds for the database to resume.

Channels

aws rds-data execute-statement \
    --resource-arn $FAKETUBE_AWS_AURORA_CLUSTER_ARN \
    --secret-arn $FAKETUBE_AWS_AURORA_CLUSTER_SECRET_ARN \
    --database $FAKETUBE_AWS_AURORA_DATABASE_NAME \
    --sql "$(cat ./lib/channels.schema.sql)"

Result:

{
    "numberOfRecordsUpdated": 0,
    "generatedFields": []
}

Videos

aws rds-data execute-statement \
    --resource-arn $FAKETUBE_AWS_AURORA_CLUSTER_ARN \
    --secret-arn $FAKETUBE_AWS_AURORA_CLUSTER_SECRET_ARN \
    --database $FAKETUBE_AWS_AURORA_DATABASE_NAME \
    --sql "$(cat ./lib/videos.schema.sql)"

Result:

{
    "numberOfRecordsUpdated": 0,
    "generatedFields": []
}

Seed

Now that we've defined the database schema, the next step is to execute our seed statements to populate database with the initial data.

Channels

aws rds-data execute-statement \
    --resource-arn $FAKETUBE_AWS_AURORA_CLUSTER_ARN \
    --secret-arn $FAKETUBE_AWS_AURORA_CLUSTER_SECRET_ARN \
    --database $FAKETUBE_AWS_AURORA_DATABASE_NAME \
    --sql "$(cat ./lib/channels.seed.sql)"

Result:

{
    "numberOfRecordsUpdated": 1,
    "generatedFields": []
}

Videos

aws rds-data execute-statement \
    --resource-arn $FAKETUBE_AWS_AURORA_CLUSTER_ARN \
    --secret-arn $FAKETUBE_AWS_AURORA_CLUSTER_SECRET_ARN \
    --database $FAKETUBE_AWS_AURORA_DATABASE_NAME \
    --sql "$(cat ./lib/videos.seed.sql)"

Result:

{
    "numberOfRecordsUpdated": 32,
    "generatedFields": []
}

Query

To check that our schema and seed data were correctly deployed, we'll run a verification query. This test confirms the tables exist and contain the expected data, ensuring our database is ready to be used by the application.

lib/videos.query.sql

SELECT 
    v.*,
    c.name as channel_name,
    c.avatar as channel_avatar
FROM videos v
INNER JOIN channels c ON v.channel_id = c.id
ORDER BY v.published_at ASC
LIMIT 24 OFFSET 0;

aws rds-data execute-statement \
    --resource-arn $FAKETUBE_AWS_AURORA_CLUSTER_ARN \
    --secret-arn $FAKETUBE_AWS_AURORA_CLUSTER_SECRET_ARN \
    --database $FAKETUBE_AWS_AURORA_DATABASE_NAME \
    --sql "$(cat ./lib/videos.query.sql)"

Result:

{
    "records": [
        [
            {
                "stringValue": "QYUGZ3ueoHQ"
            },
            {
                "stringValue": "Magic Wheels: The Future of Cars"
            },
            {
                "stringValue": "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.png"
            },
            {
                "stringValue": "PT0M6.047708S"
            },
            {
                "stringValue": "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.mp4"
            },
            {
                "stringValue": "2025-03-03 14:22:54"
            },
            {
                "stringValue": "AmazonNovaReel"
            },
            {
                "stringValue": "Amazon Nova Reel"
            },
            {
                "stringValue": "/channels/AmazonNovaReel/AmazonNovaReel.png"
            }
        ],
        [
            {
                "stringValue": "q9Gm7a6Wwjk"
            },
            {
                "stringValue": "The Amazing World of Octopus!"
            },
            {
                "stringValue": "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png"
...

GitHub: feat(home): aurora (#7)

API

An API (Application Programming Interface) acts as a crucial bridge, allowing our web application to communicate with and access our backend services hosted on AWS. We will define this API using OpenAPI, a standardized way to describe RESTful APIs.

For this project, we will use Amazon API Gateway to create our API, focusing on both the HTTP and REST variants. While HTTP APIs are a simpler, faster, and more cost-effective option for building stateless APIs, REST APIs offer more features and control, such as API keys, request validation and AWS WAF integration.

Although you can use an OpenAPI definition to directly create an API Gateway:

we will not go that route this time.

Similarly, while there are ways to directly integrate API Gateway with other AWS services, we will instead use an AWS Lambda function as our backend.

To enhance our Lambda function, we'll leverage the Middy - Node.js middleware engine for AWS Lambda, which allows you to

Organise your Lambda code, remove code duplication, focus on business logic!

We'll also incorporate Powertools for AWS, a powerful developer toolkit designed to accelerate the adoption of serverless best practices. Our focus will be on leveraging its core features, including logging, tracing, and metrics, to enhance the visibility and operational health of our application.

Finally, to ensure our API functions correctly, we will test the entire setup using cURL, a powerful command-line tool for transferring data.

Schema

When building an API, it's essential to have a clear contract that defines how clients can interact with it. This is where the schema comes in. We are going to use OpenAPI (formerly Swagger) to define our API's structure in a YAML file.

While OpenAPI can be used for many things, like automatically generating client libraries and server stubs, for now, we will use it to achieve two main goals: to have a clear definition of what we are building and to test our API from the Swagger Editor. This approach helps us ensure consistency and provides a single source of truth for our API's structure.

Let's put our OpenAPI definition in the home feature folder.

cloud/lib/home/home.openapi.yaml

openapi: 3.0.3
info:
  title: FakeTube Home API
  version: 0.1.0
paths:
  /videos:
    get:
      summary: Retrieve a paginated list of videos
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 0
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 24
      responses:
        "200":
          description: The requested page of videos
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Page"
        "400":
          description: Bad request.
        "500":
          description: Server error.
components:
  schemas:
    Page:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Video"
        currentPage:
          type: integer
        hasNextPage:
          type: boolean
      example:
        items:
          - id: "q9Gm7a6Wwjk"
            title: "The Amazing World of Octopus!"
            thumbnail: "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png"
            duration: "PT0M6.214542S"
            url: "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.mp4"
            publishedAt: "2025-03-03T15:58:23Z"
            channel:
              id: "AmazonNovaReel"
              avatar: "/channels/AmazonNovaReel/AmazonNovaReel.png"
              name: "Amazon Nova Reel"
        currentPage: 0
        hasNextPage: true
    Video:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        url:
          type: string
          format: uri
        channel:
          $ref: "#/components/schemas/Channel"
        thumbnail:
          type: string
          format: uri
        duration:
          type: string
          format: duration
        publishedAt:
          type: string
          format: date-time
      example:
        id: "q9Gm7a6Wwjk"
        title: "The Amazing World of Octopus!"
        thumbnail: "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png"
        duration: "PT0M6.214542S"
        url: "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.mp4"
        publishedAt: "2025-03-03T15:58:23Z"
        channel:
          id: "AmazonNovaReel"
          avatar: "/channels/AmazonNovaReel/AmazonNovaReel.png"
          name: "Amazon Nova Reel"
    Channel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        avatar:
          type: string
          format: uri
      example:
        id: "AmazonNovaReel"
        avatar: "/channels/AmazonNovaReel/AmazonNovaReel.png"
        name: "Amazon Nova Reel"

To visualize this contract, you can simply copy and paste the content of our home.openapi.yaml file into the online Swagger Editor. The editor will instantly render an interactive, beautiful documentation page for the API.

GitHub: feat(home): openapi schema (#7)

API Gateway

We will now focus on the API Gateway, a core AWS service for creating and managing APIs. Just like before, our implementation will leverage the higher level AWS CDK Constructs, enabling us to easily define our API infrastructure programmatically.

This section will cover creating both REST and HTTP API versions, demonstrating their respective configurations.

We'll also cover crucial details like CORS, showing how it's configured within our code, and how the stack outputs are used to export the final API gateway URLs for easy access.

REST API

Let's start with the REST API version.

cloud/lib/gateway.ts

import * as apigw from "aws-cdk-lib/aws-apigateway";
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

export class Gateway extends Construct {
  public rest: apigw.RestApi;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.rest = new apigw.RestApi(this, "faketubeRest", {
      defaultCorsPreflightOptions: {
        allowHeaders: apigw.Cors.DEFAULT_HEADERS,
        allowMethods: ["GET", "OPTIONS"],
        allowOrigins: this.node.tryGetContext("corsOrigins") || [],
      },
    });

    new cdk.CfnOutput(this, "ApiGatewayRestUrlExport", {
      value: this.rest.url,
    });
  }
}

When we configure the defaultCorsPreflightOptions property, notice how we retrieve allowOrigins from the CDK context. This is a powerful feature that allows us to configure our API's behavior without changing the code itself.

Context values are a way to pass configuration settings, such as corsOrigins, into our CDK application from an external source like cdk.json. This makes our infrastructure flexible and reusable for different environments.

cloud/cdk.json (diff)

{
  "app": "npx ts-node --prefer-ts-exts bin/faketube.ts",
  "watch": {
    "include": ["**"],
    "exclude": [
      "README.md",
      "cdk*.json",
      "**/*.d.ts",
      "**/*.js",
      "tsconfig.json",
      "package*.json",
      "yarn.lock",
      "node_modules",
      "test"
    ]
  },
  "context": {
+   "corsOrigins": ["http://localhost:3000", "https://faketube.app"],
    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,

We specifically set the CORS origins to http://localhost:3000 and https://faketube.app to allow our frontend application (on development and production environments) to make requests to the API. The browser's same-origin policy would otherwise block these requests.

HTTP API

Now let's write the corresponding infrastructure code for the HTTP API version.

cloud/lib/gateway.ts (diff)

import * as apigw from "aws-cdk-lib/aws-apigateway";
+import * as apigwv2 from "aws-cdk-lib/aws-apigatewayv2";
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

export class Gateway extends Construct {
  public rest: apigw.RestApi;
+ public http: apigwv2.HttpApi;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.rest = new apigw.RestApi(this, "faketubeRest", {
      defaultCorsPreflightOptions: {
        allowHeaders: apigw.Cors.DEFAULT_HEADERS,
        allowMethods: ["GET", "OPTIONS"],
        allowOrigins: this.node.tryGetContext("corsOrigins") || [],
      },
    });

    new cdk.CfnOutput(this, "ApiGatewayRestUrlExport", {
      value: this.rest.url,
    });
+
+   this.http = new apigwv2.HttpApi(this, "faketubeHttp", {
+     corsPreflight: {
+       allowMethods: [
+         apigwv2.CorsHttpMethod.GET,
+         apigwv2.CorsHttpMethod.OPTIONS,
+       ],
+       allowOrigins: this.node.tryGetContext("corsOrigins") || [],
+     },
+   });
+
+   new cdk.CfnOutput(this, "ApiGatewayHttpUrlExport", {
+     value: this.http.url!,
+   });
  }
}

import * as apigw from "aws-cdk-lib/aws-apigateway";
import * as apigwv2 from "aws-cdk-lib/aws-apigatewayv2";
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

export class Gateway extends Construct {
  public rest: apigw.RestApi;
  public http: apigwv2.HttpApi;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.rest = new apigw.RestApi(this, "faketubeRest", {
      defaultCorsPreflightOptions: {
        allowHeaders: apigw.Cors.DEFAULT_HEADERS,
        allowMethods: ["GET", "OPTIONS"],
        allowOrigins: this.node.tryGetContext("corsOrigins") || [],
      },
    });

    new cdk.CfnOutput(this, "ApiGatewayRestUrlExport", {
      value: this.rest.url,
    });

    this.http = new apigwv2.HttpApi(this, "faketubeHttp", {
      corsPreflight: {
        allowMethods: [
          apigwv2.CorsHttpMethod.GET,
          apigwv2.CorsHttpMethod.OPTIONS,
        ],
        allowOrigins: this.node.tryGetContext("corsOrigins") || [],
      },
    });

    new cdk.CfnOutput(this, "ApiGatewayHttpUrlExport", {
      value: this.http.url!,
    });
  }
}

Stack

Next step is to create the Gateway construct in the stack.

cloud/lib/faketube-stack.ts (diff)

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { Aurora } from "./aurora";
+import { Gateway } from "./gateway";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
    new Aurora(this, "aurora", { vpc });
+   new Gateway(this, "gateway");
  }
}

cloud/lib/faketube-stack.ts

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { Aurora } from "./aurora";
import { Gateway } from "./gateway";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
    new Aurora(this, "aurora", { vpc });
    new Gateway(this, "gateway");
  }
}

Deploy

cdk diff

cdk deploy

 ✅  FakeTubeStack

✨  Deployment time: 30.21s

Outputs:
FakeTubeStack.auroraAuroraClusterArnC992B57D = arn:aws:rds:eu-west-1:091167074253:cluster:faketube
FakeTubeStack.auroraAuroraClusterSecretArn1DFC725B = arn:aws:secretsmanager:eu-west-1:091167074253:secret:aurorardsdatabaseclusterSec-AD0YMbY5cBGY-tqs2K5
FakeTubeStack.gatewayApiGatewayHttpUrlExport521087FD = https://po560wpeeg.execute-api.eu-west-1.amazonaws.com/
FakeTubeStack.gatewayApiGatewayRestUrlExport0DF633C7 = https://exzg8ug9ya.execute-api.eu-west-1.amazonaws.com/prod/
FakeTubeStack.gatewayfaketubeRestEndpointAA55D912 = https://exzg8ug9ya.execute-api.eu-west-1.amazonaws.com/prod/

We will need those outputs (API Gateway HTTP and REST URLs) later to test our API and for the frontend configuration. For now let's add them as an environment variables.

export FAKETUBE_AWS_API_GATEWAY_HTTP_URL=https://po560wpeeg.execute-api.eu-west-1.amazonaws.com
export FAKETUBE_AWS_API_GATEWAY_REST_URL=https://exzg8ug9ya.execute-api.eu-west-1.amazonaws.com/prod

GitHub: feat(home): api gateway (#7)

Home

Next, we'll build the Home CDK construct to tie everything together. This construct will define the API Gateway methods and integrate them with the Lambda function, which in turn will query our Aurora database.

cloud/lib/home/home.ts

import * as apigw from "aws-cdk-lib/aws-apigateway";
import * as path from "path";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as apigwv2 from "aws-cdk-lib/aws-apigatewayv2";
import { Construct } from "constructs";
import { HttpLambdaIntegration } from "aws-cdk-lib/aws-apigatewayv2-integrations";

import { Aurora } from "../aurora";
import { Gateway } from "../gateway";
import { Lambda } from "../lambda";

interface Props {
  aurora: Aurora;
  gateway: Gateway;
}

export class Home extends Construct {
  constructor(scope: Construct, id: string, { aurora, gateway }: Props) {
    super(scope, id);

    const listVideosLambda = new Lambda(this, "listVideos", {
      name: "listVideos",
      description: "Retrieve a paginated list of videos",
      entry: path.join(__dirname, "functions", "listVideos.lambda.ts"),
      environment: {
        SERVICE_NAME: "Home",
        LOG_LEVEL: "INFO",
        AURORA_SECRET_ARN: aurora.credentials.secretArn,
        AURORA_CLUSTER_ARN: aurora.cluster.clusterArn,
        AURORA_DATABASE_NAME: aurora.defaultName,
      },
    });
    aurora.cluster.grantDataApiAccess(listVideosLambda.function);

    this.rest(gateway.rest, listVideosLambda.function);
    this.http(gateway.http, listVideosLambda.function);
  }

  rest(rest: apigw.RestApi, handler: lambda.IFunction): void {
    const videos = rest.root.addResource("videos", {
      defaultCorsPreflightOptions: {
        allowHeaders: apigw.Cors.DEFAULT_HEADERS,
        allowMethods: ["GET", "OPTIONS"],
        allowOrigins: this.node.tryGetContext("corsOrigins") || [],
      },
    });

    videos.addMethod("GET", new apigw.LambdaIntegration(handler));
  }

  http(http: apigwv2.HttpApi, handler: lambda.IFunction): void {
    const integration = new HttpLambdaIntegration("VideosIntegration", handler);

    http.addRoutes({
      path: "/videos",
      methods: [apigwv2.HttpMethod.GET],
      integration,
    });
  }
}

cloud/lib/home/index.ts

export * from "./home";

Inside the Home constructor, we first instantiate our listVideos Lambda function, providing it with key environment variables like the AURORA_SECRET_ARN, AURORA_CLUSTER_ARN, and AURORA_DATABASE_NAME which are required to connect to our database. Following this, we explicitly grant the Lambda function Data API access to the Aurora cluster. This Lambda construct is our own wrapper, which we will discuss next.

Finally, we define both a REST and an HTTP API endpoint to integrate with our new Lambda. They both have GET method with /videos path, which will retrieve paginated list of videos.

Before we dive into the core of our backend — the Lambda function—let's first update our stack.

Stack

cloud/lib/faketube-stack.ts (diff)

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { Aurora } from "./aurora";
import { Gateway } from "./gateway";
+import { Home } from "./home";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
-   new Aurora(this, "aurora", { vpc });
-   new Gateway(this, "gateway");
+   const aurora = new Aurora(this, "aurora", { vpc });
+   const gateway = new Gateway(this, "gateway");
+
+   new Home(this, "home", {
+     aurora,
+     gateway,
+   });
  }
}

cloud/lib/faketube-stack.ts

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { Aurora } from "./aurora";
import { Gateway } from "./gateway";
import { Home } from "./home";
import { VPC } from "./vpc";

export class FakeTubeStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const vpc = new VPC(this, "vpc");
    const aurora = new Aurora(this, "aurora", { vpc });
    const gateway = new Gateway(this, "gateway");

    new Home(this, "home", {
      aurora,
      gateway,
    });
  }
}

Lambda

Helper

Now, let's take a quick detour to understand a custom Lambda construct we created. It serves as a helper class, simplifying the process of defining our AWS Lambda functions.

Instead of repeating the same configuration — like setting the runtime, architecture, and environment variables (e.g. CORS settings) — every time, we can reuse this single class. This approach keeps our code clean, readable, and DRY (Don't Repeat Yourself), making our project much easier to maintain as it grows.

cloud/lib/lambda.ts

import * as lambda from "aws-cdk-lib/aws-lambda";
import * as lambdaNode from "aws-cdk-lib/aws-lambda-nodejs";
import { Construct } from "constructs";

interface Props {
  name: string;
  description: string;
  entry: string;
  environment?: { [key: string]: string };
}

export class Lambda extends Construct {
  public function: lambda.IFunction;

  constructor(
    scope: Construct,
    id: string,
    { name, description, entry, environment: env }: Props
  ) {
    super(scope, id);

    const environment: { [key: string]: string } = {
      ...env,
      CORS_ORIGINS: JSON.stringify(
        this.node.tryGetContext("corsOrigins") || []
      ),
    };

    const lambdaFunction = new lambdaNode.NodejsFunction(
      this,
      `${name}Lambda`,
      {
        functionName: name,
        description: description,
        runtime: lambda.Runtime.NODEJS_LATEST,
        architecture: lambda.Architecture.ARM_64,
        entry,
        environment,
      }
    );

    this.function = lambdaFunction;
  }
}

Handler

It's time to build the core of our backend: the Lambda handler. This is the code that will actually process requests and talk to our database.

We'll start by installing the necessary dependencies, including esbuild for efficient bundling, the Middy middleware engine to keep our handler code clean, and Powertools for AWS Lambda to add observability and best practices out of the box.

Next, we'll model the data by creating channel, video, and page interfaces, which are very similar to the ones we built for the frontend. With our models in place, we'll write the initial handler boilerplate using Middy and Powertools. In this version, the handler will simply return an empty page of videos, allowing us to deploy and test the entire solution using cURL.

Finally, we'll integrate our Lambda with the Aurora database. We'll use the Data API Client to construct our SQL query and send it, enabling our API to retrieve real video data.

Dependencies

ESBuild

npm install --save-dev esbuild @types/aws-lambda

Middy

npm install @middy/core @middy/http-cors @middy/http-error-handler @middy/validator middy-env

Powertools for AWS

npm install @aws-lambda-powertools/logger @aws-lambda-powertools/metrics @aws-lambda-powertools/tracer

Models

cloud/lib/home/channel.ts

export interface Channel {
  id: string;
  avatar: string;
  name: string;
}

cloud/lib/home/video.ts

import { Channel } from "./channel";

export interface Video {
  id: string;
  title: string;
  thumbnail: string;
  duration: string;
  url: string;
  publishedAt: string;
  channel: Channel;
}

cloud/lib/home/page.ts

export interface Page<T> {
  items: T[];
  currentPage: number;
  hasNextPage: boolean;
}

Boilerplate

cloud/lib/home/functions/listVideos.lambda.ts

import cors from "@middy/http-cors";
import error from "@middy/http-error-handler";
const env = require("middy-env");
import middy from "@middy/core";
import validator from "@middy/validator";
import { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
import { captureLambdaHandler } from "@aws-lambda-powertools/tracer/middleware";
import { injectLambdaContext } from "@aws-lambda-powertools/logger/middleware";
import { Logger } from "@aws-lambda-powertools/logger";
import { LogLevel } from "@aws-lambda-powertools/logger/types";
import { logMetrics } from "@aws-lambda-powertools/metrics/middleware";
import { Metrics } from "@aws-lambda-powertools/metrics";
import { Tracer } from "@aws-lambda-powertools/tracer";
import { transpileSchema } from "@middy/validator/transpile";

import { Video } from "../video";
import { Page } from "../page";

const serviceName = process.env.SERVICE_NAME!;
const logLevel = (process.env.LOG_LEVEL || "ERROR") as LogLevel;
const corsOrigins = process.env.CORS_ORIGINS || "[]";

const metrics = new Metrics({ namespace: serviceName });
const logger = new Logger({ logLevel, serviceName });
const tracer = new Tracer({ serviceName });

export const lambdaHandler = async (
  event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  try {
    console.log("event", JSON.stringify(event));

    const queryParams = event.queryStringParameters || {};
    const currentPage = Math.max(parseInt(queryParams.page || "0"), 0);
    const pageSize = Math.min(parseInt(queryParams.pageSize || "24"), 64);

    const page: Page<Video> = {
      items: [],
      currentPage,
      hasNextPage: false,
    };

    return {
      statusCode: 200,
      body: JSON.stringify(page),
    };
  } catch (e: any) {
    console.error(e);
    return {
      statusCode: 500,
      body: JSON.stringify({
        message: "Internal Server Error",
        error: e.message,
      }),
    };
  }
};

const envMap = {
  names: {
    serviceName: ["SERVICE_NAME"],
    logLevel: ["LOG_LEVEL"],
    corsOrigins: ["CORS_ORIGINS"],
  },
};

const eventSchema = {
  type: "object",
  properties: {
    queryStringParameters: {
      type: ["object", "null"],
      properties: {
        page: {
          type: "string",
          pattern: "^[0-9]+$",
        },
        pageSize: {
          type: "string",
          pattern: "^[1-9][0-9]*$",
        },
      },
      additionalProperties: true,
    },
  },
};

export const handler = middy(lambdaHandler)
  .use(captureLambdaHandler(tracer))
  .use(logMetrics(metrics, { captureColdStartMetric: true }))
  .use(injectLambdaContext(logger, { logEvent: true }))
  .use(env(envMap))
  .use(validator({ eventSchema: transpileSchema(eventSchema) }))
  .use(
    cors({
      origins: JSON.parse(corsOrigins),
      methods: "GET,OPTIONS",
    })
  )
  .use(
    error({ logger: (message) => logger.error("http-error-handler", message) })
  );

While this might look like a lot of initial boilerplate, it's the foundation that makes our handler robust and maintainable. This is where we leverage a few key tools to build a production-ready function:

AWS Powertools for Lambda provides essential observability, giving us a logger that outputs structured JSON, a tracer for AWS X-Ray integration, and the ability to generate custom metrics.
Middy handles the surrounding concerns of our handler, offering powerful features like request validation.

This setup prevents many common runtime issues. If we, for instance, forget to set the LOG_LEVEL environment variable in our cloud/lib/home/home.ts file, the handler will fail early and inform us with a precise error:

Environment variable LOG_LEVEL is missing

export class Home extends Construct {
  constructor(scope: Construct, id: string, { aurora, gateway }: Props) {
    super(scope, id);

    const listVideosLambda = new Lambda(this, "listVideos", {
      name: "listVideos",
      description: "Retrieve a paginated list of videos",
      entry: path.join(__dirname, "functions", "listVideos.lambda.ts"),
      environment: {
        SERVICE_NAME: "Home",
-       LOG_LEVEL: "INFO",
        AURORA_SECRET_ARN: aurora.credentials.secretArn,
        AURORA_CLUSTER_ARN: aurora.cluster.clusterArn,
        AURORA_DATABASE_NAME: aurora.defaultName,
      },
    });
    aurora.cluster.grantDataApiAccess(listVideosLambda.function);

{
   "level":"ERROR",
   "message":"http-error-handler",
   "timestamp":"2025-08-20T11:01:27.800Z",
   "service":"Home",
   "cold_start":false,
   "function_arn":"arn:aws:lambda:eu-west-1:091167074253:function:listVideos",
   "function_memory_size":"128",
   "function_name":"listVideos",
   "function_request_id":"61e5b153-428a-4da1-bfc0-43072d8b251c",
   "sampling_rate":0,
   "xray_trace_id":"1-68a5ab07-6703de0b26b65bfb3c9f845d",
   "error":{
      "name":"ReferenceError",
      "location":"/var/task/index.js:18728",
      "message":"Environment variable LOG_LEVEL is missing",
      "stack":"ReferenceError: Environment variable LOG_LEVEL is missing\n at getEnvVar (/var/task/index.js:18728:13)\n at /var/task/index.js:18736:18\n at Array.reduce (<anonymous>)\n at getEnvVars (/var/task/index.js:18732:30)\n at before (/var/task/index.js:18756:59)\n at runMiddlewares (/var/task/index.js:19282:23)\n at async runRequest (/var/task/index.js:19226:5)\n at async Runtime.middy2 [as handler] (/var/task/index.js:19167:22)"
   }

Similarly, if a user sends a request with an invalid page value, such as x, Middy's validation layer will catch it and provide a clear, helpful error message:

must match pattern "^[0-9]+$".

curl -s "$FAKETUBE_AWS_API_GATEWAY_HTTP_URL/videos?page=x" | jq .

{
   "level":"ERROR",
   "message":"http-error-handler",
   "timestamp":"2025-08-20T11:43:13.203Z",
   "service":"Home",
   "cold_start":false,
   "function_arn":"arn:aws:lambda:eu-west-1:091167074253:function:listVideos",
   "function_memory_size":"128",
   "function_name":"listVideos",
   "function_request_id":"89499ff7-968c-4c8f-8a54-9588193cb1ac",
   "sampling_rate":0,
   "xray_trace_id":"1-68a5b4d1-4e7cf58929088c2a7e4e1e29",
   "error":{
      "name":"BadRequestError",
      "location":"/var/task/index.js:18820",
      "message":"Event object failed validation",
      "stack":"BadRequestError: Event object failed validation\n at createError (/var/task/index.js:18820:10)\n at validatorMiddlewareBefore (/var/task/index.js:19317:15)\n at async runMiddlewares (/var/task/index.js:19282:17)\n at async runRequest (/var/task/index.js:19226:5)\n at async Runtime.middy2 [as handler] (/var/task/index.js:19167:22)",
      "cause":{
         "package":"@middy/validator",
         "data":[
            {
               "instancePath":"/queryStringParameters/page",
               "schemaPath":"#/properties/queryStringParameters/properties/page/pattern",
               "keyword":"pattern",
               "params":{
                  "pattern":"^[0-9]+$"
               },
               "message":"must match pattern \"^[0-9]+$\""
            }
         ]
      },
      "statusCode":400,
      "status":400,
      "expose":true
   }
}

Let's quickly deploy our stack (cdk deploy) and do some testing using cURL.

REST API

curl -s "$FAKETUBE_AWS_API_GATEWAY_REST_URL/videos" | jq .

Result:

{
  "items": [],
  "currentPage": 0,
  "hasNextPage": false
}

HTTP API

curl -s "$FAKETUBE_AWS_API_GATEWAY_HTTP_URL/videos?page=3" | jq .

Response:

{
  "items": [],
  "currentPage": 3,
  "hasNextPage": false
}

GitHub: feat(home): list videos lambda (#7)

Database

With the API Gateway and Lambda function in place, the final piece of our puzzle is integration with the Aurora database. We will now focus on connecting our handler to the database to execute SQL query.

First, we'll install a new dependency, the Data API Client, which will allow us to easily interact with our Aurora database.

Next, we'll update our Lambda handler to use this client to execute a SQL query. After coding the changes, we'll deploy our updated solution.

Finally, we'll test again our API using cURL.

Dependencies

npm install data-api-client@2.0.0-beta.0

Handler

cloud/lib/home/function/listVideos.lambda.ts (diff)

import cors from "@middy/http-cors";
import error from "@middy/http-error-handler";
const env = require("middy-env");
import middy from "@middy/core";
import validator from "@middy/validator";
import { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
import { captureLambdaHandler } from "@aws-lambda-powertools/tracer/middleware";
import { injectLambdaContext } from "@aws-lambda-powertools/logger/middleware";
import { Logger } from "@aws-lambda-powertools/logger";
import { LogLevel } from "@aws-lambda-powertools/logger/types";
import { logMetrics } from "@aws-lambda-powertools/metrics/middleware";
import { Metrics } from "@aws-lambda-powertools/metrics";
import { Tracer } from "@aws-lambda-powertools/tracer";
import { transpileSchema } from "@middy/validator/transpile";

+const db = require("data-api-client")({
+  secretArn: process.env.AURORA_SECRET_ARN,
+  resourceArn: process.env.AURORA_CLUSTER_ARN,
+  database: process.env.AURORA_DATABASE_NAME,
+});

import { Video } from "../video";
import { Page } from "../page";

const serviceName = process.env.SERVICE_NAME!;
const logLevel = (process.env.LOG_LEVEL || "ERROR") as LogLevel;
const corsOrigins = process.env.CORS_ORIGINS || "[]";

const metrics = new Metrics({ namespace: serviceName });
const logger = new Logger({ logLevel, serviceName });
const tracer = new Tracer({ serviceName });

export const lambdaHandler = async (
  event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  try {
    console.log("event", JSON.stringify(event));

    const queryParams = event.queryStringParameters || {};
    const currentPage = Math.max(parseInt(queryParams.page || "0"), 0);
    const pageSize = Math.min(parseInt(queryParams.pageSize || "24"), 64);
+
+   const limit = pageSize;
+   const offset = currentPage * pageSize;
+
+   const result = await db.query(
+     `
+       SELECT 
+           v.*,
+           c.name as channel_name,
+           c.avatar as channel_avatar,
+           count(*) OVER() AS total
+       FROM videos v
+       INNER JOIN channels c ON v.channel_id = c.id
+       ORDER BY v.published_at ASC
+       LIMIT :limit
+       OFFSET :offset;
+     `,
+     [
+       {
+         name: "limit",
+         value: limit,
+       },
+       {
+         name: "offset",
+         value: offset,
+       },
+     ]
+   );
+
+   const videos = result.records.map((r: VideoRecord) => ({
+     id: r.id,
+     title: r.title,
+     thumbnail: r.thumbnail,
+     duration: r.duration,
+     url: r.url,
+     publishedAt: r.published_at,
+     channel: {
+       id: r.channel_id,
+       name: r.channel_name,
+       avatar: r.channel_avatar,
+     },
+   }));
+
+   const total = result.records?.[0]?.total || 0;
+   const totalPages = Math.ceil(total / pageSize);
+   const hasNextPage = currentPage < totalPages - 1;
+
    const page: Page<Video> = {
-     items: [],
+     items: videos,
      currentPage,
-     hasNextPage: false
+     hasNextPage
    };

    return {
      statusCode: 200,
      body: JSON.stringify(page),
    };
  } catch (e: any) {
    console.error(e);
    return {
      statusCode: 500,
      body: JSON.stringify({
        message: "Internal Server Error",
        error: e.message,
      }),
    };
  }
};

+interface VideoRecord {
+  id: string;
+  title: string;
+  thumbnail: string;
+  duration: string;
+  url: string;
+  published_at: string;
+  channel_id: string;
+  channel_name: string;
+  channel_avatar: string;
+  total: number;
+}

const envMap = {
  names: {
    serviceName: ["SERVICE_NAME"],
    logLevel: ["LOG_LEVEL"],
    corsOrigins: ["CORS_ORIGINS"],
  },
};

const eventSchema = {
  type: "object",
  properties: {
    queryStringParameters: {
      type: ["object", "null"],
      properties: {
        page: {
          type: "string",
          pattern: "^[0-9]+$",
        },
        pageSize: {
          type: "string",
          pattern: "^[1-9][0-9]*$",
        },
      },
      additionalProperties: true,
    },
  },
};

export const handler = middy(lambdaHandler)
  .use(captureLambdaHandler(tracer))
  .use(logMetrics(metrics, { captureColdStartMetric: true }))
  .use(injectLambdaContext(logger, { logEvent: true }))
  .use(env(envMap))
  .use(validator({ eventSchema: transpileSchema(eventSchema) }))
  .use(
    cors({
      origins: JSON.parse(corsOrigins),
      methods: "GET,OPTIONS",
    })
  )
  .use(
    error({ logger: (message) => logger.error("http-error-handler", message) })
  );

import cors from "@middy/http-cors";
import error from "@middy/http-error-handler";
const env = require("middy-env");
import middy from "@middy/core";
import validator from "@middy/validator";
import { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
import { captureLambdaHandler } from "@aws-lambda-powertools/tracer/middleware";
import { injectLambdaContext } from "@aws-lambda-powertools/logger/middleware";
import { Logger } from "@aws-lambda-powertools/logger";
import { LogLevel } from "@aws-lambda-powertools/logger/types";
import { logMetrics } from "@aws-lambda-powertools/metrics/middleware";
import { Metrics } from "@aws-lambda-powertools/metrics";
import { Tracer } from "@aws-lambda-powertools/tracer";
import { transpileSchema } from "@middy/validator/transpile";

const db = require("data-api-client")({
  secretArn: process.env.AURORA_SECRET_ARN,
  resourceArn: process.env.AURORA_CLUSTER_ARN,
  database: process.env.AURORA_DATABASE_NAME,
});

import { Video } from "../video";
import { Page } from "../page";

const serviceName = process.env.SERVICE_NAME!;
const logLevel = (process.env.LOG_LEVEL || "ERROR") as LogLevel;
const corsOrigins = process.env.CORS_ORIGINS || "[]";

const metrics = new Metrics({ namespace: serviceName });
const logger = new Logger({ logLevel, serviceName });
const tracer = new Tracer({ serviceName });

export const lambdaHandler = async (
  event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  try {
    console.log("event", JSON.stringify(event));

    const queryParams = event.queryStringParameters || {};
    const currentPage = Math.max(parseInt(queryParams.page || "0"), 0);
    const pageSize = Math.min(parseInt(queryParams.pageSize || "24"), 64);

    const limit = pageSize;
    const offset = currentPage * pageSize;

    const result = await db.query(
      `
       SELECT 
           v.*,
           c.name as channel_name,
           c.avatar as channel_avatar,
           count(*) OVER() AS total
       FROM videos v
       INNER JOIN channels c ON v.channel_id = c.id
       ORDER BY v.published_at ASC
       LIMIT :limit
       OFFSET :offset;
     `,
      [
        {
          name: "limit",
          value: limit,
        },
        {
          name: "offset",
          value: offset,
        },
      ]
    );

    const videos = result.records.map((r: VideoRecord) => ({
      id: r.id,
      title: r.title,
      thumbnail: r.thumbnail,
      duration: r.duration,
      url: r.url,
      publishedAt: r.published_at,
      channel: {
        id: r.channel_id,
        name: r.channel_name,
        avatar: r.channel_avatar,
      },
    }));

    const total = result.records?.[0]?.total || 0;
    const totalPages = Math.ceil(total / pageSize);
    const hasNextPage = currentPage < totalPages - 1;

    const page: Page<Video> = {
      items: videos,
      currentPage,
      hasNextPage,
    };

    return {
      statusCode: 200,
      body: JSON.stringify(page),
    };
  } catch (e: any) {
    console.error(e);
    return {
      statusCode: 500,
      body: JSON.stringify({
        message: "Internal Server Error",
        error: e.message,
      }),
    };
  }
};

interface VideoRecord {
  id: string;
  title: string;
  thumbnail: string;
  duration: string;
  url: string;
  published_at: string;
  channel_id: string;
  channel_name: string;
  channel_avatar: string;
  total: number;
}

const envMap = {
  names: {
    serviceName: ["SERVICE_NAME"],
    logLevel: ["LOG_LEVEL"],
    corsOrigins: ["CORS_ORIGINS"],
  },
};

const eventSchema = {
  type: "object",
  properties: {
    queryStringParameters: {
      type: ["object", "null"],
      properties: {
        page: {
          type: "string",
          pattern: "^[0-9]+$",
        },
        pageSize: {
          type: "string",
          pattern: "^[1-9][0-9]*$",
        },
      },
      additionalProperties: true,
    },
  },
};

export const handler = middy(lambdaHandler)
  .use(captureLambdaHandler(tracer))
  .use(logMetrics(metrics, { captureColdStartMetric: true }))
  .use(injectLambdaContext(logger, { logEvent: true }))
  .use(env(envMap))
  .use(validator({ eventSchema: transpileSchema(eventSchema) }))
  .use(
    cors({
      origins: JSON.parse(corsOrigins),
      methods: "GET,OPTIONS",
    })
  )
  .use(
    error({ logger: (message) => logger.error("http-error-handler", message) })
  );

Test

cURL

After deployment (cdk deploy), let's do some cURL testing.

REST API

curl -s "$FAKETUBE_AWS_API_GATEWAY_REST_URL/videos?page=0&pageSize=2" | jq .

Result:

{
  "items": [
    {
      "id": "QYUGZ3ueoHQ",
      "title": "Magic Wheels: The Future of Cars",
      "thumbnail": "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.png",
      "duration": "PT0M6.047708S",
      "url": "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.mp4",
      "publishedAt": "2025-03-03T14:22:54.000Z",
      "channel": {
        "id": "AmazonNovaReel",
        "name": "Amazon Nova Reel",
        "avatar": "/channels/AmazonNovaReel/AmazonNovaReel.png"
      }
    },
    {
      "id": "q9Gm7a6Wwjk",
      "title": "The Amazing World of Octopus!",
      "thumbnail": "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png",
      "duration": "PT0M6.214542S",
      "url": "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.mp4",
      "publishedAt": "2025-03-03T15:58:23.000Z",
      "channel": {
        "id": "AmazonNovaReel",
        "name": "Amazon Nova Reel",
        "avatar": "/channels/AmazonNovaReel/AmazonNovaReel.png"
      }
    }
  ],
  "currentPage": 0,
  "hasNextPage": true
}

HTTP API

curl -s "$FAKETUBE_AWS_API_GATEWAY_HTTP_URL/videos?page=3&pageSize=10" | jq .

Response:

{
  "items": [
    {
      "id": "8tS7B-c0b_8",
      "title": "Easy Soup Cooking Fun",
      "thumbnail": "/videos/8tS7B-c0b_8/8tS7B-c0b_8.png",
      "duration": "PT0M6.047708S",
      "url": "/videos/8tS7B-c0b_8/8tS7B-c0b_8.mp4",
      "publishedAt": "2025-03-07T15:42:59.000Z",
      "channel": {
        "id": "AmazonNovaReel",
        "name": "Amazon Nova Reel",
        "avatar": "/channels/AmazonNovaReel/AmazonNovaReel.png"
      }
    },
    {
      "id": "EoptO2hf3tY",
      "title": "How to Use a Yo Yo: Fun Tricks for Beginners",
      "thumbnail": "/videos/EoptO2hf3tY/EoptO2hf3tY.png",
      "duration": "PT0M6.047708S",
      "url": "/videos/EoptO2hf3tY/EoptO2hf3tY.mp4",
      "publishedAt": "2025-03-07T16:08:48.000Z",
      "channel": {
        "id": "AmazonNovaReel",
        "name": "Amazon Nova Reel",
        "avatar": "/channels/AmazonNovaReel/AmazonNovaReel.png"
      }
    }
  ],
  "currentPage": 3,
  "hasNextPage": false
}

Swagger

In order to test our API in the Swagger Editor we have to change two things.

Add API Gateway URLs (REST and HTTP) as servers to the OpenAPI specification
Add https://editor.swagger.io/ as an allowed CORS origin.

cloud/lib/home/home.openapi.yaml

openapi: 3.0.3
info:
  title: FakeTube Home API
  version: 0.1.0
+servers:
+  - url: https://exzg8ug9ya.execute-api.eu-west-1.amazonaws.com/prod
+    description: REST
+  - url: https://po560wpeeg.execute-api.eu-west-1.amazonaws.com
+    description: HTTP
paths:
  /videos:
...

cloud/cdk.json (diff)

{
  "app": "npx ts-node --prefer-ts-exts bin/faketube.ts",
  "watch": {
    "include": ["**"],
    "exclude": [
      "README.md",
      "cdk*.json",
      "**/*.d.ts",
      "**/*.js",
      "tsconfig.json",
      "package*.json",
      "yarn.lock",
      "node_modules",
      "test"
    ]
  },
  "context": {
-   "corsOrigins": ["http://localhost:3000", "https://faketube.app"],
+   "corsOrigins": [
+     "http://localhost:3000",
+     "https://faketube.app",
+     "https://editor.swagger.io"
+   ],
    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,

After deploying (cdk deploy) those changes, we can select one of the servers e.g. REST and click Execute button.

GitHub: feat(home): aurora integration (#7)

Frontend

Now, let's turn our attention to the frontend, where we'll bring our API to life. We'll begin by configuring the Amplify library to work seamlessly with our backend and integrate with Next.js. We'll start by installing the aws-amplify dependency. Then, we'll create the amplify-configuration.ts file, which will pull essential values from environment variables defined in .env file. This configuration will also include our custom NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH variable, allowing us to switch between our REST and HTTP API variants or a mock implementation. Finally, we'll initialize this configuration within our providers.tsx file using a dedicated ConfigureAmplifyClientSide.tsx component.

Next, we'll enhance our existing useListVideos hook. We'll introduce a new fetchApi function that uses Amplify's get function to make requests to our API Gateway endpoint, allowing us to seamlessly integrate our new backend logic.

Finally, we'll test both API versions by simply toggling the NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH environment variable. We can see our home page grid populate with live data and verify the network requests in Chrome DevTools.

Amplify

Dependencies

cd .../web
npm install aws-amplify

Configuration

web/amplify-configuration.ts

import { ResourcesConfig } from "aws-amplify";

export const config: ResourcesConfig = {
  API: {
    REST: {
      faketubeHttp: {
        region: process.env.NEXT_PUBLIC_FAKETUBE_AWS_REGION!,
        endpoint:
          process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_ENDPOINT!,
      },
      faketubeRest: {
        region: process.env.NEXT_PUBLIC_FAKETUBE_AWS_REGION!,
        endpoint:
          process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_ENDPOINT!,
      },
    },
  },
};

export default config;

web/.env

NEXT_PUBLIC_FAKETUBE_AWS_REGION=eu-west-1
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_ENDPOINT=https://exzg8ug9ya.execute-api.eu-west-1.amazonaws.com/prod
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_NAME=faketubeRest
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_ENDPOINT=https://po560wpeeg.execute-api.eu-west-1.amazonaws.com
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_NAME=faketubeHttp

# mock | rest | http
NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH=mock

Before we forget, let's also open AWS Console and update environment variables in Amplify Hosting, so that they will be used with the next build.

Client

web/utils/ConfigureAmplifyClientSide.tsx

"use client";

import { Amplify } from "aws-amplify";

import amplifyConfig from "@/amplify-configuration";

Amplify.configure(amplifyConfig, { ssr: true });

export function ConfigureAmplifyClientSide({
  children,
}: {
  children: React.ReactNode;
}) {
  return children;
}

web/utils/index.ts

export * from "./ConfigureAmplifyClientSide";

web/app/providers.tsx

"use client";

import CssBaseline from "@mui/material/CssBaseline";
import { AppRouterCacheProvider } from "@mui/material-nextjs/v15-appRouter";
import { ThemeProvider } from "@mui/material/styles";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

import theme from "./theme";
+import { ConfigureAmplifyClientSide } from "@/utils";

const queryClient = new QueryClient();

export function Providers({
  children,
  deviceType,
}: Readonly<{
  children: React.ReactNode;
  deviceType: string;
}>) {
  return (
+     <ConfigureAmplifyClientSide>
        <AppRouterCacheProvider>
          <QueryClientProvider client={queryClient}>
            <ThemeProvider theme={theme(deviceType)}>
              <CssBaseline />
              {children}
            </ThemeProvider>
          </QueryClientProvider>
        </AppRouterCacheProvider>
+     </ConfigureAmplifyClientSide>
  );
}

Hook

web/app/Home/useListVideos.tsx (diff)

+import { get } from "aws-amplify/api";
import { useInfiniteQuery } from "@tanstack/react-query";

import { Page } from "./pagination";
import { Video } from "./video";
import { VIDEOS } from "./videos.data";

export const PAGE_SIZE = 24;
const DELAY_MS = 1000;

-const fetch = async (
+const fetchMock = async (
  currentPage: number,
  pageSize: number = PAGE_SIZE
): Promise<Page<Video>> => {
  await new Promise((resolve) => setTimeout(resolve, DELAY_MS));

  const start = currentPage * pageSize;
  const end = start + pageSize;

  return {
    items: VIDEOS.slice(start, end),
    currentPage,
    hasNextPage: end < VIDEOS.length,
  };
};

+enum ApiType {
+  MOCK = "mock",
+  REST = "rest",
+  HTTP = "http",
+}

+const getApiName = (): string => {
+  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
+    case ApiType.REST:
+      return process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_NAME!;
+    case ApiType.HTTP:
+      return process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_NAME!;
+    default:
+      throw new Error("Invalid API switch configuration");
+  }
+};

+const fetchApi = async (
+  currentPage: number,
+  pageSize: number = PAGE_SIZE
+): Promise<Page<Video>> => {
+  try {
+    const restOperation = get({
+      apiName: getApiName(),
+      path: "/videos",
+      options: {
+        queryParams: {
+          page: currentPage.toString(),
+          pageSize: pageSize.toString(),
+        },
+      },
+    });
+
+    const { body } = await restOperation.response;
+    const response = await body.json();
+
+    console.log("Response from API:", response);
+
+    const page = response as unknown as Page<Video>;
+
+    return page;
+  } catch (error) {
+    console.error("Error fetching videos:", error);
+    return {
+      items: [],
+      currentPage,
+      hasNextPage: false,
+    };
+  }
+};

export const useListVideos = () => {
  return useInfiniteQuery({
    queryKey: ["listVideos"],
-   queryFn: ({ pageParam: page }) => fetch(page),
+   queryFn: ({ pageParam: page }) =>
+     process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH === ApiType.MOCK
+       ? fetchMock(page)
+       : fetchApi(page),
    initialPageParam: 0,
    getNextPageParam: (lastPage) =>
      lastPage.hasNextPage ? lastPage.currentPage + 1 : undefined,
  });
};

import { get } from "aws-amplify/api";
import { useInfiniteQuery } from "@tanstack/react-query";

import { Page } from "./pagination";
import { Video } from "./video";
import { VIDEOS } from "./videos.data";

export const PAGE_SIZE = 24;
const DELAY_MS = 1000;

const fetchMock = async (
  currentPage: number,
  pageSize: number = PAGE_SIZE
): Promise<Page<Video>> => {
  await new Promise((resolve) => setTimeout(resolve, DELAY_MS));

  const start = currentPage * pageSize;
  const end = start + pageSize;

  return {
    items: VIDEOS.slice(start, end),
    currentPage,
    hasNextPage: end < VIDEOS.length,
  };
};

enum ApiType {
  MOCK = "mock",
  REST = "rest",
  HTTP = "http",
}

const getApiName = (): string => {
  switch (process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH) {
    case ApiType.REST:
      return process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_REST_NAME!;
    case ApiType.HTTP:
      return process.env.NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_NAME!;
    default:
      throw new Error("Invalid API switch configuration");
  }
};

const fetchApi = async (
  currentPage: number,
  pageSize: number = PAGE_SIZE
): Promise<Page<Video>> => {
  try {
    const restOperation = get({
      apiName: getApiName(),
      path: "/videos",
      options: {
        queryParams: {
          page: currentPage.toString(),
          pageSize: pageSize.toString(),
        },
      },
    });

    const { body } = await restOperation.response;
    const response = await body.json();

    console.log("Response from API:", response);

    const page = response as unknown as Page<Video>;

    return page;
  } catch (error) {
    console.error("Error fetching videos:", error);
    return {
      items: [],
      currentPage,
      hasNextPage: false,
    };
  }
};

export const useListVideos = () => {
  return useInfiniteQuery({
    queryKey: ["listVideos"],
    queryFn: ({ pageParam: page }) =>
      process.env.NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH === ApiType.MOCK
        ? fetchMock(page)
        : fetchApi(page),
    initialPageParam: 0,
    getNextPageParam: (lastPage) =>
      lastPage.hasNextPage ? lastPage.currentPage + 1 : undefined,
  });
};

Test

REST API

web/.env

...
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_NAME=faketubeHttp

# mock | rest | http
-NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH=mock
+NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH=rest

HTTP API

web/.env

...
NEXT_PUBLIC_FAKETUBE_AWS_API_GATEWAY_HTTP_NAME=faketubeHttp

# mock | rest | http
-NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH=rest
+NEXT_PUBLIC_FAKETUBE_API_TYPE_SWITCH=http

GitHub: feat(home): backend integration using amplify (#7)

Trademark Notice

It turns out that FakeTube is an already registered trademark. I started a rebranding process, but it will take a while.

Home Page using Next.js, Material UI, TanStack Query - FakeTube #4

Jacek Kościesza — Tue, 29 Jul 2025 08:13:17 +0000

Let's add a video content to our YouTube clone. In the last episode we created a static app shell with a basic branding and navigation. It's time to create a more dynamic part - home page with a responsive grid of media items.

We will start with a loading skeleton during data fetching phase. When the data are loaded we will display a beautiful thumbnail with all the needed video and channel metadata.

We will also implement some more advanced things like infinite scroll using TanStack Query and React Intersection Observer, as well as an inline media media player.

Last but not least, we will introduce a bonus section, where we will be doing some improvements, small experiments and bug fixes. This time we will fix a small bug related to the masthead position.

Media Skeleton

Skeleton is a placeholder preview of your content, displayed before the data gets loaded.

In our case it shows the basic layout of the media item with a thumbnail, channel avatar and metadata sections.

web/app/Home/MediaSkeleton/MediaSkeleton.tsx

import Box from "@mui/material/Box";
import Stack from "@mui/material/Stack";
import Skeleton from "@mui/material/Skeleton";
import Typography from "@mui/material/Typography";

interface Props {
  animation?: "wave" | "pulse" | false;
}

export function MediaSkeleton({ animation = false }: Props) {
  return (
    <Stack spacing={1.5}>
      <Skeleton
        variant="rectangular"
        animation={animation}
        sx={{
          borderRadius: 3,
          height: "inherit",
          aspectRatio: "16 / 9",
        }}
      />
      <Stack direction="row" spacing={1}>
        <Box>
          <Skeleton
            variant="circular"
            width={36}
            height={36}
            animation={animation}
          />
        </Box>
        <Stack width="100%">
          <Typography variant="subtitle1">
            <Skeleton variant="text" width="100%" animation={animation} />
          </Typography>
          <Typography variant="subtitle2">
            <Skeleton variant="text" width="50%" animation={animation} />
          </Typography>
        </Stack>
      </Stack>
    </Stack>
  );
}

web/app/Home/MediaSkeleton/index.ts

export * from "./MediaSkeleton";

Home Page

Let's create a dedicated HomePage component and use it on our default page.

We will use our MediaSkeleton to show a data loading state of our home page. Let's create an array of media skeletons and display them. You will notice that we delegated the task of creating grid layout to another component called BrowseGrid.

web/app/Home/HomePage.tsx

import { BrowseGrid } from "./BrowseGrid";
import { MediaSkeleton } from "./MediaSkeleton";

const PAGE_SIZE = 24;

export function HomePage() {
  const skeleton = (
    <>
      {Array.from({ length: PAGE_SIZE }).map((_, index) => (
        <MediaSkeleton key={index} />
      ))}
    </>
  );

  return <BrowseGrid>{skeleton}</BrowseGrid>;
}

web/app/Home/index.tsx

export * from "./HomePage";

web/app/page.tsx (diff)

-import Typography from "@mui/material/Typography";
+import { HomePage } from "./Home";

export default function Home() {
-  return (
-    <Typography component="h2" variant="h4">
-      TODO: Home Page
-    </Typography>
-  );
+  return <HomePage />;
}

Browse Grid

Grid is a responsive layout that adapts to screen size and orientation.

We will use it to display our media skeletons and items and ensure that the number of columns adopts to the screen resolution.

You might have noticed that we are not passing an array of skeletons directly, but rather encapsulated in a single <> (Fragment) element. It makes it harder to iterate over, but increases our component's flexibility.

To make our lives easier, we will use react-keyed-flatten-children library

it will flatten nested arrays and React.Fragments into a regular, one-dimensional array while ensuring element and fragment keys are preserved, unique, and stable between renders.

Let's install that library and its dependencies

npm install react-keyed-flatten-children react-is@19

web/app/Home/BrowseGrid/BrowseGrid.tsx

import * as React from "react";
import Grid from "@mui/material/Grid";
import flattenChildren from "react-keyed-flatten-children";

interface Props {
  children: React.ReactNode;
}

export function BrowseGrid({ children }: Props) {
  return (
    <Grid container rowSpacing={4} columnSpacing={2}>
      {React.Children.map(flattenChildren(children), (child) => (
        <Grid size={{ xs: 12, sm: 6, md: 6, lg: 3, xl: 3, xxl: 3, xxxl: 3 }}>
          {child}
        </Grid>
      ))}
    </Grid>
  );
}

web/app/Home/BrowseGrid/index.ts

export * from "./BrowseGrid";

The final result looks like this

GitHub: feat(home): browse grid, media skeleton (#7)

Data

Before we display the grid of media items, we have to define our data models (video and channels) and create mock data.

Data models

web/app/Home/video.ts

import { Channel } from "./channel";

export interface Video {
  id: string;
  title: string;
  thumbnail: string;
  duration: string;
  url: string;
  publishedAt: string;
  channel: Channel;
}

web/app/Home/channel.ts

export interface Channel {
  id: string;
  avatar: string;
  name: string;
}

Mock data

All the mock data are based on the content generated by AI in the Generative AI Videos using Bedrock, Polly, iMovie - FakeTube #2 episode. Because we uploaded all of the generated videos to the YouTube, we can use metadata like id and publishedAt directly from there. Finally we will copy channel avatar, video thumbnails and files to the Next.js public directory.

web/app/Home/channels.data.ts

import { Channel } from "./channel";

export const CHANNELS: Channel[] = [
  {
    id: "AmazonNovaReel",
    avatar: "/channels/AmazonNovaReel/AmazonNovaReel.png",
    name: "Amazon Nova Reel",
  },
];

web/app/Home/videos.data.ts

import { CHANNELS } from "./channels.data";
import { Video } from "./video";

const channel = CHANNELS[0];

export const VIDEOS: Video[] = [
  {
    id: "q9Gm7a6Wwjk",
    title: "The Amazing World of Octopus!",
    thumbnail: "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.png",
    duration: "PT0M6.214542S",
    url: "/videos/q9Gm7a6Wwjk/q9Gm7a6Wwjk.mp4",
    publishedAt: "2025-03-03T15:58:23Z",
    channel,
  },
  {
    id: "QYUGZ3ueoHQ",
    title: "Magic Wheels: The Future of Cars",
    thumbnail: "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.png",
    duration: "PT0M6.047708S",
    url: "/videos/QYUGZ3ueoHQ/QYUGZ3ueoHQ.mp4",
    publishedAt: "2025-03-03T14:22:54Z",
    channel,
  },
  {
    id: "SkrDa20qGGo",
    title: "Dancing Pets: A Fun Animal Show",
    thumbnail: "/videos/SkrDa20qGGo/SkrDa20qGGo.png",
    duration: "PT0M6.047708S",
    url: "/videos/SkrDa20qGGo/SkrDa20qGGo.mp4",
    publishedAt: "2025-03-04T15:13:16Z",
    channel,
  },
  {
    id: "snI0xHnk9vw",
    title: "Learning with Fun: The Magic of Numbers",
    thumbnail: "/videos/snI0xHnk9vw/snI0xHnk9vw.png",
    duration: "PT0M6.047708S",
    url: "/videos/snI0xHnk9vw/snI0xHnk9vw.mp4",
    publishedAt: "2025-03-04T15:53:08Z",
    channel,
  },
  {
    id: "tO-6SL2drHA",
    title: "Learning with Fun: The Magic of Science",
    thumbnail: "/videos/tO-6SL2drHA/tO-6SL2drHA.png",
    duration: "PT0M6.047708S",
    url: "/videos/tO-6SL2drHA/tO-6SL2drHA.mp4",
    publishedAt: "2025-03-04T16:10:52Z",
    channel,
  },
  {
    id: "51KK6cQwqdo",
    title: "Desert Motorcycle Adventure",
    thumbnail: "/videos/51KK6cQwqdo/51KK6cQwqdo.png",
    duration: "PT0M6.047708S",
    url: "/videos/51KK6cQwqdo/51KK6cQwqdo.mp4",
    publishedAt: "2025-03-04T16:37:57Z",
    channel,
  },
  {
    id: "6Pz1MlphyvA",
    title: "Amazing Soccer Tricks",
    thumbnail: "/videos/6Pz1MlphyvA/6Pz1MlphyvA.png",
    duration: "PT0M6.047708S",
    url: "/videos/6Pz1MlphyvA/6Pz1MlphyvA.mp4",
    publishedAt: "2025-03-04T16:54:19Z",
    channel,
  },
  {
    id: "rX4LkHQLKSw",
    title: "Tennis Magic: The Spin of Champions",
    thumbnail: "/videos/rX4LkHQLKSw/rX4LkHQLKSw.png",
    duration: "PT0M6.047708S",
    url: "/videos/rX4LkHQLKSw/rX4LkHQLKSw.mp4",
    publishedAt: "2025-03-04T17:12:16Z",
    channel,
  },
  {
    id: "mYiQU9_bvAA",
    title: "Mud Monster Truck Adventure",
    thumbnail: "/videos/mYiQU9_bvAA/mYiQU9_bvAA.png",
    duration: "PT0M6.047708S",
    url: "/videos/mYiQU9_bvAA/mYiQU9_bvAA.mp4",
    publishedAt: "2025-03-05T15:47:29Z",
    channel,
  },
  {
    id: "1ccSDKMvpGA",
    title: "Exploring the Magic of Motorhomes",
    thumbnail: "/videos/1ccSDKMvpGA/1ccSDKMvpGA.png",
    duration: "PT0M6.047708S",
    url: "/videos/1ccSDKMvpGA/1ccSDKMvpGA.mp4",
    publishedAt: "2025-03-05T16:01:54Z",
    channel,
  },
  {
    id: "8ibeIVJKsYQ",
    title: "Rocket Science: Blast Off!",
    thumbnail: "/videos/8ibeIVJKsYQ/8ibeIVJKsYQ.png",
    duration: "PT0M6.047708S",
    url: "/videos/8ibeIVJKsYQ/8ibeIVJKsYQ.mp4",
    publishedAt: "2025-03-05T16:20:43Z",
    channel,
  },
  {
    id: "PcxHBLxkNuA",
    title: "The Magic of Magnets",
    thumbnail: "/videos/PcxHBLxkNuA/PcxHBLxkNuA.png",
    duration: "PT0M6.047708S",
    url: "/videos/PcxHBLxkNuA/PcxHBLxkNuA.mp4",
    publishedAt: "2025-03-05T16:30:52Z",
    channel,
  },
  {
    id: "j5az8g8QEZ4",
    title: "Snail's Slow and Steady Adventure",
    thumbnail: "/videos/j5az8g8QEZ4/j5az8g8QEZ4.png",
    duration: "PT0M6.047708S",
    url: "/videos/j5az8g8QEZ4/j5az8g8QEZ4.mp4",
    publishedAt: "2025-03-05T16:44:19Z",
    channel,
  },
  {
    id: "j4aY8zGqcLQ",
    title: "Rattlesnake's Dance: A Wild Adventure",
    thumbnail: "/videos/j4aY8zGqcLQ/j4aY8zGqcLQ.png",
    duration: "PT0M6.047708S",
    url: "/videos/j4aY8zGqcLQ/j4aY8zGqcLQ.mp4",
    publishedAt: "2025-03-05T16:56:10Z",
    channel,
  },
  {
    id: "ZG5ixKK6ABs",
    title: "Classic Golf: The Art of the Swing",
    thumbnail: "/videos/ZG5ixKK6ABs/ZG5ixKK6ABs.png",
    duration: "PT0M6.047708S",
    url: "/videos/ZG5ixKK6ABs/ZG5ixKK6ABs.mp4",
    publishedAt: "2025-03-05T17:18:03Z",
    channel,
  },
  {
    id: "cJanxpcCwq0",
    title: "Retro Hockey: A Blast from the Past",
    thumbnail: "/videos/cJanxpcCwq0/cJanxpcCwq0.png",
    duration: "PT0M6.047708S",
    url: "/videos/cJanxpcCwq0/cJanxpcCwq0.mp4",
    publishedAt: "2025-03-05T17:34:12Z",
    channel,
  },
  {
    id: "7qgegT-6tq8",
    title: "Exploring Magical Festivals",
    thumbnail: "/videos/7qgegT-6tq8/7qgegT-6tq8.png",
    duration: "PT0M6.047708S",
    url: "/videos/7qgegT-6tq8/7qgegT-6tq8.mp4",
    publishedAt: "2025-03-06T15:15:29Z",
    channel,
  },
  {
    id: "wCYxsFwXVAk",
    title: "Adventure Awaits: Mountain Hiking",
    thumbnail: "/videos/wCYxsFwXVAk/wCYxsFwXVAk.png",
    duration: "PT0M6.047708S",
    url: "/videos/wCYxsFwXVAk/wCYxsFwXVAk.mp4",
    publishedAt: "2025-03-06T15:30:21Z",
    channel,
  },
  {
    id: "aD5_u3q6KUM",
    title: "City Adventure: Walking Tour",
    thumbnail: "/videos/aD5_u3q6KUM/aD5_u3q6KUM.png",
    duration: "PT0M6.047708S",
    url: "/videos/aD5_u3q6KUM/aD5_u3q6KUM.mp4",
    publishedAt: "2025-03-06T15:52:52Z",
    channel,
  },
  {
    id: "aFwvWFVIUww",
    title: "Live from the Big Conference!",
    thumbnail: "/videos/aFwvWFVIUww/aFwvWFVIUww.png",
    duration: "PT0M6.047708S",
    url: "/videos/aFwvWFVIUww/aFwvWFVIUww.mp4",
    publishedAt: "2025-03-06T16:06:33Z",
    channel,
  },
  {
    id: "zGl4juMoUow",
    title: "RTS Battle: Strategy in Action",
    thumbnail: "/videos/zGl4juMoUow/zGl4juMoUow.png",
    duration: "PT0M6.047708S",
    url: "/videos/zGl4juMoUow/zGl4juMoUow.mp4",
    publishedAt: "2025-03-06T16:20:51Z",
    channel,
  },
  {
    id: "cCps60RZP4g",
    title: "Retro Platformer Adventure",
    thumbnail: "/videos/cCps60RZP4g/cCps60RZP4g.png",
    duration: "PT0M6.047708S",
    url: "/videos/cCps60RZP4g/cCps60RZP4g.mp4",
    publishedAt: "2025-03-06T16:34:34Z",
    channel,
  },
  {
    id: "LvQMMXWXOvE",
    title: "Chess Showdown: The Ultimate Battle",
    thumbnail: "/videos/LvQMMXWXOvE/LvQMMXWXOvE.png",
    duration: "PT0M6.047708S",
    url: "/videos/LvQMMXWXOvE/LvQMMXWXOvE.mp4",
    publishedAt: "2025-03-06T16:54:22Z",
    channel,
  },
  {
    id: "z-dBt8MpAnA",
    title: "Chess Showdown: The Ultimate Battle",
    thumbnail: "/videos/z-dBt8MpAnA/z-dBt8MpAnA.png",
    duration: "PT0M6.047708S",
    url: "/videos/z-dBt8MpAnA/z-dBt8MpAnA.mp4",
    publishedAt: "2025-03-06T17:16:39Z",
    channel,
  },
  {
    id: "k1DF_Rcan6M",
    title: "Standing Up for Change: Peaceful Road Block",
    thumbnail: "/videos/k1DF_Rcan6M/k1DF_Rcan6M.png",
    duration: "PT0M6.047708S",
    url: "/videos/k1DF_Rcan6M/k1DF_Rcan6M.mp4",
    publishedAt: "2025-03-07T14:05:46Z",
    channel,
  },
  {
    id: "SJOCLMEuoh0",
    title: "Tree Guardians: Protecting Nature's Champions",
    thumbnail: "/videos/SJOCLMEuoh0/SJOCLMEuoh0.png",
    duration: "PT0M6.047708S",
    url: "/videos/SJOCLMEuoh0/SJOCLMEuoh0.mp4",
    publishedAt: "2025-03-07T14:20:26Z",
    channel,
  },
  {
    id: "M8V1FcKde2g",
    title: "Street Volunteers: Collecting for a Cause",
    thumbnail: "/videos/M8V1FcKde2g/M8V1FcKde2g.png",
    duration: "PT0M6.047708S",
    url: "/videos/M8V1FcKde2g/M8V1FcKde2g.mp4",
    publishedAt: "2025-03-07T14:36:03Z",
    channel,
  },
  {
    id: "saYIayqn6I0",
    title: "Charity Run: Running Together for a Cause",
    thumbnail: "/videos/saYIayqn6I0/saYIayqn6I0.png",
    duration: "PT0M6.047708S",
    url: "/videos/saYIayqn6I0/saYIayqn6I0.mp4",
    publishedAt: "2025-03-07T14:48:26Z",
    channel,
  },
  {
    id: "NzB9W_14tgE",
    title: "Hair Magic: A Girl's New Haircut",
    thumbnail: "/videos/NzB9W_14tgE/NzB9W_14tgE.png",
    duration: "PT0M6.047708S",
    url: "/videos/NzB9W_14tgE/NzB9W_14tgE.mp4",
    publishedAt: "2025-03-07T15:01:18Z",
    channel,
  },
  {
    id: "RQmLNnELeFQ",
    title: "Fashion Forward: Catwalk Chic",
    thumbnail: "/videos/RQmLNnELeFQ/RQmLNnELeFQ.png",
    duration: "PT0M6.047708S",
    url: "/videos/RQmLNnELeFQ/RQmLNnELeFQ.mp4",
    publishedAt: "2025-03-07T15:13:21Z",
    channel,
  },
  {
    id: "8tS7B-c0b_8",
    title: "Easy Soup Cooking Fun",
    thumbnail: "/videos/8tS7B-c0b_8/8tS7B-c0b_8.png",
    duration: "PT0M6.047708S",
    url: "/videos/8tS7B-c0b_8/8tS7B-c0b_8.mp4",
    publishedAt: "2025-03-07T15:42:59Z",
    channel,
  },
  {
    id: "EoptO2hf3tY",
    title: "How to Use a Yo Yo: Fun Tricks for Beginners",
    thumbnail: "/videos/EoptO2hf3tY/EoptO2hf3tY.png",
    duration: "PT0M6.047708S",
    url: "/videos/EoptO2hf3tY/EoptO2hf3tY.mp4",
    publishedAt: "2025-03-07T16:08:48Z",
    channel,
  },
];

web
├── public
│   ├── channels
│   │   ├── AmazonNovaReel
│   │   │   ├── AmazonNovaReel.png
│   ├── vidoes
│   │   ├── q9Gm7a6Wwjk
│   │   │   ├── q9Gm7a6Wwjk.png
│   │   │   ├── q9Gm7a6Wwjk.mp4
│   │   ├── QYUGZ3ueoHQ
│   │   │   ├── QYUGZ3ueoHQ.png
│   │   │   ├── QYUGZ3ueoHQ.mp4
|   ├── ...
| ...

GitHub: feat(home): mock data (#7)

Media Item

Let's shift our focus to the most important component, which will represent video on the home page, that is Media Item. It will consist of the two main parts: Video Thumbnail and Video Details.

web/app/Home/MediaItem/MediaItem.tsx

import Box from "@mui/material/Box";

import { Video } from "../video";
import { VideoDetails } from "./VideoDetails";
import { VideoThumbnail } from "./VideoThumbnail";

interface Props {
  video: Video;
}

export function MediaItem({ video }: Props) {
  return (
    <Box
      sx={{
        width: "100%",
        mb: 2,
        display: "block",
        aspectRatio: "16 / 9",
      }}
    >
      <VideoThumbnail video={video} />
      <VideoDetails video={video} />
    </Box>
  );
}

web/app/Home/MediaItem/index.tsx

export * from "./MediaItem";

Video Thumbnail

This component will obviously show an image representation of our video, which is called a thumbnail.

Additionally it should display the duration of the video in the bottom-right corner. We will extract this functionality to a Time Status component.

web/app/Home/MediaItem/VideoThumbnail/VideoThumbnail.tsx

import Box from "@mui/material/Box";

import { Video } from "../../video";
import { TimeStatus } from "../TimeStatus";

interface Props {
  video: Video;
}

export function VideoThumbnail({ video }: Props) {
  return (
    <Box
      sx={{
        width: "100%",
        height: "100%",
        position: "relative",
        mb: 1.5,
      }}
    >
      <Box
        component="img"
        alt=""
        src={video.thumbnail}
        sx={{
          borderRadius: 3,
          aspectRatio: "16 / 9",
          maxWidth: "100%",
          display: "block",
          objectFit: "cover",
        }}
      />
      <TimeStatus time={video.duration} />
    </Box>
  );
}

web/app/Home/MediaItem/VideoThumbnail/index.tsx

export * from "./VideoThumbnail";

Time Status

It's a slightly customized Chip component. We will have to convert ISO_8601 duration format into human readable format like 0:07. We can easily do that with the Luxon library.

Let's first install needed dependencies

npm install luxon
npm i --save-dev @types/luxon

web/app/Home/MediaItem/TimeStatus/TimeStatus.tsx

"use client";

import * as React from "react";
import Chip from "@mui/material/Chip";
import { Duration } from "luxon";

interface Props {
  time: string;
}

export function TimeStatus({ time }: Props) {
  const duration: string = React.useMemo(() => {
    const seconds = Duration.fromISO(time).as("seconds");
    return Duration.fromObject({ seconds: Math.ceil(seconds) }).toFormat(
      "m:ss"
    );
  }, [time]);

  return (
    <Chip
      size="small"
      label={duration}
      sx={{
        position: "absolute",
        bottom: (theme) => theme.spacing(1.5),
        right: (theme) => theme.spacing(1),
        borderRadius: 1,
        color: "white",
        fontWeight: 600,
        backgroundColor: "#00000099",
        ".MuiChip-label": {
          padding: 0.5,
        },
      }}
    />
  );
}

web/app/Home/MediaItem/TimeStatus/index.tsx

export * from "./TimeStatus";

Video Details

The second part of the MediaItem component is responsible for displaying video and channel metadata like channel avatar and name, video title and publish date. There is some work related to its layout, plus we will have to convert the video publish date to a more convenient relative format like 1 month ago. The good news is that we can also do that using Luxon.

web/app/Home/MediaItem/VideoDetails/VideoDetails.tsx

"use client";

import * as React from "react";
import Avatar from "@mui/material/Avatar";
import Box from "@mui/material/Box";
import Stack from "@mui/material/Stack";
import Tooltip from "@mui/material/Tooltip";
import Typography from "@mui/material/Typography";
import { DateTime } from "luxon";

import { Video } from "../../video";

interface Props {
  video: Video;
}

export function VideoDetails({ video }: Props) {
  const date: string | null = React.useMemo(
    () =>
      DateTime.fromISO(video.publishedAt).toRelative({
        unit: ["years", "months", "weeks", "days"],
      }),
    [video.publishedAt]
  );

  return (
    <Box sx={{ display: "flex", alignItems: "flex-start" }}>
      <Avatar
        src={video.channel.avatar}
        alt={video.channel.name}
        sx={{
          width: (theme) => theme.spacing(4.5),
          height: (theme) => theme.spacing(4.5),
          marginRight: (theme) => theme.spacing(1),
        }}
      />
      <Stack>
        <Typography
          variant="subtitle2"
          component="h3"
          fontSize={16}
          gutterBottom
          mb={0.5}
        >
          {video.title}
        </Typography>
        <Stack>
          <Tooltip
            title={video.channel.name}
            placement="top"
            disableInteractive
          >
            <Typography
              variant="caption"
              fontSize={14}
              sx={{
                color: "#606060",
                "&:hover": {
                  color: (theme) => theme.palette.text.primary,
                },
              }}
            >
              {video.channel.name}
            </Typography>
          </Tooltip>
        </Stack>

        <Typography
          variant="caption"
          fontSize={14}
          sx={{
            color: "#606060",
          }}
        >
          {date}
        </Typography>
      </Stack>
    </Box>
  );
}

web/app/Home/MediaItem/VideoDetails/index.tsx

export * from "./VideoDetails";

Home Page

The media item component is ready, so it's time to use it on our home page. When loading is done (for now we will just mock it using loading variable which is set to false), we will pass array of MediaItems based on our mock data to the BrowseGrid;

web/app/Home/HomePage.tsx (diff)

import { BrowseGrid } from "./BrowseGrid";
+import { MediaItem } from "./MediaItem";
import { MediaSkeleton } from "./MediaSkeleton";
+import { VIDEOS } from "./videos.data";

const PAGE_SIZE = 24;

export function HomePage() {
+ const loading = false;

  const skeleton = (
    <>
      {Array.from({ length: PAGE_SIZE }).map((_, index) => (
        <MediaSkeleton key={index} />
      ))}
    </>
  );

- return <BrowseGrid>{skeleton}</BrowseGrid>;
+  return (
+    <BrowseGrid>
+      {loading ? (
+        skeleton
+      ) : (
+        <>
+         {VIDEOS.map((video) => (
+           <MediaItem video={video} key={video.id} />
+         ))}
+       </>
+      )}
+    </BrowseGrid>
+  );
}

web/app/Home/HomePage.tsx

import { BrowseGrid } from "./BrowseGrid";
import { MediaItem } from "./MediaItem";
import { MediaSkeleton } from "./MediaSkeleton";
import { VIDEOS } from "./videos.data";

const PAGE_SIZE = 24;

export function HomePage() {
  const loading = false;

  const skeleton = (
    <>
      {Array.from({ length: PAGE_SIZE }).map((_, index) => (
        <MediaSkeleton key={index} />
      ))}
    </>
  );

  return (
    <BrowseGrid>
      {loading ? (
        skeleton
      ) : (
        <>
          {VIDEOS.map((video) => (
            <MediaItem video={video} key={video.id} />
          ))}
        </>
      )}
    </BrowseGrid>
  );
}

GitHub: feat(home): media item (#8)

Fetching data

So far we just directly rendered our mock data on the home page. In the next episodes we will store data in the database and build an API to fetch them. What we can do right now is to prepare frontend for scenario like that, but still return mock data from web/app/Home/videos.data.ts. We will use TansStack Query for that. It's asynchronous state management library, which provides very handy abstraction layer for operations like that, including infinite queries.

Setup

TansStack Query provides quite good installation and quick start documentation.

Let's install the needed dependency and configure the query client provider.

npm install @tanstack/react-query

web/app/providers.tsx (diff)

"use client";

import CssBaseline from "@mui/material/CssBaseline";
import { AppRouterCacheProvider } from "@mui/material-nextjs/v15-appRouter";
import { ThemeProvider } from "@mui/material/styles";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

import { theme } from "./theme";

+const queryClient = new QueryClient();

export function Providers({
  children,
  deviceType,
}: Readonly<{
  children: React.ReactNode;
  deviceType: string;
}>) {
  return (
    <AppRouterCacheProvider>
+     <QueryClientProvider client={queryClient}>
        <ThemeProvider theme={theme(deviceType)}>
          <CssBaseline />
          {children}
        </ThemeProvider>
+     </QueryClientProvider>
    </AppRouterCacheProvider>
  );
}

web/app/providers.tsx

"use client";

import CssBaseline from "@mui/material/CssBaseline";
import { AppRouterCacheProvider } from "@mui/material-nextjs/v15-appRouter";
import { ThemeProvider } from "@mui/material/styles";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

import theme from "./theme";

const queryClient = new QueryClient();

export function Providers({
  children,
  deviceType,
}: Readonly<{
  children: React.ReactNode;
  deviceType: string;
}>) {
  return (
    <AppRouterCacheProvider>
      <QueryClientProvider client={queryClient}>
        <ThemeProvider theme={theme(deviceType)}>
          <CssBaseline />
          {children}
        </ThemeProvider>
      </QueryClientProvider>
    </AppRouterCacheProvider>
  );
}

Infinite scroll

Next step is to define our own useListVideos hook, which will be responsible for fetching page of videos, with some simulated delay.

It will use useInfiniteQuery under the hood, which was designed for UI patterns which automatically load more data.

Rendering lists that can additively "load more" data onto an existing set of data or "infinite scroll" is also a very common UI pattern. TanStack Query supports a useful version of useQuery called useInfiniteQuery for querying these types of lists.

We will implement pagination and introduce 1 second delay to simulate fetching data from the backend and show skeleton, which we already implemented.

web/app/Home/useListVideos.tsx

import { useInfiniteQuery } from "@tanstack/react-query";

import { Page } from "./page";
import { Video } from "./video";
import { VIDEOS } from "./videos.data";

export const PAGE_SIZE = 24;
const DELAY_MS = 1000;

const fetch = async (
  currentPage: number,
  pageSize: number = PAGE_SIZE
): Promise<Page<Video>> => {
  await new Promise((resolve) => setTimeout(resolve, DELAY_MS));

  const start = currentPage * pageSize;
  const end = start + pageSize;

  return {
    items: VIDEOS.slice(start, end),
    currentPage,
    hasNextPage: end < VIDEOS.length,
  };
};

export const useListVideos = () => {
  return useInfiniteQuery({
    queryKey: ["listVideos"],
    queryFn: ({ pageParam: page }) => fetch(page),
    initialPageParam: 0,
    getNextPageParam: (lastPage) =>
      lastPage.hasNextPage ? lastPage.currentPage + 1 : undefined,
  });
};

web/app/Home/page.ts

export interface Page<T> {
  items: T[];
  currentPage: number;
  hasNextPage: boolean;
}

Home Page

It's time to use our useListVideos hook on the home page. Thanks to TanStack Query it not only returns paginated data, but also some useful statuses of the operation (e.g. pending) or helper functions (e.g. fetchNextPage).

We will the show skeleton during the initial page load, but also when we will be fetching the next page. In that case we will also show a small circular progress, like they do on YouTube.

We want to trigger fetching the next page when we scroll down and reach end of our list of media items. Let's use React Intersection Observer for a trigger like that. We will add a Box just after BrowseGrid. When that box is visible (in the view), it will change the state of the inView variable to true, which will fetch the next page as a consequence.

npm install react-intersection-observer

web/app/Home/HomePage.tsx (diff)

+"use client";
+
+import React from "react";
+import Box from "@mui/material/Box";
+import CircularProgress from "@mui/material/CircularProgress";
+import { useInView } from "react-intersection-observer";
+
import { BrowseGrid } from "./BrowseGrid";
import { MediaItem } from "./MediaItem";
import { MediaSkeleton } from "./MediaSkeleton";
-import { VIDEOS } from "./videos.data";
+import { PAGE_SIZE, useListVideos } from "./useListVideos";
-
-const PAGE_SIZE = 24;

export function HomePage() {
- const loading = false;
+ const { ref, inView } = useInView();

+ const {
+   status,
+   data,
+   isFetching,
+   isFetchingNextPage,
+   fetchNextPage,
+   hasNextPage,
+ } = useListVideos();
+
+ const videos = data?.pages.flatMap((page) => page.items);
+
+ React.useEffect(() => {
+   if (inView) {
+     if (!isFetching && !isFetchingNextPage && hasNextPage) {
+       fetchNextPage();
+     }
+   }
+ }, [inView, isFetching, isFetchingNextPage, hasNextPage, fetchNextPage]);

  const skeleton = (
    <>
      {Array.from({ length: PAGE_SIZE }).map((_, index) => (
        <MediaSkeleton key={index} />
      ))}
    </>
  );

  return (
-   <BrowseGrid>
-     {loading ? (
-       skeleton
-     ) : (
-       <>
-         {VIDEOS.map((video) => (
-           <MediaItem video={video} key={video.id} />
-         ))}
-       </>
-     )}
-   </BrowseGrid>
+   <>
+     <BrowseGrid>
+       {status === "pending" ? (
+         skeleton
+       ) : (
+         <>
+           {(videos || []).map((video) => (
+             <MediaItem key={video.id} video={video} />
+           ))}
+           {isFetchingNextPage && skeleton}
+         </>
+       )}
+     </BrowseGrid>
+     <Box ref={ref} sx={{ textAlign: "center", height: 2, my: 2 }}>
+       {isFetchingNextPage && <CircularProgress />}
+     </Box>
+   </>
  );
}

web/app/Home/HomePage.tsx

"use client";

import React from "react";
import Box from "@mui/material/Box";
import CircularProgress from "@mui/material/CircularProgress";
import { useInView } from "react-intersection-observer";

import { BrowseGrid } from "./BrowseGrid";
import { MediaItem } from "./MediaItem";
import { MediaSkeleton } from "./MediaSkeleton";
import { PAGE_SIZE, useListVideos } from "./useListVideos";

export function HomePage() {
  const { ref, inView } = useInView();

  const {
    status,
    data,
    isFetching,
    isFetchingNextPage,
    fetchNextPage,
    hasNextPage,
  } = useListVideos();

  const videos = data?.pages.flatMap((page) => page.items);

  React.useEffect(() => {
    if (inView) {
      if (!isFetching && !isFetchingNextPage && hasNextPage) {
        fetchNextPage();
      }
    }
  }, [inView, isFetching, isFetchingNextPage, hasNextPage, fetchNextPage]);

  const skeleton = (
    <>
      {Array.from({ length: PAGE_SIZE }).map((_, index) => (
        <MediaSkeleton key={index} />
      ))}
    </>
  );

  return (
    <>
      <BrowseGrid>
        {status === "pending" ? (
          skeleton
        ) : (
          <>
            {(videos || []).map((video) => (
              <MediaItem key={video.id} video={video} />
            ))}
            {isFetchingNextPage && skeleton}
          </>
        )}
      </BrowseGrid>
      <Box ref={ref} sx={{ textAlign: "center", height: 2, my: 2 }}>
        {isFetchingNextPage && <CircularProgress />}
      </Box>
    </>
  );
}

GitHub: feat(home): fetching data (#8)

Video player

There are two ways to play a YouTube video. The first one is just to click a media item. It will take you to a watch page, with a video player which will automatically start playback. We don't have this page yet, but we will build it in the coming episodes.

The second one is to hover over a media item. It will replace a video thumbnail with an inline video player and automatically start it. This is what we are going to implement right now.

This inline video player will not have any controls, except for a mute/unmute button. State of audio will be lifted up to the media item in order to preserve it every time you activate an inline video player.

We will also implement a playback progress indicator using a determinate variant of a linear progress component.

TimeStatus in the bottom-right corner will be more dynamic. It will be updated in the real-time and show a remaining video duration

web/app/Home/MediaItem/VideoPlayer/VideoPlayer.tsx

"use client";

import * as React from "react";
import Box from "@mui/material/Box";
import LinearProgress from "@mui/material/LinearProgress";
import IconButton from "@mui/material/IconButton";
import Tooltip from "@mui/material/Tooltip";
import VolumeOffIcon from "@mui/icons-material/VolumeOff";
import VolumeUpOutlinedIcon from "@mui/icons-material/VolumeUpOutlined";
import { Duration } from "luxon";
import { styled } from "@mui/material/styles";

import { Video } from "../../video";
import { TimeStatus } from "../TimeStatus";

interface Props {
  video: Pick<Video, "duration" | "url">;
  isMuted: boolean;
  toggleMute: () => void;
}

const StyledVideo = styled("video")({
  aspectRatio: "16 / 9",
  maxWidth: "100%",
  display: "block",
  objectFit: "cover",
});

export function VideoPlayer({ video, isMuted, toggleMute }: Props) {
  const [progress, setProgress] = React.useState(0);
  const [remainingDuration, setRemainingDuration] = React.useState(
    video.duration
  );

  const handleTimeUpdate = ({
    currentTarget: { currentTime, duration },
  }: React.SyntheticEvent<HTMLVideoElement>) => {
    updateProgressIndicator(currentTime, duration);
    updateRemainingDuration(currentTime);
  };

  const updateProgressIndicator = (currentTime: number, duration: number) => {
    const progressPercentage = (currentTime / duration) * 100;
    setProgress(progressPercentage);
  };

  const updateRemainingDuration = (currentTime: number) => {
    const totalDurationInSeconds = Duration.fromISO(video.duration).as(
      "seconds"
    );
    const remainingTimeInSeconds = totalDurationInSeconds - currentTime;

    setRemainingDuration(
      Duration.fromObject({ seconds: remainingTimeInSeconds }).toISO()
    );
  };

  return (
    <Box
      sx={{
        width: "100%",
        height: "100%",
        position: "relative",
        mb: 1.5,
      }}
    >
      <StyledVideo
        src={video.url}
        autoPlay
        loop
        muted={isMuted}
        preload="metadata"
        controlsList="nodownload"
        disablePictureInPicture
        disableRemotePlayback
        onTimeUpdate={handleTimeUpdate}
      />
      <Tooltip
        title={isMuted ? "Unmute" : "Mute"}
        enterDelay={500}
        disableInteractive
      >
        <IconButton
          onClick={toggleMute}
          sx={{
            position: "absolute",
            top: (theme) => theme.spacing(1),
            right: (theme) => theme.spacing(1),
            backgroundColor: "#00000099",
            color: "white",
            "&:hover": {
              backgroundColor: "#00000099",
            },
          }}
        >
          {isMuted ? <VolumeOffIcon /> : <VolumeUpOutlinedIcon />}
        </IconButton>
      </Tooltip>
      <Box
        sx={{
          position: "absolute",
          height: 3,
          left: 0,
          right: 0,
          bottom: 1,
        }}
      >
        <LinearProgress variant="determinate" value={progress} color="error" />
      </Box>
      <TimeStatus time={remainingDuration} />
    </Box>
  );
}

web/app/Home/MediaItem/VideoPlayer/index.ts

export * from "./VideoPlayer";

web/app/Home/MediaItem/MediaItem.tsx (diff)

+"use client";
+
+import * as React from "react";
import Box from "@mui/material/Box";

import { Video } from "../video";
import { VideoDetails } from "./VideoDetails";
+import { VideoPlayer } from "./VideoPlayer";
import { VideoThumbnail } from "./VideoThumbnail";

interface Props {
  video: Video;
}

export function MediaItem({ video }: Props) {
+ const [isHovered, setIsHovered] = React.useState(false);
+
+ const [isMuted, setIsMuted] = React.useState(true);
+ const toggleMute = React.useCallback(() => {
+   setIsMuted((prev) => !prev);
+ }, []);
+
  return (
    <Box
      sx={{
        width: "100%",
        mb: 2,
        display: "block",
        aspectRatio: "16 / 9",
      }}
+     onMouseEnter={() => setIsHovered(true)}
+     onMouseLeave={() => setIsHovered(false)}
    >
+     {isHovered ? (
+       <VideoPlayer video={video} isMuted={isMuted} toggleMute={toggleMute} />
+     ) : (
        <VideoThumbnail video={video} />
+     )}      
      <VideoDetails video={video} />
    </Box>
  );
}

GitHub: feat(home): video player (#8)

Bonus

Next.js page

It seems that the name of our page model conflicts with Netx.js page.

app/Home/page.ts
Type error: Page "app/Home/page.ts" does not match the required types of a Next.js Page.

Let's rename web/app/Home/page.ts file to web/app/Home/pagination.ts. It should fix the issue.

GitHub: fix(home): model/nextjs page conflict (#7)

Masthead position bug fix

When we scroll down our home page - the masthead doesn't stay in its position. We didn't notice it before (in the last episode), because we didn't have enough content on the page. It turns out that we should have used sticky instead of static position.

web/app/AppShell/Masthead/Masthead.tsx (diff)

export function Masthead({ onGuideButtonClick, showGuideButton }: Props) {
  return (
-   <AppBar elevation={0} position="static">
+   <AppBar elevation={0} position="sticky">
      <Toolbar>
        {showGuideButton && <GuideButton onClick={onGuideButtonClick} />}
        <Logo />
      </Toolbar>
    </AppBar>
  );
}

GitHub: fix(masthead): sticky position

Application Shell using Next.js, Material UI, Amplify Hosting - FakeTube #3

Jacek Kościesza — Wed, 16 Jul 2025 10:50:05 +0000

We are finally ready to start coding. In the last two episodes we finalised important prerequisites - preparing initial requirements and content for our YouTube clone. In this episode we will start frontend development with an Application Shell.

Application Shell provides a static, consistent and responsive user interface framework or skeleton, which has elements like navigation bars, headers, footers, sidebars and basic layout structure. App shell loads very quickly, then the dynamic content specific to the current page or section is loaded and injected into the shell. In our case it will be a static layout with components like Masthead, App Drawer with Guide, Mini Guide and Pivot Bar.

We are going to use popular technologies like Next.js, React, TypeScript and Material UI. Hosting will be provided by AWS Amplify Hosting, which supports Next.js server-side rendering (SSR) out of the box.

GitHub

GitHub will be our primary tool for a project planning and tracking, but also as a source code repository

I already created the project repository:JacekKosciesza/FakeTube, so let's clone it and change a working directory:

git clone https://github.com/JacekKosciesza/FakeTube.git
cd FakeTube/

Next.js

Installation

The easiest way to start a Next.js project is to use create-next-app. It launches a simple wizard in the terminal. Let's name our app faketube and use default values for the other options.

npx create-next-app@latest

I like to have top level folders in the project like this:

web
mobile
cloud

so, let's rename faketube folder created by crate-next-app to web, change a working directory and run our web application (on the default http://localhost:3000)

mv faketube web
cd web/
npm run dev

GitHub: feat(appshell): next.js installation (#9)

Material UI

Installation

Now it's time to add our components library of choice - Material UI to our project. MUI documentation gives us precise instructions on how to do it.

Let's start with installing core dependencies.

npm install @mui/material @emotion/react @emotion/styled

We will also need to install icons in order to use prebuilt SVG Material Icons.

npm install @mui/icons-material

GitHub: feat(appshell): material ui installation (#10)

Next.js integration

There are a few integration steps we will have to do to use Material UI with Next.js.

We will be using an App Router which is a file-system based router that uses the React's latest features and is an evolution of the older Pages Router.

Dependencies

Let's start with installing the dependencies

npm install @mui/material-nextjs @emotion/cache

Configuration

Next, let's change configuration in web/app/layout.tsx by importing the AppRouterCacheProvider component and wrapping all elements under the <body> with it

web/app/layout.tsx (diff)

+ import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';
import type { Metadata } from "next";
// ...

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en">
      <body className={`${geistSans.variable} ${geistMono.variable}`}>
+       <AppRouterCacheProvider>
          {children}
+       </AppRouterCacheProvider>
      </body>
    </html>
  );
}

Font optimization

If we want to take advantage of Next.js font optimization, we will have to customize a few things in the MUI theme and Next.js layout.

web/app/theme.ts

"use client";

import { createTheme } from "@mui/material/styles";

const theme = createTheme({
  typography: {
    fontFamily: "var(--font-roboto)",
  },
});

export default theme;

web/app/layout.tsx (diff)

+import CssBaseline from "@mui/material/CssBaseline";
import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';
import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
-import "./globals.css";
+import { Roboto } from 'next/font/google';
+import { ThemeProvider } from '@mui/material/styles';

+import theme from './theme';

-const geistSans = Geist({
-  variable: "--font-geist-sans",
-  subsets: ["latin"],
-});

-const geistMono = Geist_Mono({
-  variable: "--font-geist-mono",
-  subsets: ["latin"],
-});

+const roboto = Roboto({
+  weight: ['300', '400', '500', '700'],
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-roboto',
+});

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
   return (
-    <html lang="en">
+    <html lang="en" className={roboto.variable}>
-      <body className={`${geistSans.variable} ${geistMono.variable}`}>
+      <body>
          <AppRouterCacheProvider>
+           <ThemeProvider theme={theme}>
+             <CssBaseline />
              {children}
+           </ThemeProvider>
          </AppRouterCacheProvider>
       </body>
     </html>
   );
 }

web/app/layout.tsx

import CssBaseline from "@mui/material/CssBaseline";
import { AppRouterCacheProvider } from "@mui/material-nextjs/v15-appRouter";
import type { Metadata } from "next";
import { Roboto } from "next/font/google";
import { ThemeProvider } from "@mui/material/styles";

import theme from "./theme";

const roboto = Roboto({
  weight: ["300", "400", "500", "700"],
  subsets: ["latin"],
  display: "swap",
  variable: "--font-roboto",
});

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en" className={roboto.variable}>
      <body>
        <AppRouterCacheProvider>
          <ThemeProvider theme={theme}>
            <CssBaseline />
            {children}
          </ThemeProvider>
        </AppRouterCacheProvider>
      </body>
    </html>
  );
}

Let's verify if our project still builds and runs

npm run build
npm run dev

GitHub: feat(appshell): next.js integration (#11)

Application Shell

After all those prerequisites, we can focus on a minimalistic Application Shell component. It will not add any visual difference (in that version), but will be a foundation for some enhancements.

web/app/AppShell/AppShell.tsx

import * as React from "react";

interface Props {
  children: React.ReactNode;
}

export function AppShell({ children }: Props) {
  return <>{children}</>;
}

web/app/AppShell/index.ts

export * from "./AppShell";

To use it - we will have to modify our web/app/layout.tsx, but first let's look at HTML metadata.

Metadata

Let's change web app metadata like title, description and keywords. This is how YouTube defines it.

<!DOCTYPE html>
<html>
  <head>
    <title>YouTube</title>
    <meta name="description" content="Enjoy the videos and music
you love, upload original content, and share it all with friends,
family, and the world on YouTube.">
     <meta name="keywords" content="video, sharing, camera phone, video
phone, free, upload">
     <!-- ... -->
  </head>
</html>

We will do it in a similar way, but let's get rid of some features references, which we don't have yet.

web/app/layout.tsx (diff)

import CssBaseline from "@mui/material/CssBaseline";
import { AppRouterCacheProvider } from "@mui/material-nextjs/v15-appRouter";
import type { Metadata } from "next";
import { Roboto } from "next/font/google";
import { ThemeProvider } from "@mui/material/styles";

import theme from "../theme";
+import { AppShell } from "./AppShell";

const roboto = Roboto({
  weight: ["300", "400", "500", "700"],
  subsets: ["latin"],
  display: "swap",
  variable: "--font-roboto",
});

export const metadata: Metadata = {
-  title: "Create Next App",
+  title: "FakeTube",
-  description: "Generated by create next app",
+  description: "Enjoy the videos and music you love on FakeTube.",
+  keywords: "video, free",
};

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en" className={roboto.variable}>
      <body>
        <AppRouterCacheProvider>
          <ThemeProvider theme={theme}>
            <CssBaseline />
-           {children}
+           <AppShell>{children}</AppShell>
          </ThemeProvider>
        </AppRouterCacheProvider>
      </body>
    </html>
  );
}

Home

Defaul page needs some cleanup. We will make it empty for now.

web/app/page.tsx

export default function Home() {
  return null;
}

Breakpoints

To make our layout more compatible with the real YouTube app, we will have to slightly adjust breakpoints by defining custom ones in the MUI theme.

web/app/theme.ts (diff)

"use client";

import { createTheme } from "@mui/material/styles";

+declare module "@mui/material/styles" {
+  interface BreakpointOverrides {
+    xxl: true;
+    xxxl: true;
+  }
+}

const theme = createTheme({
  typography: {
    fontFamily: "var(--font-roboto)",
  },
+ breakpoints: {
+   values: {
+     xs: 0,
+     sm: 601,
+     md: 792,
+     lg: 1313,
+     xl: 1536,
+     xxl: 1920,
+     xxxl: 2985,
+   },
+ },
});

export default theme;

Loading

In Next.js we can display a meaningful loading UI component with React Suspense. In our case we will need a simple indeterminate linear progress indicator.

web/app/loading.tsx

import LinearProgress from "@mui/material/LinearProgress";

export default function Loading() {
  return <LinearProgress color="error" sx={{ height: 3 }} />;
}

Favicon

It's time to replace Next.js favicon with the FakeTube one. At the same time let's add the FakeTube logo in PNG and SVG formats.

web
├── app
│   ├── favicon.ico
|   ├── ...
├── public
│   ├── faketube.png
│   ├── faketube.svg
|   ├── ...
| ...

Cleanup

Let's also remove all the unused files created by create-nextjs-app.

web
├── app
│   ├── globals.css
│   ├── page.module.css
|   ├── ...
├── public
│   ├── file.svg
│   ├── globe.svg
│   ├── next.svg
│   ├── vercel.svg
│   ├── window.svg
|   ├── ...
| ...

Next.js Dev Tools

We don't need Next.js Dev Tools at the moment, so we will hide it. We can do it by modifying devIndicators Next.js config option.

web/next.config (diff)

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
- /* config options here */
+ devIndicators: false,
};

export default nextConfig;

GitHub: feat(appshell): empty appshell component (#12)

Masthead

The next step is to create a masthead, which in Material Design terms is known as an App Bar. It's at the top of the screen and will be used for branding, navigation, and actions in the future.

web/app/AppShell/Masthead/Masthead.tsx

import AppBar from "@mui/material/AppBar";
import IconButton from "@mui/material/IconButton";
import MenuIcon from "@mui/icons-material/Menu";
import Toolbar from "@mui/material/Toolbar";
import Typography from "@mui/material/Typography";

export function Masthead() {
  return (
    <AppBar elevation={0} position="static">
      <Toolbar>
        <IconButton
          size="large"
          edge="start"
          color="inherit"
          aria-label="menu"
          sx={{ mr: 2 }}
        >
          <MenuIcon />
        </IconButton>
        <Typography variant="h6" component="div" sx={{ flexGrow: 1 }}>
          FakeTube
        </Typography>
      </Toolbar>
    </AppBar>
  );
}

web/app/AppShell/Masthead/index.tsx

export * from "./Masthead";

web/app/AppShell/AppShell.tsx (diff)

import * as React from "react";

+import { Masthead } from "./Masthead";

interface Props {
  children: React.ReactNode;
}

export function AppShell({ children }: Props) {
- return <>{children}</>;
+ return (
+   <>
+     <Masthead />
+     {children}
+   </>
+  );
}

By default it's blue, so we have to change it to look like on YouTube. We can adjust styling on the component level or on the theme level. I chose the latter to make it easier to introduce dark theme in the future.

web/app/theme.ts (diff)

// ...
const theme = createTheme({
  typography: {
    fontFamily: "var(--font-roboto)",
  },
  breakpoints: {
    values: {
      xs: 0,
      sm: 601,
      md: 792,
      lg: 1313,
      xl: 1536,
      xxl: 1920,
      xxxl: 2985,
    },
  },
+ components: {
+   MuiAppBar: {
+     styleOverrides: {
+       colorPrimary: {
+         backgroundColor: "#FFFFFF",
+         color: "#000000",
+       },
+     },
+   },
+ },
});

GitHub: feat(appshell): basic masthead component (#13)

Logo

So far we have created only basic "FakeTube" logotype (brand name), but we also need a logomark (icon or image) to create a complete brand logo. We will introduce a new logo component and update masthead to use it.

web/app/AppShell/Logo/Logo.tsx

"use client";

import * as React from "react";
import Image from "next/image";
import NextLink from "next/link";
import Tooltip from "@mui/material/Tooltip";
import Typography from "@mui/material/Typography";
import Stack from "@mui/material/Stack";

export function Logo() {
  return (
    <Tooltip
      title="FakeTube Home"
      enterDelay={500}
      disableInteractive
      sx={{
        textDecoration: "none",
      }}
    >
      <NextLink href="/" style={{ textDecoration: "none" }}>
        <Stack direction="row" alignItems="center" spacing={0.2}>
          <Image src="faketube.svg" alt="" width={29} height={20} />
          <Typography
            variant="h6"
            color="textPrimary"
            sx={{
              fontWeight: (theme) => theme.typography.fontWeightBold,
              letterSpacing: "-0.075rem",
            }}
          >
            FakeTube
          </Typography>
        </Stack>
      </NextLink>
    </Tooltip>
  );
}

web/app/AppShell/Logo/index.ts

export * from "./Logo";

web/app/AppShell/Masthead/Masthead.tsx (diff)

import AppBar from "@mui/material/AppBar";
import IconButton from "@mui/material/IconButton";
import MenuIcon from "@mui/icons-material/Menu";
import Toolbar from "@mui/material/Toolbar";
-import Typography from "@mui/material/Typography";

+import { Logo } from "../Logo";

export function Masthead() {
  return (
    <AppBar elevation={0} position="static">
      <Toolbar>
        <IconButton
          size="large"
          edge="start"
          color="inherit"
          aria-label="menu"
          sx={{ mr: 2 }}
        >
          <MenuIcon />
        </IconButton>
-       <Typography variant="h6" component="div" sx={{ flexGrow: 1 }}>
-         FakeTube
-       </Typography>
+        <Logo />
      </Toolbar>
    </AppBar>
  );
}

GitHub: feat(appshell): logo (#14)

App Drawer

Now, let's shift focus to an App Drawer - sidebar which will have main navigation elements like Guide or Mini Guide. It will have a temporary and permanent variants and will be controlled (open/close) by a Guide Button, which is also known as a hamburger menu button.

web/app/AppShell/AppDrawer/AppDrawer.tsx

import Box from "@mui/material/Box";
import Drawer from "@mui/material/Drawer";

export interface Props {
  open: boolean;
  onDrawerClose: () => void;
  variant?: "temporary" | "permanent";
}

export function AppDrawer(props: Props) {
  const { open, onDrawerClose, variant } = props;

  const handleDrawerClose = () => {
    if (variant === "temporary") onDrawerClose();
  };

  return (
    <Drawer
      open={open}
      onClose={onDrawerClose}
      sx={{
        "& .MuiDrawer-paper": {
          mt: variant === "temporary" ? 0 : 8,
          borderRight: "none",
        },
      }}
      variant={variant}
    >
      <Box
        role="presentation"
        onClick={handleDrawerClose}
        onKeyDown={handleDrawerClose}
        display="flex"
        flexDirection="column"
        justifyContent="space-between"
        sx={{
          height: (theme) =>
            `calc(100% - ${theme.spacing(variant === "temporary" ? 2 : 8)})`,
        }}
      >
        <Box p={2}>TODO: Guide</Box>
      </Box>
    </Drawer>
  );
}

web/app/AppShell/AppShell.tsx (diff)

+"use client";

import * as React from "react";

+import { AppDrawer } from "./AppDrawer";
import { Masthead } from "./Masthead";

interface Props {
  children: React.ReactNode;
}

export function AppShell({ children }: Props) {
+ const [isAppDrawerOpened, setIsAppDrawerOpened] = React.useState(false);

+ const closeAppDrawer = () => {
+   setIsAppDrawerOpened(false);
+ };
+  const toggleAppDrawer = () => {
+   setIsAppDrawerOpened(!isAppDrawerOpened);
+ };

  return (
    <>
-     <Masthead />
+     <Masthead onGuideButtonClick={toggleAppDrawer} />
+     <AppDrawer
+       open={isAppDrawerOpened}
+       onDrawerClose={closeAppDrawer}
+       variant="temporary"
+      />
      {children}
    </>
  );
}

web/app/AppShell/AppShell.tsx

"use client";

import * as React from "react";

import { AppDrawer } from "./AppDrawer";
import { Masthead } from "./Masthead";

interface Props {
  children: React.ReactNode;
}

export function AppShell({ children }: Props) {
  const [isAppDrawerOpened, setIsAppDrawerOpened] = React.useState(false);

  const closeAppDrawer = () => {
    setIsAppDrawerOpened(false);
  };
  const toggleAppDrawer = () => {
    setIsAppDrawerOpened(!isAppDrawerOpened);
  };

  return (
    <>
      <Masthead onGuideButtonClick={toggleAppDrawer} />
      <AppDrawer
        open={isAppDrawerOpened}
        onDrawerClose={closeAppDrawer}
        variant="temporary"
      />
      {children}
    </>
  );
}

web/app/AppShell/Masthead/Masthead.tsx (diff)

import AppBar from "@mui/material/AppBar";
import IconButton from "@mui/material/IconButton";
import MenuIcon from "@mui/icons-material/Menu";
import Toolbar from "@mui/material/Toolbar";

import { Logo } from "../Logo";

+export interface Props {
+  onGuideButtonClick: () => void;
+}

-export function Masthead() {
+export function Masthead({ onGuideButtonClick }: Props) {
  return (
    <AppBar elevation={0} position="static">
      <Toolbar>
        <IconButton
          size="large"
          edge="start"
          color="inherit"
          aria-label="menu"
          sx={{ mr: 2 }}
+         onClick={onGuideButtonClick}
        >
          <MenuIcon />
        </IconButton>
        <Logo />
      </Toolbar>
    </AppBar>
  );
}

GitHub: feat(appshell): empty app drawer component (#15)

Guide

A guide is one of the main navigation elements. It contains elements which we already have in the masthead like Guide Button and Logo, as well as unique navigation items.

web/app/AppShell/AppDrawer/Guide/Guide.tsx

import HomeIcon from "@mui/icons-material/Home";
import HomeOutlinedIcon from "@mui/icons-material/HomeOutlined";
import List from "@mui/material/List";
import Stack from "@mui/material/Stack";
import Toolbar from "@mui/material/Toolbar";

import { GuideButton } from "./GuideButton";
import { GuideItem } from "./GuideItem";
import { Logo } from "../../Logo";

interface Props {
  onDrawerClose: () => void;
  variant?: "temporary" | "permanent";
}

export function Guide(props: Props) {
  const { onDrawerClose, variant } = props;

  const handleDrawerClose = () => {
    if (variant === "temporary") onDrawerClose();
  };

  return (
    <Stack>
      {variant === "temporary" && (
        <Toolbar>
          <GuideButton onClick={handleDrawerClose} />
          <Logo />
        </Toolbar>
      )}
      <List sx={{ width: 240, p: 1 }}>
        <GuideItem
          label="Home"
          href="/"
          icon={<HomeOutlinedIcon />}
          activeIcon={<HomeIcon />}
          onClick={handleDrawerClose}
        />
      </List>
    </Stack>
  );
}

Let's extract a hamburger menu button to a reusable Guide Button component and use it in both places (Guide and Masthead).

web/app/AppShell/AppDrawer/Guide/GuideButton.tsx

import IconButton from "@mui/material/IconButton";
import MenuIcon from "@mui/icons-material/Menu";

interface Props {
  onClick: () => void;
}

export function GuideButton(props: Props) {
  const { onClick } = props;

  return (
    <IconButton
      onClick={onClick}
      size="large"
      edge="start"
      color="inherit"
      aria-label="Guide"
      sx={{ mr: 2 }}
    >
      <MenuIcon />
    </IconButton>
  );
}

web/app/AppShell/AppDrawer/Guide/index.ts

export * from "./Guide";
export * from "./GuideButton";

web/app/AppShell/Masthead/Masthead.tsx (diff)

import AppBar from "@mui/material/AppBar";
-import IconButton from "@mui/material/IconButton";
-import MenuIcon from "@mui/icons-material/Menu";
import Toolbar from "@mui/material/Toolbar";

import { Logo } from "../Logo";
+import { GuideButton } from "../AppDrawer/Guide";

export interface Props {
  onGuideButtonClick: () => void;
}

export function Masthead({ onGuideButtonClick }: Props) {
  return (
    <AppBar elevation={0} position="static">
      <Toolbar>        
-       <IconButton
-         size="large"
-         edge="start"
-         color="inherit"
-         aria-label="menu"
-         sx={{ mr: 2 }}
-         onClick={onGuideButtonClick}
-       >
-         <MenuIcon />
-       </IconButton>
+       <GuideButton onClick={onGuideButtonClick} />
        <Logo />
      </Toolbar>
    </AppBar>
  );
}

Guide item will also be a reusable component defined like this.

web/app/AppShell/AppDrawer/Guide/GuideItem.tsx

import ListItem from "@mui/material/ListItem";
import ListItemButton from "@mui/material/ListItemButton";
import ListItemIcon from "@mui/material/ListItemIcon";
import ListItemText from "@mui/material/ListItemText";
import NextLink from "next/link";

import { useActive } from "../../useActive";

interface Props {
  label: string;
  href: string;
  icon: React.ReactNode;
  activeIcon: React.ReactNode;
  onClick: () => void;
}

export function GuideItem(props: Props) {
  const { label, href, icon, activeIcon, onClick } = props;

  const active = useActive(href);

  return (
    <ListItem disablePadding>
      <ListItemButton
        component={NextLink}
        onClick={onClick}
        href={href}
        sx={{
          pl: 2,
          borderRadius: 2.5,
          backgroundColor: (theme) =>
            active ? theme.palette.action.selected : "inherit",
          fontWeight: active ? "bolder" : "normal",
        }}
      >
        <ListItemIcon
          sx={{
            color: (theme) => theme.palette.text.primary,
            minWidth: "42px",
          }}
        >
          {active ? activeIcon : icon}
        </ListItemIcon>
        <ListItemText
          primary={label}
          slotProps={{
            primary: {
              sx: {
                fontWeight: active ? "bolder" : "normal",
                fontSize: 14,
              },
            },
          }}
        />
      </ListItemButton>
    </ListItem>
  );
}

To know if this is an active (selected) element, we created a helper useActive hook.

web/app/AppShell/useActive.tsx

import { usePathname } from "next/navigation";

export function useActive(href: string): boolean {
  const pathname = usePathname();

  let active = false;
  if (href === "/") {
    active = pathname === href;
  } else {
    active = pathname.startsWith(href);
  }

  return active;
}

Finally let's add Guide to the Application Drawer

web/app/AppShell/AppDrawer/AppDrawer.tsx (diff)

import Box from "@mui/material/Box";
import Drawer from "@mui/material/Drawer";

+import { Guide } from "./Guide";

export interface Props {
  open: boolean;
  onDrawerClose: () => void;
  variant?: "temporary" | "permanent";
}

export function AppDrawer(props: Props) {
  const { open, onDrawerClose, variant } = props;

  const handleDrawerClose = () => {
    if (variant === "temporary") onDrawerClose();
  };

  return (
    <Drawer
      open={open}
      onClose={onDrawerClose}
      sx={{
        "& .MuiDrawer-paper": {
          mt: variant === "temporary" ? 0 : 8,
          borderRight: "none",
        },
      }}
      variant={variant}
    >
      <Box
        role="presentation"
        onClick={handleDrawerClose}
        onKeyDown={handleDrawerClose}
        display="flex"
        flexDirection="column"
        justifyContent="space-between"
        sx={{
          height: (theme) =>
            `calc(100% - ${theme.spacing(variant === "temporary" ? 2 : 8)})`,
        }}
      >
-       <Box p={2}>TODO: Guide</Box>
+       <Guide onDrawerClose={handleDrawerClose} variant={variant} />
      </Box>
    </Drawer>
  );
}

Our navigation solution works well, but we only display a temporary variant of the app drawer. We want to show a permanent variant for the desktop resolution. At the same time we can prepare a display logic for other navigation types like Mini Guide and Pivot Bar. To do that, let's introduce a new hook - useNavigation.

web/app/AppShell/useNavigation.tsx

import useMediaQuery from "@mui/material/useMediaQuery";
import useTheme from "@mui/system/useTheme";

export interface Navigation {
  pivotBar?: boolean;
  miniGuide?: boolean;
  guide?: boolean;
  variant?: "temporary" | "permanent";
}

export function useNavigation(opened: boolean): Navigation {
  const theme = useTheme();
  const tablet = useMediaQuery(theme.breakpoints.between("sm", "lg"));
  const desktop = useMediaQuery(theme.breakpoints.up("lg"));

  const navigation: Navigation = {
    pivotBar: true,
    miniGuide: false,
    guide: false,
  };

  if (tablet) {
    return { guide: true, miniGuide: true, variant: "temporary" };
  }

  if (desktop) {
    return opened
      ? { guide: true, variant: "permanent" }
      : { guide: false, miniGuide: true, variant: "temporary" };
  }

  return navigation;
}

web/app/AppShell/AppShell.tsx (diff)

"use client";

import * as React from "react";

import { AppDrawer } from "./AppDrawer";
import { Masthead } from "./Masthead";
+import { useNavigation } from "./useNavigation";

interface Props {
  children: React.ReactNode;
}

export function AppShell({ children }: Props) {
  const [isAppDrawerOpened, setIsAppDrawerOpened] = React.useState(false);

  const closeAppDrawer = () => {
    setIsAppDrawerOpened(false);
  };
  const toggleAppDrawer = () => {
    setIsAppDrawerOpened(!isAppDrawerOpened);
  };

+ const navigation = useNavigation(isAppDrawerOpened);

  return (
    <>
      <Masthead onGuideButtonClick={toggleAppDrawer} />
+     {navigation.guide && (
        <AppDrawer
          open={isAppDrawerOpened}
          onDrawerClose={closeAppDrawer}
-         variant="temporary"
+         variant={navigation.variant}
        />
+     )}
      {children}
    </>
  );
}

GitHub: feat(appshell): guide (#4)

Mini Guide

In some cases we want to display a Mini Guide instead of a fully blown Guide. We will do that for tablet resolution or a desktop one, when the app drawer is closed.

web/app/AppShell/MiniGuide/MiniGuide.tsx

import Drawer from "@mui/material/Drawer";
import HomeIcon from "@mui/icons-material/Home";
import HomeOutlinedIcon from "@mui/icons-material/HomeOutlined";
import List from "@mui/material/List";

import { MiniGuideItem } from "./MiniGuideItem";

export function MiniGuide() {
  return (
    <Drawer
      open={true}
      variant="permanent"
      sx={{
        "& .MuiDrawer-paper": {
          width: (theme) => theme.spacing(9),
          mt: 8,
          pt: 0.3,
          px: 0.8,
          borderRight: "none",
        },
      }}
    >
      <List disablePadding>
        <MiniGuideItem
          label="Home"
          href="/"
          icon={<HomeOutlinedIcon />}
          activeIcon={<HomeIcon />}
        />
      </List>
    </Drawer>
  );
}

web/app/AppShell/MiniGuide/MiniGuideItem.tsx

import ListItem from "@mui/material/ListItem";
import ListItemButton from "@mui/material/ListItemButton";
import NextLink from "next/link";
import Stack from "@mui/material/Stack";
import Typography from "@mui/material/Typography";

import { useActive } from "../useActive";

interface Props {
  label: string;
  href: string;
  icon: React.ReactNode;
  activeIcon: React.ReactNode;
}

export function MiniGuideItem(props: Props) {
  const { label, href, icon, activeIcon } = props;

  const active = useActive(href);

  return (
    <ListItem disablePadding>
      <ListItemButton
        component={NextLink}
        href={href}
        sx={{
          borderRadius: 2.5,
        }}
      >
        <Stack alignItems="center" pt={1}>
          {active ? activeIcon : icon}
          <Typography variant="caption" fontSize={10}>
            {label}
          </Typography>
        </Stack>
      </ListItemButton>
    </ListItem>
  );
}

web/app/AppShell/MiniGuide/index.ts

export * from "./MiniGuide";

web/app/AppShell/AppShell.tsx (diff)

"use client";

import * as React from "react";

import { AppDrawer } from "./AppDrawer";
import { Masthead } from "./Masthead";
+import { MiniGuide } from "./MiniGuide";
import { useNavigation } from "./useNavigation";

interface Props {
  children: React.ReactNode;
}

export function AppShell({ children }: Props) {
  const [isAppDrawerOpened, setIsAppDrawerOpened] = React.useState(false);

  const closeAppDrawer = () => {
    setIsAppDrawerOpened(false);
  };
  const toggleAppDrawer = () => {
    setIsAppDrawerOpened(!isAppDrawerOpened);
  };

  const navigation = useNavigation(isAppDrawerOpened);

  return (
    <>
      <Masthead onGuideButtonClick={toggleAppDrawer} />
+     {navigation.miniGuide && <MiniGuide />}
      {navigation.guide && (
        <AppDrawer
          open={isAppDrawerOpened}
          onDrawerClose={closeAppDrawer}
          variant={navigation.variant}
        />
      )}
      {children}
    </>
  );
}

GitHub: feat(appshell): mini guide (#5)

Pivot Bar

Similarly, for the mobile resolution we want to display a bottom navigation, which is called a Pivot Bar.

web/app/AppShell/PivotBar/PivotBar.tsx

import BottomNavigation from "@mui/material/BottomNavigation";
import HomeIcon from "@mui/icons-material/Home";
import HomeOutlinedIcon from "@mui/icons-material/HomeOutlined";
import Paper from "@mui/material/Paper";

import { PivotBarItem } from "./PivotBarItem";

export function PivotBar() {
  return (
    <Paper
      sx={{
        position: "fixed",
        bottom: 0,
        left: 0,
        right: 0,
        zIndex: (theme) => theme.zIndex.appBar,
      }}
      elevation={1}
    >
      <BottomNavigation showLabels>
        <PivotBarItem
          label="Home"
          href="/"
          icon={<HomeOutlinedIcon />}
          activeIcon={<HomeIcon />}
        />
      </BottomNavigation>
    </Paper>
  );
}

web/app/AppShell/PivotBar/PivotBarItem.tsx

import BottomNavigationAction from "@mui/material/BottomNavigationAction";
import NextLink from "next/link";

import { useActive } from "../useActive";

interface Props {
  label: string;
  href: string;
  icon: React.ReactNode;
  activeIcon: React.ReactNode;
}

export function PivotBarItem(props: Props) {
  const { label, href, icon, activeIcon } = props;

  const active = useActive(href);

  return (
    <BottomNavigationAction
      component={NextLink}
      href={href}
      showLabel
      label={label}
      icon={active ? activeIcon : icon}
      sx={{
        "&.MuiBottomNavigationAction-root": {
          color: "inherit",
        },
      }}
    />
  );
}

web/app/AppShell/PivotBar/index.ts

export * from "./PivotBar";

web/app/AppShell/AppShell.tsx (diff)

"use client";

import * as React from "react";

import { AppDrawer } from "./AppDrawer";
import { Masthead } from "./Masthead";
import { MiniGuide } from "./MiniGuide";
+import { PivotBar } from "./PivotBar";
import { useNavigation } from "./useNavigation";

interface Props {
  children: React.ReactNode;
}

export function AppShell({ children }: Props) {
  const [isAppDrawerOpened, setIsAppDrawerOpened] = React.useState(false);

  const closeAppDrawer = () => {
    setIsAppDrawerOpened(false);
  };
  const toggleAppDrawer = () => {
    setIsAppDrawerOpened(!isAppDrawerOpened);
  };

  const navigation = useNavigation(isAppDrawerOpened);

  return (
    <>
      <Masthead onGuideButtonClick={toggleAppDrawer} />
+     {navigation.pivotBar && <PivotBar />}
      {navigation.miniGuide && <MiniGuide />}
      {navigation.guide && (
        <AppDrawer
          open={isAppDrawerOpened}
          onDrawerClose={closeAppDrawer}
          variant={navigation.variant}
        />
      )}
      {children}
    </>
  );
}

We don't want to show the Guide Button when a Pivot Bar navigation is present. Let's change that behaviour.

web/app/AppShell/Masthead/Masthead.tsx (diff)

// ...
export interface Props {
  onGuideButtonClick: () => void;
+ showGuideButton?: boolean;
}

-export function Masthead({ onGuideButtonClick }: Props) {
+export function Masthead({ onGuideButtonClick, showGuideButton }: Props) {
  return (
    <AppBar elevation={0} position="static">
      <Toolbar>
-       <GuideButton onClick={onGuideButtonClick} />
+       {showGuideButton && <GuideButton onClick={onGuideButtonClick} />}
        <Logo />
      </Toolbar>
    </AppBar>
  );
}

web/app/AppShell/AppShell.tsx (diff)

  // ...
  return (
    <>
-     <Masthead onGuideButtonClick={toggleAppDrawer} />
+     <Masthead
+       onGuideButtonClick={toggleAppDrawer}
+       showGuideButton={!navigation.pivotBar}
+     />
      {navigation.pivotBar && <PivotBar />}
      {navigation.miniGuide && <MiniGuide />}
      {navigation.guide && (
        <AppDrawer
          open={isAppDrawerOpened}
          onDrawerClose={closeAppDrawer}
          variant={navigation.variant}
        />
      )}
      {children}
    </>
  );
}

GitHub: feat(appshell): pivot bar (#6)

Page Manager

At the moment content of the page is not displayed in the right place, when Guide or Mini Guide is displayed. Let's add some placeholder to the Home Page e.g. TODO: Home Page to show that.

web/app/page.tsx (diff)

+import Typography from "@mui/material/Typography";

export default function Home() {
- return null;
+ return (
+   <Typography component="h2" variant="h4">
+     TODO: Home Page
+   </Typography>
+ );
}

To fix that we will introduce a Page Manger - a component, which will adjust margin and padding based on the navigation elements displayed. We will also set the maximum width of the page to the xxxl breakpoint.

web/app/AppShell/PageManager/PageManager.tsx

import Box from "@mui/material/Box";
import Container from "@mui/material/Container";

import { Navigation } from "../useNavigation";

interface Props {
  navigation: Navigation;
  children: React.ReactNode;
}

export function PageManager({ navigation, children }: Props) {
  let ml = 0;
  let px = 0;

  if (navigation.guide && navigation.variant === "permanent") {
    ml = 30;
    px = 3;
  }

  if (navigation.miniGuide) {
    ml = 9;
    px = 3;
  }

  return (
    <Container maxWidth={"xxxl"} disableGutters>
      <Box
        sx={{
          ml,
          mt: 1,
          px,
        }}
      >
        {children}
      </Box>
    </Container>
  );
}

web/app/AppShell/PageManager/index.ts

export * from "./PageManager";

web/app/AppShell/AppShell.tsx (diff)

"use client";

import * as React from "react";

import { AppDrawer } from "./AppDrawer";
import { Masthead } from "./Masthead";
import { MiniGuide } from "./MiniGuide";
+import { PageManager } from "./PageManager";
import { PivotBar } from "./PivotBar";
import { useNavigation } from "./useNavigation";
// ...

// ...
  return (
    <>
      <Masthead
        onGuideButtonClick={toggleAppDrawer}
        showGuideButton={!navigation.pivotBar}
      />
      {navigation.pivotBar && <PivotBar />}
      {navigation.miniGuide && <MiniGuide />}
      {navigation.guide && (
        <AppDrawer
          open={isAppDrawerOpened}
          onDrawerClose={closeAppDrawer}
          variant={navigation.variant}
        />
      )}
-     {children}
+     <PageManager navigation={navigation}>{children}</PageManager>
    </>
  );
}

Looks much better now.

GitHub: feat(appshell): page manager (#16)

SSR (Server-Side Rendering)

When you load or refresh our web app on a tablet or mobile resolution - there is a flash of mobile version, before useMediaQuery is executed on a client side and adjusts navigation elements.

To fix that - we can use Server-Side Rendering for useMediaQuery, but there is a catch.

Server-side rendering and client-side media queries are fundamentally at odds. Be aware of the tradeoff. The support can only be partial.

Let's start with extracting part of the web/app/layout.tsx to a separate web/app/providers.tsx file.

"use client";

import CssBaseline from "@mui/material/CssBaseline";
import { AppRouterCacheProvider } from "@mui/material-nextjs/v15-appRouter";
import { ThemeProvider } from "@mui/material/styles";

import theme from "./theme";

export function Providers({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <AppRouterCacheProvider>
      <ThemeProvider theme={theme}>
        <CssBaseline />
        {children}
      </ThemeProvider>
    </AppRouterCacheProvider>
  );
}

web/app/layout.tsx (diff)

-import CssBaseline from "@mui/material/CssBaseline";
-import { AppRouterCacheProvider } from "@mui/material-nextjs/v15-appRouter";
import type { Metadata } from "next";
import { Roboto } from "next/font/google";
-import { ThemeProvider } from "@mui/material/styles";

-import theme from "./theme";
import { AppShell } from "./AppShell";
+import { Providers } from "./providers";

const roboto = Roboto({
  weight: ["300", "400", "500", "700"],
  subsets: ["latin"],
  display: "swap",
  variable: "--font-roboto",
});

export const metadata: Metadata = {
  title: "FakeTube",
  description: "Enjoy the videos and music you love on FakeTube.",
  keywords: "video, free",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en" className={roboto.variable}>
      <body>
-       <AppRouterCacheProvider>
-       <ThemeProvider theme={theme}>
-       <CssBaseline />
+       <Providers>
          <AppShell>{children}</AppShell>
+       </Providers>
-       </ThemeProvider>
-       </AppRouterCacheProvider>
      </body>
    </html>
  );
}

This SSR implementation will use User-Agent request header to detect device type (mobile, tablet, desktop) and based on that will provide arbitrary screen width to the useMediaQuery.

Let's install a few dependencies first.

npm install css-mediaquery ua-parser-js
npm install --save-dev @types/css-mediaquery @types/ua-parser-js

web/app/layout.tsx (diff)

import type { Metadata } from "next";
+import { headers } from "next/headers";
import { Roboto } from "next/font/google";
+import { UAParser } from "ua-parser-js";

// ...

+const FALLBACK_DEVICE_TYPE = "mobile";

-export default function RootLayout({
+export default async function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
+ const headersList = await headers();
+ const userAgent = headersList.get("user-agent") || undefined;
+ const uap = new UAParser(userAgent);
+ const deviceType = (await uap.getDevice().withFeatureCheck()).type || FALLBACK_DEVICE_TYPE;

  return (
    <html lang="en" className={roboto.variable}>
      <body>
-       <Providers>
+       <Providers deviceType={deviceType}>
          <AppShell>{children}</AppShell>
        </Providers>
      </body>
    </html>
  );
}

web/app/providers.tsx (diff)

// ...

export function Providers({
  children,
+ deviceType,
}: Readonly<{
  children: React.ReactNode;
+  deviceType: string;
}>) {
  return (
    <AppRouterCacheProvider>
-     <ThemeProvider theme={theme}>
+     <ThemeProvider theme={theme(deviceType)}>
        <CssBaseline />
        {children}
      </ThemeProvider>
    </AppRouterCacheProvider>
  );
}

web/app/theme.ts (diff)

"use client";

+import mediaQuery from "css-mediaquery";
import { createTheme } from "@mui/material/styles";

declare module "@mui/material/styles" {
  interface BreakpointOverrides {
    xxl: true;
    xxxl: true;
  }
}

+function deviceTypeToWidth(deviceType: string) {
+  switch (deviceType) {
+    case "mobile":
+      return "600px";
+    case "tablet":
+      return "792px";
+    default:
+      return "1313px";
+  }
+}

+const ssrMatchMedia = (deviceType: string) => (query: string) => ({
+  matches: mediaQuery.match(query, {
+    width: deviceTypeToWidth(deviceType),
+  }),
+});

-const theme = createTheme({
+const theme = (deviceType: string) =>
+  createTheme({
     typography: {
       fontFamily: "var(--font-roboto)",
     },
     breakpoints: {
       values: {
         xs: 0,
         sm: 601,
         md: 792,
         lg: 1313,
         xl: 1536,
         xxl: 1920,
         xxxl: 2985,
       },
     },
     components: {
+      MuiUseMediaQuery: {
+        defaultProps: {
+          ssrMatchMedia: ssrMatchMedia(deviceType),
+        },
+      },
       MuiAppBar: {
         styleOverrides: {
           colorPrimary: {
             backgroundColor: "#FFFFFF",
             color: "#000000",
           },
         },
       },
     },
   });

export default theme;

Unfortunately it seems that ua-parser-js doesn't always correctly identify a device type, see iPad Air and iPad Pro - type not correctly identified, so it doesn't work correctly on my Chrome browser on MacOS. We will have to definitely look at improving it. At the moment we can adjust FALLBACK_DEVICE_TYPE to change the behaviour.

GitHub: feat(appshell): server-side rendering (#17)

Amplify Hosting

The last thing to do is to deploy our web application and make it publicly accessible from the faketube.app domain.

We will use AWS Amplify service and its hosting feature.

Go to AWS Amplify and click Deploy an app button. Choose GitHub as a Git provider and click Next.

Choose JacekKosciesza/FakeTube repository and main branch. Our app is a monorepo, so let's set web as a root directory. Click Next.

Set the name of our app to FakeTube. All other settings should be auto detected and configured as a Next.js app. Click Next.

After reviewing all the settings click Save and deploy.

After a while the app should be deployed to the amplifyapp.com domain with some random subdomain.

To use our faketube.app domain, we have to click Add custom domain from the Overview tab.

Click Add domain, type faketube.app and click Check domain availability. We already own this domain (GoDaddy domain registrar), so Amplify will detect it and automatically select Create hosted zone on Route53 option. Let's click Configure domain button.

We will have to copy the name server names and paste them on the GoDaddy domain configuration page. After some longer time (usually minutes not hours) Amplify should automatically finish setup - create SSL configuration and activate the domain.

Now faketube.app should be listed as a custom domain and we should see our app when we visit it.

Generative AI Videos using Bedrock, Polly, iMovie - FakeTube #2

Jacek Kościesza — Mon, 31 Mar 2025 15:47:15 +0000

We are building FakeTube - a YouTube clone using cloud-native and web technologies. In the last episode we defined initial project requirements. We are almost ready for the development, but before we jump into writing code, we need one more thing - a video content.

Due to potential copyright issues, using existing YouTube videos is not an option. Instead, we can consider using stock video footage from services such as Shutterstock or creating our own content with a mobile phone.

There is however a better way in my opinion. We are living in a Generative AI era, so why not just use some foundation models to generate not only ideas for the videos, but also the videos themselves.

Content Requirements

FakeTube is all about videos and we need at least a few of them to implement and test home page features such as responsive grid layout, infinite scroll or inline video player.

How many?

For the infinite scroll we will need a lot of videos. This is because YouTube loads videos in batches (which is actually a page size) of 24. So we will need more than this to accurately illustrate the feature.

Also, having a home page full of videos, especially on the larger screens will look much better, so let's assume our target will be to generate 32 videos (which is BTW also a perfect number from the computer science perspective: 2⁵).

What topics?

Should we generate some random videos or do we have some specific topics or categories in mind?

It turns out that YouTube can help us with that. When you upload a video using YouTube Studio, in the "Details" step there is a hidden "Paid promotion, tags, subtitles, and more" section, which you can expand by clicking the "Show more" button.

One of the subsections there is "Category" ("Add your video to a category so viewers can find it more easily").

There are 15 categories in total. They are very generic, but it will help us to create more structured and consistent video content.

For now let's select 8 categories and we will generate 4 videos per category, which will be 32 videos in total:

Autos & Vehicles
Education
Gaming
Howto & Style
Nonprofits & Activism
Pets & Animals
Sports
Travel & Events

Generative AI

With a clearer understanding of our desired content, the next crucial step is to identify a Generative AI service and foundation model capable of generating a video script and footage.

I personally have a lot of experience with AWS (Amazon Web Services), so it's a natural choice to use it for this project. At some point I really would like compare it with other cloud providers like Microsoft Azure or Google Cloud or even independent services, but for now we will use AWS as a foundation and a baseline for FakeTube.

Amazon Bedrock

Luckily for us, we don't have to spend a lot of time on research.

Amazon Bedrock is the service dedicated for the generative AI applications in AWS.

It's one of the fastest growing AWS services, which gives you access to a wide range of Foundation Models (FM) from leading AI companies like AI21 Labs, Cohere, Stability AI, Anthropic, Meta, Mistral AI, DeepSeek and of course Amazon themselves.

Amazon Nova

One of the models or actually a family of models which can be a perfect fit for our use case is Amazon Nova, because as stated in the documentation, it includes:

creative content generation models that accept text and image inputs and produce image or video outputs. They are designed to deliver customizable high-quality images and videos for visual content generation.

We will be interested in 3 models from the Amazon Nova family:

Amazon Nova Reel

state-of-the-art video generation model that allows customers to easily create high quality video from text and images.

Amazon Nova Canvas

state-of-the-art image generation model that creates professional-grade images from text or images provided in prompts.

Amazon Nova Micro

text-only model that delivers the lowest latency responses at very low cost. It is highly performant at language understanding, translation, reasoning, code completion, brainstorming, and mathematical problem-solving.

Limitations

There are currently some important limitations of the Amazon Nova Reel, which can be difficult to accept or affect our content generation workflow:

Video duration is limited

Amazon Nova Reel serves a wide range of potential application domains and offers the following core capabilities:

Generate videos of up to 6 seconds given a text prompt.

Generate videos of up to 6 seconds given a reference image and a text prompt.

There is no audio

Modalities

Amazon Nova Reel does not currently support audio or 3D content.

The first limitation is not a big deal at the moment. We can accept that we will have short video examples.

The second one is more problematic. One of the features of the video player is the "Unmute/mute button", which will be kind of useless when a video doesn't have an audio track.

Solution would be to generate audio using some other foundation model or service and merge it with the video using for example Apple iMovie, which I already use for video editing.

There are two ideas about an audio track

Generate background music
Generate voice-over narration

Background music is a very nice option, but unfortunately I didn't find a foundation model in Amazon Bedrock which is capable of doing that. There is a dedicated service for that AWS DeepComposer, but unfortunately it's deprecated

After careful consideration, we have made the decision to end support for AWS DeepComposer, effective 17-Sep-2025. New customer sign-ups and account upgrades are no longer available.

That's why I decided for a voice-over narration option, and there is a very good AWS service exactly for that purpose.

Amazon Polly

Amazon Polly was created precisely for that - it's AI voice generator and text-to-speech tool, which can create high-quality, natural-sounding human voices in dozens of languages.

It's also super easy to use - we just need to enter text we want to synthesize, select engine, language and voice and download it as an mp3 file.

Workflow

High level overview

Putting this all together - we will create a workflow, which looks like this:

1) We will use prompt engineering techniques to create input for Amazon Nova Micro, asking it to generate JSON metadata for the video, including category, title, slug (id), description and prompts for other foundation models and services to generate thumbnail, audio and video.

2) Output from Amazon Nova Micro will look like this:

{
  "category": "Video category",
  "title": "Video title",
  "slug": "video-title",
  "description": "Video description",
  "thumbnail": "Prompt for Amazon Nova Canvas",
  "video": "Prompt for Amazon Nova Reel",
  "audio": "Text for Amazon Polly"
}

3) We will use "thumbnail": "Prompt for Amazon Nova Canvas" from step 2 as an input for Amazon Nova Canvas to generate 3 thumbnails. One of them (arbitrary selected) will be image input for Amazon Nova Reel to generate a video

4) We will use "audio": "Text for Amazon Polly" from step 2) as an input for Amazon Polly to generate voice-over narration audio.

5) We will use "video": "Prompt for Amazon Nova Reel" from step 2 as an input for Amazon Nova Reel, together with one of the thumbnails from step 3) to generate a video.

6) We will use Apple iMovie to merge audio from step 4 with video from step 5 and produce a final video with an audio track.

Let's try it

Prerequisites

Not all foundation models in Amazon Bedrock are supported in all regions, so if you can't find Amazon Nova models in your AWS region of choice - you can switch to US East (N. Virginia) us-east-1 region.

Models have to also be enabled before you use them. Scroll down the left sidebar to the very bottom and select Bedrock configurations -> Model access -> Modify model access and enable Nova Reel, Nova Micro, Nova Canvas models.

Prompt

Prompt engineering is process of developing, designing and optimising prompts to enhance the output of FM (Foundation Model) to our needs.

Improved prompting technique consists of:

Instruction - a task for the model to do
Context - external information to guide the model
Input data - the input for which you want a response
Output indicator - the output type or format

After some experiments I ended up with prompt like this:

Instruction:
Generate an example video metadata for a given [CATEGORY]
and [TOPIC] suggestion (if provided). Output should be in
a JSON format, with the following kay-value pairs

- category: provided category in the input
- title: video title
- slug: title slug
- description: video description
- thumbnail: prompt for Amazon Nova Canvas model, which will generate video thumbnail
- video: prompt for Amazon Nova Reel, which will generate video (based on that prompt and generated thumbnail)
- audio: text for Amazon Polly, which will be synthesised into speech and will be part of the video's audio track
  Make all parts of the metadata are concise, consistent and easily understandable by a 12 year old child. Make sure that video is exactly 6 seconds long and synthesised audio is 5 seconds long. Video script should be simple but engaging animation with a moving parts and changing lights. Don't add any statistics or text overlays to the thumbnail or video.

Context:  
This video content will be used on YouTube clone, which is an educational software engineering project. The video content will be used to showcase the capabilities of the platform.

Examples:

Input:
[CATEGORY] is "Autos & Vehicles"
Output:
{
  "category": "Autos & Vehicles",
  "title": "Magic Wheels: The Future of Cars",
  "slug": "magic-wheels-the-future-of-cars",
  "description": "Discover how cars of the future will move with magic wheels! Watch the cool animation of a car zooming around with flashing lights and see how it might change our rides!",
  "thumbnail": "Create a dynamic and colorful thumbnail showcasing a futuristic car with spinning 'magic wheels' and flashing lights. The car should be zooming through a bright, neon-lit futuristic cityscape.",
  "video": "Generate a 6-second dynamic video with a futuristic car featuring magic wheels that spin and emit flashing lights. The car zooms through a vibrant, neon-lit city with animated movement and bright colors. The scene should be fast-paced and full of energy.",
  "audio": "Welcome to the future of cars! Watch this dynamic future car with magic wheels zooming through a vibrant city."
}

Input:
[CATEGORY] is "Nonprofits & Activism"

Output:

It's not perfect, but good enough for our use case. It's important to note that there are a few prompt engineering techniques e.g.

Enhanced prompt

Instruction

Generate an example video metadata for a given [CATEGORY]
and [TOPIC] suggestion (if provided)
...
Make all parts of the metadata are concise, consistent and easily understandable by a 12 year old child. Make sure that video is exactly 6 seconds long and synthesised audio is 5 seconds long. Video script should be simple but engaging animation with a moving parts and changing lights.

Output indicator

Output should be in a JSON format, with the following kay-value pairs
...

category: provided category in the input

title: video title

slug: title slug

description: video description

thumbnail: prompt for Amazon Nova Canvas model, which will generate video thumbnail

video: prompt for Amazon Nova Reel, which will generate video (based on that prompt and generated thumbnail)

audio: text for Amazon Polly, which will be synthesised into speech and will be part of the video's audio track

Context

This video content will be used on YouTube clone, which is an educational software engineering project. The video content will be used to showcase the capabilities of the platform.

Input

[CATEGORY] is "Nonprofits & Activism"

Negative prompting

A technique where you explicitly instruct the model on what not to include or do in the response.

Don't add any statistics or text overlays to the thumbnail or video.

Few-shot prompting

Provide examples of a task to the model to guide its output. I used one example (one-shot prompting). Probably I could get better results providing more examples, but it was good enough for now.

Input:
[CATEGORY] is "Autos & Vehicles"
Output:
{
"category": "Autos & Vehicles",
"title": "Magic Wheels: The Future of Cars",
"slug": "magic-wheels-the-future-of-cars",
"description": "Discover how cars of the future will move with magic wheels! Watch the cool animation of a car zooming around with flashing lights and see how it might change our rides!",
"thumbnail": "Create a dynamic and colorful thumbnail showcasing a futuristic car with spinning 'magic wheels' and flashing lights. The car should be zooming through a bright, neon-lit futuristic cityscape.",
"video": "Generate a 6-second dynamic video with a futuristic car featuring magic wheels that spin and emit flashing lights. The car zooms through a vibrant, neon-lit city with animated movement and bright colors. The scene should be fast-paced and full of energy.",
"audio": "Welcome to the future of cars! Watch this dynamic future car with magic wheels zooming through a vibrant city."
}

Prompt templates

Templates simplify and standardize the process of generating prompts.

Generate an example video metadata for a given [CATEGORY]
and [TOPIC] suggestion (if provided)
...
[CATEGORY] is "Nonprofits & Activism"

Amazon Nova Micro

We can access Amazon Nova Micro foundation model using Chat/Text playground. Choose "Single prompt" mode from the dropdown. Then click "Select model" and choose Amazon category, Nova Micro model and On-demand inference (which is pay-as-you-go model, where you are charged based on the number of input and output tokens processed for each request).

Let's also adjust some inference parameters which are located in the "Configurations" segment on the left. There are at least two interesting sections:

Randomness and diversity
Length

I increased the "Response length" parameter to 1024, because the default setting of 512 was not enough for our video metadata JSON output.

I also increased "Temperature" and "Top P" parameters to a maximum value of 1 to make model responses more random, diverse and creative.

Let's now paste our prompt and modify input category to "Sports" like this:

Input:
[CATEGORY] is "Sports"

Here is JSON video metadata output generated by the Amazon Nova Micro foundation model:

{
  "category": "Sports",
  "title": "Amazing Soccer Tricks",
  "slug": "amazing-soccer-tricks",
  "description": "Watch this cool soccer player do amazing tricks on the field! See how he spins the ball and makes it move in crazy ways!",
  "thumbnail": "Create a dynamic and colorful thumbnail showing a soccer player doing a spinning trick with the ball, surrounded by flashing lights and a vibrant soccer field.",
  "video": "Generate a 6-second dynamic video featuring a soccer player performing amazing tricks with the ball, including spins and flips. The scene should be fast-paced, full of energy, and colorful with animated movement and lights.",
  "audio": "Check out these amazing soccer tricks! The player spin and flip the ball in incredible ways!"
}

Amazon Nova Canvas

Now it's time to generate thumbnails using Amazon Nova Canvas.

We can access Amazon Nova Canvas foundation model using Image/Video playground. Click "Select model" and choose Amazon category, Nova Canvas model and On-demand inference.

Default inference parameters ("Configurations" segment on the left) are just fine. We want "Generate image" action with 3 images with 1280 x 720 size and 16:9 aspect ratio.

Let's use thumbnail prompt generated by Amazon Nova Micro:

Create a dynamic and colorful thumbnail showing a soccer player
doing a spinning trick with the ball, surrounded by flashing
lights and a vibrant soccer field.

Here are 3 thumbnails generated by the Amazon Nova Canvas foundation model:

Amazon Polly

Let's generate our audio track using Amazon Polly. Some voice engines were available only in certain AWS regions, so I switched to US East (N. Virginia) us-east-1 region.

I was trying different engines and voices, but for that one I used "Generative" engine (the most expressive and adaptive speech using Generative Al), "English, Indian" language variant and "Kajal, Female" voice.

Let's use audio input generated by Amazon Nova Micro:

Check out these amazing soccer tricks!
The player spin and flip the ball in incredible ways!

Here is an voice-over narration generated by the Amazon Polly:

Amazon Nova Reel

Now it's finally time to generate the video using Amazon Nova Reel.

We can access the Amazon Nova Reel foundation model using Image/Video playground. Click "Select model" and choose Amazon category, Nova Reel model and On-demand inference.

Let's also adjust some inference parameters which are located in the "Configurations" segment on the left.

"Generate video" action is already selected by default. One thing we have to provide is a reference image, which will be a start frame for our video. We will of course use one of the thumbnails generated by the Amazon Nova Canvas foundation model.

Let's also use video prompt generated by Amazon Nova Micro:

Generate a 6-second dynamic video featuring a soccer player
performing amazing tricks with the ball, including spins and flips.
The scene should be fast-paced, full of energy, and colorful with
animated movement and lights.

Here are the video generated by the Amazon Nova Reel foundation model:

Definitely it's not perfect, but funny for sure - with all those strange movements of the soccer player body. Indeed he does the tricks in some "incredible ways" ;)

Apple iMovie

The last step will be to merge audio generated by Amazon Polly with video generated by Amazon Nova Reel.

We will use the Apple iMovie for that purpose. We just need to drag and drop both resources, place it on the timeline and export it.

Here is the final result:

Content

Here's a list of all the 32 generated videos.

Autos & Vehicles

Desert Motorcycle Adventure

Metadata

{
  "category": "Autos & Vehicles",
  "title": "Desert Motorcycle Adventure",
  "slug": "desert-motorcycle-adventure",
  "description": "Join us on a thrilling motorcycle ride through the desert! Watch this cool animation of a bike zooming across the sand with bright lights and see how it travels in the vast desert.",
  "thumbnail": "Create a dynamic and colorful thumbnail showcasing a sleek motorcycle speeding through a vast desert with bright, flashing lights. The bike should be leaving a trail of sand and dust, with a dramatic sunset in the background.",
  "video": "Generate a 6-second dynamic video with a sleek motorcycle zooming across the desert. The bike's lights flash brightly as it speeds through the sand, leaving a trail of dust and sand. The scene should be fast-paced and full of energy, with a dramatic sunset in the background.",
  "audio": "Experience the thrill of a desert motorcycle ride! Watch this sleek bike zoom across the sand with bright, flashing lights and see how it conquers the vast desert."
}

Thumbnails

Audio

Video

Exploring the Magic of Motorhomes

Metadata

{
  "category": "Autos & Vehicles",
  "title": "Exploring the Magic of Motorhomes",
  "slug": "exploring-the-magic-of-motorhomes",
  "description": "Step inside a motorhome and see how it transforms into a magical home on wheels! Watch the cool animation of a motorhome zooming through the countryside with changing lights and see how it can be your home anywhere!",
  "thumbnail": "Create a dynamic and colorful thumbnail showcasing a motorhome transforming into a magical home on wheels with spinning 'magic wheels' and flashing lights. The motorhome should be zooming through a bright, countryside landscape.",
  "video": "Generate a 6-second dynamic video with a motorhome featuring magic wheels that spin and emit flashing lights. The motorhome zooms through a vibrant countryside with animated movement and bright colors. The scene should be fast-paced and full of energy.",
  "audio": "Welcome to the magical world of motorhomes! Watch this motorhome with magic wheels zooming through a vibrant countryside."
}

Thumbnails

Audio

Video

Magic Wheels: The Future of Cars

Metadata

{
  "category": "Autos & Vehicles",
  "title": "Magic Wheels: The Future of Cars",
  "slug": "magic-wheels-the-future-of-cars",
  "description": "Discover how cars of the future will move with magic wheels! Watch the cool animation of a car zooming around with flashing lights and see how it might change our rides!",
  "thumbnail": "Create a dynamic and colorful thumbnail showcasing a futuristic car with spinning 'magic wheels' and flashing lights. The car should be zooming through a bright, neon-lit futuristic cityscape.",
  "video": "Generate a 6-second dynamic video with a futuristic car featuring magic wheels that spin and emit flashing lights. The car zooms through a vibrant, neon-lit city with animated movement and bright colors. The scene should be fast-paced and full of energy.",
  "audio": "Welcome to the future of cars! Watch this dynamic future car with magic wheels zooming through a vibrant city."
}

Thumbnails

Audio

Video

Mud Monster Truck Adventure

Metadata

{
  "category": "Autos & Vehicles",
  "title": "Mud Monster Truck Adventure",
  "slug": "mud-monster-truck-adventure",
  "description": "Join us on an offroad adventure with a monster truck in the mud! Watch the cool animation of a truck bouncing through muddy terrain with big, powerful wheels.",
  "thumbnail": "Create a dynamic and colorful thumbnail showcasing a monster truck in the mud with big, powerful spinning wheels and splashing mud. The truck should be in a muddy terrain with bright, vibrant colors.",
  "video": "Generate a 6-second dynamic video with a monster truck featuring big, powerful spinning wheels that splash mud. The truck bounces through muddy terrain with animated movement and bright colors. The scene should be fast-paced and full of energy.",
  "audio": "Experience the thrill of an offroad monster truck adventure in the mud! Watch this powerful truck with big, spinning wheels bouncing through muddy terrain."
}

Thumbnails

Audio

Video

Education

Learning with Fun: The Magic of Numbers

Metadata

{
  "category": "Education",
  "title": "Learning with Fun: The Magic of Numbers",
  "slug": "learning-with-fun-the-magic-of-numbers",
  "description": "Join us in an exciting adventure where numbers come to life! Watch the fun animation of numbers dancing and playing in a magical world.",
  "thumbnail": "Create a colorful and playful thumbnail featuring dancing numbers and magical lights in a bright, whimsical background. The numbers should look like they're having fun and playing together.",
  "video": "Generate a 6-second fun video with animated numbers dancing and playing in a magical world. The numbers should move in a lively and colorful scene, with changing lights and engaging animations. No text or statistics should be added.",
  "audio": "Welcome to the magical world of numbers! Watch these numbers dance and play in a fun and colorful adventure."
}

Thumbnails

Audio

Video

Learning with Fun: The Magic of Science

Metadata

{
  "category": "Education",
  "title": "Learning with Fun: The Magic of Science",
  "slug": "learning-with-fun-the-magic-of-science",
  "description": "Join us on a fun journey through science! Watch an exciting animation of a magical science experiment that changes colors and moves with amazing energy!",
  "thumbnail": "Create a colorful and dynamic thumbnail featuring a magical science experiment with glowing, colorful particles swirling around in a bright, futuristic lab setting.",
  "video": "Generate a 6-second dynamic video with a magical science experiment that features glowing, colorful particles swirling and changing colors. The scene should be fast-paced and full of energy, with animated movement and bright colors.",
  "audio": "Welcome to the magic of science! Watch this colorful experiment with glowing particles swirling in a futuristic lab."
}

Thumbnails

Audio

Video

Rocket Science: Blast Off!

Metadata

{
  "category": "Education",
  "title": "Rocket Science: Blast Off!",
  "slug": "rocket-science-blast-off",
  "description": "Learn about rocket science with this fun animation! Watch a rocket zoom into space with bright lights and see how it might change our future!",
  "thumbnail": "Create a dynamic and colorful thumbnail showcasing a rocket blasting off into space with bright lights and trails. The rocket should be surrounded by stars and a vibrant, colorful sky.",
  "video": "Generate a 6-second dynamic video with a rocket blasting off into space. The rocket features bright lights and trails that emit colorful sparks. The scene should be fast-paced and full of energy, showing the rocket soaring through the sky with animated movements.",
  "audio": "Welcome to rocket science! Watch this rocket blast off into space with bright lights and colorful trails."
}

Thumbnails

Audio

Video

The Magic of Magnets

Metadata

{
  "category": "Education",
  "title": "The Magic of Magnets",
  "slug": "the-magic-of-magnets",
  "description": "Learn about magnets in this fun and engaging 6-second video! Watch as a magnet attracts metal objects with cool lights and see how it works!",
  "thumbnail": "Create a colorful and dynamic thumbnail showing a magnet with glowing lines attracting metal objects like a paper clip and a nail. The background should have a bright, futuristic look.",
  "video": "Generate a 6-second dynamic video with a magnet that has glowing lines attracting metal objects like a paper clip and a nail. The magnet should move around with bright, colorful lights and animated movement. The scene should be fast-paced and full of energy.",
  "audio": "Discover the magic of magnets! Watch how they attract metal objects with bright lights and see how they work!"
}

Thumbnails

Audio

Video

Gaming

Chess Showdown: The Ultimate Battle

Metadata

{
  "category": "Gaming",
  "title": "Chess Showdown: The Ultimate Battle",
  "slug": "chess-showdown-the-ultimate-battle",
  "description": "Watch an exciting chess game unfold! See the pieces moving in a thrilling match with flashing lights and dynamic movements.",
  "thumbnail": "Create a vibrant thumbnail showing two players in an intense chess match with glowing pieces and flashing lights. The scene should be dynamic and full of energy.",
  "video": "Generate a 6-second dynamic video of an intense chess game with glowing pieces and flashing lights. The pieces move in a thrilling match, creating a fast-paced and energetic scene.",
  "audio": "Join the ultimate chess showdown! Watch the pieces move in a thrilling match with glowing lights and dynamic movements."
}

Thumbnails

Audio

Video

Retro Platformer Adventure

Metadata

{
  "category": "Gaming",
  "title": "Retro Platformer Adventure",
  "slug": "retro-platformer-adventure",
  "description": "Step into the world of classic platform games! Watch this fun animation of a character jumping over obstacles in a retro-style game world.",
  "thumbnail": "Create a vibrant thumbnail featuring a classic platformer character jumping over obstacles with pixel art style. Include colorful background elements like platforms and enemies.",
  "video": "Generate a 6-second engaging video with a classic platformer character jumping over obstacles in a retro-style game world. The scene should have animated movement, colorful platforms, and simple enemies. The animation should be fast-paced and full of energy.",
  "audio": "Welcome to the classic platformer adventure! Watch the character jump and dodge obstacles in this retro-style game world."
}

Thumbnails

Audio

Video

RTS Battle: Strategy in Action

Metadata

{
  "category": "Gaming",
  "title": "RTS Battle: Strategy in Action",
  "slug": "rts-battle-strategy-in-action",
  "description": "Step into the world of real-time strategy games! Watch this 6-second animation of a thrilling battle where armies clash with dynamic strategies and fast-paced action.",
  "thumbnail": "Create a dynamic and colorful thumbnail showcasing a real-time strategy game scene. Show two armies clashing with soldiers, tanks, and flying units in mid-action. Use bright colors and flashy effects to highlight the intense battle.",
  "video": "Generate a 6-second dynamic video featuring a real-time strategy game battle. Show armies clashing with soldiers, tanks, and flying units. Include animated movements, changing strategies, and bright, flashy effects to highlight the fast-paced action.",
  "audio": "Join the real-time strategy battle! Watch as armies clash with dynamic strategies and fast-paced action in this thrilling 6-second animation."
}

Thumbnails

Audio

Video

Tetris: The Classic Block Puzzle

Metadata

{
  "category": "Gaming",
  "title": "Tetris: The Classic Block Puzzle",
  "slug": "tetris-the-classic-block-puzzle",
  "description": "Explore the timeless world of Tetris! Watch an exciting 6-second animation of classic Tetris blocks falling and fitting together in a fun, colorful scene.",
  "thumbnail": "Create a vibrant and energetic thumbnail featuring classic Tetris blocks in motion, with bright colors and a dynamic background. Show a few blocks falling and fitting together in a neat row.",
  "video": "Generate a 6-second engaging video showcasing the classic Tetris game. Animate Tetris blocks falling and fitting together in a colorful, fast-paced scene. The blocks should move smoothly and create neat rows as they fit.",
  "audio": "Welcome to the classic Tetris! Watch the blocks fall and fit together in this exciting, colorful game."
}

Thumbnails

Audio

Video

Howto & Style

Easy Soup Cooking Fun

Metadata

{
  "category": "Howto & Style",
  "title": "Easy Soup Cooking Fun",
  "slug": "easy-soup-cooking-fun",
  "description": "Learn how to cook a simple and delicious soup with this fun and easy animation! Watch the steps to make soup in a playful and engaging way.",
  "thumbnail": "Create a cheerful and colorful thumbnail showing a pot of soup with steam rising, surrounded by fun kitchen utensils like a spoon and a whisk. The background should be a bright, happy kitchen.",
  "video": "Generate a 6-second engaging video showing a simple soup cooking process with fun animations. Start with ingredients like carrots and potatoes in a pot, then add water and stir. The pot should bubble with colorful steam and playful movements. The scene should be lively and easy to follow.",
  "audio": "Let's cook a simple soup together! Watch the fun ingredients come together in a bubbling pot."
}

Thumbnails

Audio

Video

Fashion Forward: Catwalk Chic

Metadata

{
  "category": "Howto & Style",
  "title": "Fashion Forward: Catwalk Chic",
  "slug": "fashion-forward-catwalk-chic",
  "description": "Step into the world of high fashion! Watch a model showcase a stunning outfit on the catwalk. See the elegance and style as the model walks with confidence.",
  "thumbnail": "Create a vibrant and stylish thumbnail showcasing a model in a chic outfit walking down a catwalk. The model should be in a glamorous pose with bright lights and a stylish background.",
  "video": "Generate a 6-second dynamic video featuring a model presenting a chic outfit on a catwalk. The model walks gracefully with elegant movements and changing lights. The scene should be stylish and full of energy.",
  "audio": "Discover catwalk chic! Watch this model in a stylish outfit walking with confidence and elegance."
}

Thumbnails

Audio

Video

Hair Magic: A Girl's New Haircut

Metadata

{
  "category": "Howto & Style",
  "title": "Hair Magic: A Girl's New Haircut",
  "slug": "hair-magic-a-girls-new-haircut",
  "description": "Watch a magical haircut in action! See how a hairdresser cuts a girl's hair with fun, colorful magic. The scene is full of bright colors and exciting movements.",
  "thumbnail": "Create a vibrant thumbnail showing a hairdresser with colorful magic wands, cutting a girl's hair in a bright, playful setting. The girl has a big smile, and the hair is styled with fun, animated movements.",
  "video": "Generate a 6-second engaging video with a hairdresser using colorful magic wands to cut a girl's hair. The scene is full of bright colors and animated movements, with the girl smiling and the hair changing in a fun, magical way.",
  "audio": "Watch the magic of a new haircut! See how a hairdresser uses colorful magic to cut a girl's hair in a fun and exciting way."
}

Thumbnails

Audio

Video

How to Use a Yo-Yo: Fun Tricks for Beginners

Metadata

{
  "category": "Howto & Style",
  "title": "How to Use a Yo-Yo: Fun Tricks for Beginners",
  "slug": "how-to-use-a-yoyo-fun-tricks-for-beginners",
  "description": "Learn how to use a yo-yo with fun tricks! Watch this cool animation of a kid spinning a yo-yo with amazing tricks and see how you can start too!",
  "thumbnail": "Create a fun and colorful thumbnail showing a happy kid spinning a yo-yo with spinning parts and colorful tricks. The background should be bright and playful.",
  "video": "Generate a 6-second dynamic video with a kid spinning a yo-yo with fun tricks. The yo-yo spins and emits colorful lights. The scene should be fast-paced and full of energy.",
  "audio": "Welcome to the world of yo-yo! Watch this kid spin a yo-yo with fun tricks in a bright and colorful city."
}

Thumbnails

Audio

Video

Nonprofits & Activism

Charity Run: Running Together for a Cause

Metadata

{
  "category": "Nonprofits & Activism",
  "title": "Charity Run: Running Together for a Cause",
  "slug": "charity-run-running-together-for-a-cause",
  "description": "Join us in this fun charity run animation! Watch how people come together to run, smile, and support a great cause. The video shows a fast-paced, colorful run with happy participants and bright lights.",
  "thumbnail": "Create a dynamic and colorful thumbnail showcasing a group of people running together with bright, flashing lights and a charity banner. The scene should be vibrant and energetic, set against a cheerful background.",
  "video": "Generate a 6-second dynamic video with a group of people running together in a charity run. The scene includes fast-paced animation with smiling faces, flashing lights, and colorful banners. The movement should be energetic and full of life.",
  "audio": "Join us in the charity run! Watch the energetic group of runners with bright lights and banners, coming together for a great cause."
}

Thumbnails

Audio

Video

Standing Up for Change: Peaceful Road Block

Metadata

{
  "category": "Nonprofits & Activism",
  "title": "Standing Up for Change: Peaceful Road Block",
  "slug": "standing-up-for-change-peaceful-road-block",
  "description": "See how people come together to make a difference with a peaceful road block. Watch the animation of people sitting on the road to stop car traffic and show their support for important causes!",
  "thumbnail": "Create a vibrant thumbnail showing a group of people sitting on the road with signs, blocking traffic in a peaceful manner. The scene should be set in a busy city street with bright colors and a clear message of activism.",
  "video": "Generate a 6-second engaging video with a group of people sitting on the road, blocking traffic in a peaceful way. The scene should feature animated movement, bright colors, and changing lights to show their support for important causes. No text overlays or statistics.",
  "audio": "Join us in standing up for change! Watch how people peacefully block traffic to make their voices heard for important causes."
}

Thumbnails

Audio

Video

Street Volunteers: Collecting for a Cause

Metadata

{
  "category": "Nonprofits & Activism",
  "title": "Street Volunteers: Collecting for a Cause",
  "slug": "street-volunteers-collecting-for-a-cause",
  "description": "See how street volunteers collect money in a can for a good cause! Watch the fun animation of people helping each other and the bright lights of the city.",
  "thumbnail": "Create a colorful thumbnail showing street volunteers with cans collecting money, surrounded by bright city lights and animated movement. The volunteers should be smiling and happy.",
  "video": "Generate a 6-second dynamic video with street volunteers collecting money in cans, surrounded by bright city lights and animated movement. The scene should be fast-paced, full of energy, and show people helping each other.",
  "audio": "Meet the street volunteers! Watch them collect money for a good cause in the bright city lights. Join them in making a difference!"
}

Thumbnails

Audio

Video

Tree Guardians: Protecting Nature's Champions

Metadata

{
  "category": "Nonprofits & Activism",
  "title": "Tree Guardians: Protecting Nature's Champions",
  "slug": "tree-guardians-protecting-natures-champions",
  "description": "Meet the brave activists who stand firm, chained to trees to protect them from bulldozers. Watch the powerful animation of their dedication to saving our forests!",
  "thumbnail": "Create a striking thumbnail showing activists, with their hands chained to a tree, standing firm against a bulldozer. The scene is set in a lush forest with vibrant green trees and a bulldozer in the background. Use bright colors to highlight the activists' determination.",
  "video": "Generate a 6-second engaging animation of activists chained to trees, standing firm against a bulldozer. The scene shows the activists with determined faces, the trees with vibrant green leaves, and the bulldozer in the background. The animation should have dynamic movements and bright colors to convey the activists' courage and the urgency of the situation.",
  "audio": "Meet the tree guardians! Watch these brave activists stand firm, chained to trees, protecting our forests from bulldozers."
}

Thumbnails

Audio

Video

Pets & Animals

Dancing Pets: A Fun Animal Show

Metadata

{
  "category": "Pets & Animals",
  "title": "Dancing Pets: A Fun Animal Show",
  "slug": "dancing-pets-a-fun-animal-show",
  "description": "Watch cute animals dance in this fun animation! See how pets like dogs, cats, and birds move to the beat with colorful lights and happy music!",
  "thumbnail": "Create a colorful and lively thumbnail showing dancing pets like dogs, cats, and birds with glowing, spinning lights around them. The scene should be set in a bright, happy park with a cheerful atmosphere.",
  "video": "Generate a 6-second dynamic video featuring cute animals dancing to the beat with colorful lights and animated movements. The scene should be fast-paced, full of energy, and include happy, dancing pets with glowing effects.",
  "audio": "Join the fun with dancing pets! Watch how dogs, cats, and birds move to the beat with colorful lights and happy music."
}

Thumbnails

Audio

Video

Rattlesnake's Dance: A Wild Adventure

Metadata

{
  "category": "Pets & Animals",
  "title": "Rattlesnake's Dance: A Wild Adventure",
  "slug": "rattlesnakes-dance-wild-adventure",
  "description": "Watch a rattlesnake's mesmerizing dance in the wild! This 6-second animation shows a rattlesnake swaying and rattling its tail in a vibrant, sunny meadow.",
  "thumbnail": "Create a vivid thumbnail featuring a rattlesnake swaying gracefully in a sunny meadow, with its tail rattling and creating a dynamic visual effect. The background should be a bright, colorful meadow with wildflowers.",
  "video": "Generate a 6-second engaging animation of a rattlesnake swaying and rattling its tail in a vibrant, sunny meadow. The scene should be lively with colorful flowers and dynamic movement.",
  "audio": "Discover the rattlesnake's dance in the wild! Watch this fascinating creature swaying and rattling its tail in a sunny meadow."
}

Thumbnails

Audio

Video

Snail's Slow and Steady Adventure

Metadata

{
  "category": "Pets & Animals",
  "title": "Snail's Slow and Steady Adventure",
  "slug": "snail-slow-and-steady-adventure",
  "description": "Join a snail on its slow but steady adventure through a garden! Watch the snail's journey with colorful flowers and gentle movements.",
  "thumbnail": "Create a peaceful and colorful thumbnail showing a snail moving slowly across a garden with blooming flowers and gentle sunlight. The snail should look happy and content.",
  "video": "Generate a 6-second video with a snail making its slow journey across a vibrant garden. The snail moves gracefully among colorful flowers, with gentle and smooth movements. The scene should be calm and full of nature's beauty.",
  "audio": "Meet the snail, taking its time on a slow and steady adventure through a beautiful garden. Watch its gentle journey among the flowers."
}

Thumbnails

Audio

Video

The Amazing World of Octopus!

Metadata

{
  "category": "Pets & Animals",
  "title": "The Amazing World of Octopus!",
  "slug": "the-amazing-world-of-octopus",
  "description": "Hey there! Today we're going to explore the amazing world of octopuses. Did you know that octopuses can change color and even disappear? Watch as this clever creature shows us its amazing tricks!",
  "thumbnail": "Create a dynamic and colorful thumbnail for a video titled 'The Amazing World of Octopus!' The thumbnail should feature a close-up of a bright, curious octopus using its tentacles to perform a trick, like changing color or hiding in a shell. The background should be vibrant with ocean elements like bubbles and seaweed to highlight the underwater environment.",
  "video": "Generate a 6-second dynamic video showcasing the amazing world of octopuses. Start with a close-up of a curious octopus in an underwater setting, using its tentacles to perform a color-changing trick. The octopus should smoothly transition through different colors and then quickly hide in a small shell. The video should have a playful and vibrant atmosphere with flashes of different colors to keep the audience engaged.",
  "audio": "Today we're going to explore the amazing world of octopuses. Did you know that octopuses can change color and even disappear?"
}

Thumbnails

Audio

Video

Sports

Amazing Soccer Tricks

Metadata

{
  "category": "Sports",
  "title": "Amazing Soccer Tricks",
  "slug": "amazing-soccer-tricks",
  "description": "Watch this cool soccer player do amazing tricks on the field! See how he spins the ball and makes it move in crazy ways!",
  "thumbnail": "Create a dynamic and colorful thumbnail showing a soccer player doing a spinning trick with the ball, surrounded by flashing lights and a vibrant soccer field.",
  "video": "Generate a 6-second dynamic video featuring a soccer player performing amazing tricks with the ball, including spins and flips. The scene should be fast-paced, full of energy, and colorful with animated movement and lights.",
  "audio": "Check out these amazing soccer tricks! The player spin and flip the ball in incredible ways!"
}

Thumbnails

Audio

Video

Classic Golf: The Art of the Swing

Metadata

{
  "category": "Sports",
  "title": "Classic Golf: The Art of the Swing",
  "slug": "classic-golf-the-art-of-the-swing",
  "description": "Step into the world of classic golf! Watch this fun animation of a golfer taking a perfect swing and hitting the ball into a beautifully designed golf course.",
  "thumbnail": "Create a dynamic and colorful thumbnail showcasing a golfer taking a powerful swing with a classic golf club, hitting a bright yellow ball. The scene should be set in a picturesque golf course with green grass and a clear blue sky.",
  "video": "Generate a 6-second dynamic video with a golfer taking a powerful swing and hitting a bright yellow ball into a beautifully designed golf course. The scene should be fast-paced, full of energy, and highlight the golfer's skill and the vibrant golf course.",
  "audio": "Welcome to the world of classic golf! Watch this golfer take a perfect swing and hit the ball into a beautiful golf course."
}

Thumbnails

Audio

Video

Retro Hockey: A Blast from the Past

Metadata

{
  "category": "Sports",
  "title": "Retro Hockey: A Blast from the Past",
  "slug": "retro-hockey-a-blast-from-the-past",
  "description": "Step into the retro world of hockey! Watch this fun animation of classic hockey games with spinning pucks and retro players. See how hockey has evolved over the years!",
  "thumbnail": "Create a vibrant thumbnail featuring a classic hockey game from the past. Show a retro hockey player with a spinning puck, surrounded by colorful, old-school hockey gear and a retro arena background.",
  "video": "Generate a 6-second engaging video with a retro hockey player spinning a puck across the ice. The scene includes classic hockey gear, retro players, and a nostalgic arena background. The animation should be fast-paced with bright colors and simple movements.",
  "audio": "Welcome to the retro world of hockey! Watch this classic game with a spinning puck and nostalgic players in action."
}

Thumbnails

Audio

Video

Tennis Magic: The Spin of Champions

Metadata

{
  "category": "Sports",
  "title": "Tennis Magic: The Spin of Champions",
  "slug": "tennis-magic-the-spin-of-champions",
  "description": "Watch the magic of tennis with spinning balls and powerful serves! This animated video shows a tennis match with exciting spins and fast-moving shots.",
  "thumbnail": "Create a vibrant thumbnail featuring a tennis player hitting a powerful serve with a spinning ball, set against a bright, colorful tennis court. The ball should be glowing with energy.",
  "video": "Generate a 6-second dynamic video of a tennis match with a player hitting powerful, spinning serves. The ball should move quickly, with bright colors and animated effects. The scene should be fast-paced and full of energy.",
  "audio": "Experience the magic of tennis with spinning serves and powerful shots! Watch the player hit dynamic serves in this exciting tennis match."
}

Thumbnails

Audio

Video

Travel & Events

Adventure Awaits: Mountain Hiking

Metadata

{
  "category": "Travel & Events",
  "title": "Adventure Awaits: Mountain Hiking",
  "slug": "adventure-awaits-mountain-hiking",
  "description": "Embark on a thrilling mountain hiking adventure! Watch this fun animation of hikers climbing up a mountain with stunning views and see how hiking can be an exciting journey!",
  "thumbnail": "Create a vibrant and exciting thumbnail featuring hikers climbing up a majestic mountain with stunning views and a clear blue sky. The hikers should be smiling and looking adventurous.",
  "video": "Generate a 6-second dynamic video with animated hikers climbing up a mountain with stunning views. The scene should be fast-paced, full of energy, and highlight the beauty of the mountain and the excitement of the hikers.",
  "audio": "Join the adventure! Watch hikers climb up a majestic mountain with stunning views. It's an exciting journey!"
}

Thumbnails

Audio

Video

City Adventure: Walking Tour

Metadata

{
  "category": "Travel & Events",
  "title": "City Adventure: Walking Tour",
  "slug": "city-adventure-walking-tour",
  "description": "Join us on a fun walking tour of a city! Watch the animation of a person exploring the city streets, parks, and landmarks on foot. See how exciting city tours can be!",
  "thumbnail": "Create a vibrant thumbnail showing a person walking through a city street, with parks and landmarks in the background. Use bright colors and dynamic poses to capture the excitement of the tour.",
  "video": "Generate a 6-second engaging video featuring a person walking through a city, exploring parks, and visiting landmarks. The animation should have moving parts and changing lights, with a fast-paced and energetic vibe.",
  "audio": "Embark on a city adventure! Watch this person explore the city streets, parks, and landmarks on foot. It's a fun and exciting walking tour!"
}

Thumbnails

Audio

Video

Exploring Magical Festivals

Metadata

{
  "category": "Travel & Events",
  "title": "Exploring Magical Festivals",
  "slug": "exploring-magical-festivals",
  "description": "Join us on a journey to magical festivals around the world! Watch this fun animation to see colorful parades, dancing lights, and happy people celebrating together.",
  "thumbnail": "Create a vibrant and colorful thumbnail featuring a festival scene with dancing lights, colorful costumes, and people smiling and celebrating. The scene should be lively and full of joy.",
  "video": "Generate a 6-second dynamic video showcasing a magical festival with colorful parades, dancing lights, and happy people celebrating. The scene should be lively, full of energy, and filled with bright colors.",
  "audio": "Welcome to magical festivals around the world! Watch colorful parades, dancing lights, and happy people celebrating together."
}

Thumbnails

Audio

Video

Live from the Big Conference!

Metadata

{
  "category": "Travel & Events",
  "title": "Live from the Big Conference!",
  "slug": "live-from-the-big-conference",
  "description": "Join us at a big conference where experts share exciting ideas! Watch the lively speaker and see how people from around the world come together to learn and share.",
  "thumbnail": "Create a vibrant thumbnail showing a lively conference scene with a speaker on stage, surrounded by an engaged audience. Include colorful banners and a backdrop of a modern conference hall.",
  "video": "Generate a 6-second video featuring a lively conference scene. Show a speaker on stage with a dynamic presentation, surrounded by an enthusiastic audience. Include animated elements like moving slides and bright lights.",
  "audio": "Welcome to the big conference! Watch the lively speaker sharing exciting ideas with an engaged audience."
}

Thumbnails

Audio

Video

Repository

You can find all of artefacts generated by AI and used prompt in the GitHub JacekKosciesza/FakeTube repository.

Initial Requirements using Gherkin, GitHub, CodeCatalyst - FakeTube #1

Jacek Kościesza — Mon, 31 Mar 2025 15:43:56 +0000

We are building FakeTube - a YouTube clone software engineering project using cloud-native and web technologies. As a first step we have to define our vision and project requirements.

YouTube is arguably one of the biggest software engineering projects in the world. Since it was founded in February 2005, it took more than 20 years of development, thousands of people involved and billions of dollars spent.

Is it even possible for a single software engineer or at least a small team or community to approach a YouTube scale project?

How complex is YouTube?

Interesting statistics

YouTube is huge without a doubt. We can find some astonishing statistics on the official How YouTube Works website and YouTube article on Wikipedia.

it is the second-most-visited website in the world, after Google Search

In January 2024, YouTube had more than 2.7 billion monthly active users, who collectively watched more than one billion hours of videos every day.

Let's think about what it means: 2.7 billion users - that's around 1/3 of the world population

videos were being uploaded to the platform at a rate of more than 500 hours of content per minute

Imagine compute resources needed to process all of those videos: transcoding, thumbnail generation, copyright protection.

as of mid-2024, there were approximately 14.8 billion videos in total

This means a huge amount of space needed to store all those videos.

Modern cloud

Those are shocking numbers, but this is all a consequence of a massive scale of YouTube.

Maybe with a right approach to software architecture and by using cloud-native, serverless technologies with automatic scaling, built-in high availability we would be able to achieve it with limited engineering resources?

Let's take Object Storage Services (OSS) as an example. With modern services from the biggest cloud providers you can potentially store any amount of data like videos and thumbnails.

The Amazon S3 (Simple Storage Service documentation states that it's:

Object storage built to retrieve any amount of data from anywhere

Sounds like a perfect fit for our project, but is that the case with other building blocks needed for FakeTube? We will definitely look into that, do some experiments and try to find the limits.

Feature set

How about a feature set? Does YouTube have a lot of features? Well...the answer is yes.

It's not even a single product, rather a family of products that complement each other and create an entire platform. A quick look at the How YouTube Works footer reveals:

YouTube Main Web App
YouTube Main Mobile App
YouTube Kids
YouTube Music
YouTube Originals
YouTube Podcasts
YouTube Premium
YouTube Select
YouTube Studio
YouTube TV

It's also the entire ecosystem connecting viewers, creators and business (or advertisers) through ad revenue sharing, so it's much more complex than just uploading and watching videos.

For those interested in the evolution of YouTube, the Creator Insider channel provides valuable updates on product development, new features, and changes. It offers truly interesting insights directly from the YouTube team.

Minimum Viable Product (MVP)

What's involved in building a platform as complex as YouTube?

There is a famous proverb:

How do you eat an elephant? One bite at a time!

meaning that large tasks can be accomplished by breaking them down into smaller, manageable steps. That's exactly what we are going to do.

We will start with something simple and progressively enhance it over time. It will be a real MVP (Minimum Viable Product).

A minimum viable product (MVP) is a version of a product with just enough features to be usable by early customers who can then provide feedback for future product development.

Vision

What would be the minimum feature set that would bring value to FakeTube users?

First of all we have to focus on a single product and type of user. There are three main user groups: creators, viewers and advertisers.

It doesn't make sense to start with advertisers without viewers, because you wouldn't have an audience for the ads.

It also doesn't make sense to start with creators, because no one would spend time creating a video and uploading it knowing that there is no way for other people to watch it.

So the natural choice is to start with viewers. That means that we will focus on the features from the YouTube Main App.

In the first version there will be no way to upload a video (that's part of YouTube Studio), so we will have to start with a predefined video content.

Ideally we can start with a single page with a list of videos, which can be watched in an inline video player and some static layout around it with branding and navigation elements.

That sounds like a simplified version of YouTube Home page. It also feels like a real MVP, realistic to build and bringing some value for users (browse list of videos and watch them). It will be a great foundation for future development and experiments.

Design

One of the benefits of building a clone is the reduced upfront effort. Instead of defining requirements and designing the user experience, your main focus becomes understanding and replicating the existing application's features and design.

While creating a new product is undoubtedly exciting, this project prioritizes software engineering. Therefore, leveraging an existing UX/UI design and clearly defining the pre-existing behavior of the application will allow us to begin development as quickly as possible.

It doesn't mean that it will be trivial to discover all the features and nuances of YouTube. At some point we will have to put on a Business Analyst or a Product Owner hat and spend probably a lot of time discovering how YouTube works under the hood, doing DDD (Domain Driven Design) analysis or creating Figma designs.

For now let's look at the existing YouTube app and decide what we will implement or what is more important - what we will skip for now.

Perfection is achieved, not when there is nothing to add, but when there is nothing left to take away.

~ Antoine de Saint Exupéry

Chrome DevTools

Chrome DevTools will be our helpful tool, which we will use like a chainsaw to cut off unnecessary things. It will also give us better understanding of the components hierarchy and naming conventions.

Let's open the YouTube home page in a Chrome browser and activate Chrome DevTools inspect mode with a shortcut: Command+Shift+C on MacOS or Ctrl+Shift+C on Windows.

Application Shell

We can start with inspecting and removing components from the static layout around the home page, which is sometimes called Application Shell.

Masthead

Top element is called Masthead. YouTube UX/UI is based on the Material Design visual language and this element is called Top App Bar in that convention.

There are three sections: start, center, end. We only need the start section with a Guide Button and Logo, so let's remove other components (just select the element using the inspect tool and delete it).

center section with Search - OUT
end section with Buttons - OUT

We are like Javier Milei eliminating unnecessary ministries.

App Drawer and Guide

Now let's look at the sidebar on the left, which is known as a Navigation drawer in a Material Design world.

It's an App Drawer with a Guide inside it. It can be opened and closed using the Guide Button located in the Masthead. There are many items inside the Guide, but we only need a Home item for now. So let's put our inspect tool to work and remove all those elements.

Mini Guide

When we close the App Drawer using Guide Button, we will see another navigation bar called Mini Guide. It has the most commonly used navigation elements, but again, we only need Home item at this point. Let's remove other items.

Application Shell starts to look quite good - there are only elements which we need in the first version of FakeTube. Now it's time for home page cleanup.

Homepage

We will start with bigger elements. First one is a Header with Feed Filter Chip Bar, we will implement filtering later, so let's remove it for now. Second thing is any Shelf element like Shorts or Trending, we don't need it, so OUT.

There are also a few smaller elements on the Media item (Card in Material Design), which are not necessary: View Count, Verified Badge or Action Menu Button - OUT.

After all those drastic cuts, we have something more realistic to implement in a first version:

But what about the mobile version? Let's take a look.

Mobile

Application Shell

The most obvious difference is related to navigation. There is no App Drawer, Guide or Mini Guide. Instead there is a Pivot Bar, which is a Bottom App Bar in Material Design terms. As previously we only need a Home item. We can also remove the Search Button from the Masthead.

Homepage

Homepage looks very similar to the desktop/tablet version. We have to remove the Shorts Shelf and a few smaller things from the Media item: View Count, Separator and Action Menu Button.

Final result looks like this (BTW: sorry for the Rachel Zegler showing her middle finger)

Naming convention

Although YouTube is using Material Design, it doesn't follow its naming convention. One of the examples is Masthead instead of Top App Bar.

There are also differences in a naming convention between mobile and desktop/tablet versions of the web app (e.g. Channel Avatar vs Channel Thumbnail or Title vs Headline) and some component names are very generic like ytd-rich-item-renderer (which doesn't necessary makes sense for us when starting from scratch).

Naming things is not a trivial task.

There are only two hard things in Computer Science: cache invalidation and naming things.

~ Phil Karlton

So, the question is: how should we approach naming our components?

Let's try to stick to the YouTube naming convention as closely as possible. I think that it will be easier to compare our implementations, talk with people involved in YouTube and go through the documentation.

We will have to sometimes be creative and make some trade-offs, but it won't be set in stone, so if needed we will change it in the future.

Components hierarchy

How are we going to organise the building blocks of the FakeTube? There are many approaches, tools and conventions. At some point we will explore things like Storybook, Atomic Design and create clear UX/UI mockups in Figma. For now let's focus on a simple hierarchy of components and screenshots from the previous section.

Based on the exercise with Inspect Mode in Chrome DevTools and some creative approach to naming, here's a proposition of the components hierarchy.

- Application Shell:
    - Masthead:
        - Guide Button
        - Logo:
            - Logomark
            - Logotype
    - App Drawer:
        - Guide:
            - Item:
                - Icon
                - Title
        - Overlay
    - Mini Guide:
        - Item:
            - Icon
            - Title
    - Pivot Bar:
        - Item:
            - Icon
            - Title
- Home Page:
    - Browse Grid:
        - Media Skeleton
        - Spinner
        - Media Item:
            - Thumbnail:
                - Image
                - Player:
                    - Video
                    - Unmute/Mute Button
                    - Progress Bar
                - Time Status
            - Details:
                - Channel Avatar
                - Meta:
                    - Title
                    - Metadata:
                        - Channel Name
                        - Separator
                        - Publish Date

Requirements

People define requirements in different ways, but the end goal is the same: make it very clear what a feature is, what the user interface should look like, and how it should all work. Developers should know how to build it, and testers should know how to test it.

Requirements typically include a feature description, UX/UI mockups, and more formal acceptance criteria (set of conditions that is required to be met before deliverables are accepted).

My proposition is to define requirements using sections like this:

Section	Purpose
Overview	Short description of the feature
Design	Screenshots of the UX/UI design
Acceptance Criteria	Detailed BDD (Behavior-Driven Development) style specification using Gherkin language
Links	Useful links
Dependencies	Related features or subtasks

Using BDD (Behavior-Driven Development) and Gherkin language to express the behaviour and expected outcomes of a feature can have a lot of benefits. On the one hand it uses natural-language constructs (English-like sentences), so it can be easily understood by everyone, on the other hand it is precise enough to serve as a foundation for automated tests in the future.

Let's define our features, one by one.

Application Shell

Overview

The Application Shell provides a consistent and responsive user interface framework or skeleton, which has elements like navigation bars, headers, footers, sidebars and basic layout structure. App shell loads very quickly, then the dynamic content specific to then current page or section is loaded and injected into the shell.

Design

Acceptance criteria

Feature: Application shell

As a user I want to see an application shell, which is responsive
and adapts to different screen resolutions.

Scenario: Extra small resolution
  Given screen resolution is maximum "600px"
  Then I should see a "Masthead"
  And I should see a "Pivot Bar"

Scenario: Small resolution
  Given screen resolution is minimum "601px"
  And screen resolution is maximum "791px"
  Then I should see a "Masthead"
  And I should NOT see a "Mini Guide"
  And "App Drawer" should have a "temporary" variant
  And "App Drawer" should be "closed"

Scenario: Medium resolution
  Given screen resolution is minimum "792px"
  And screen resolution is maximum "1312px"
  Then I should see a "Masthead"
  And I should see a "Mini Guide"
  And "App Drawer" should have a "temporary" variant
  And "App Drawer" should be "closed"

Scenario: Large resolution
  Given screen resolution is minimum "1313px"
  Then I should see a "Masthead"
  And I should NOT see a "Mini Guide"
  And "App Drawer" should have a "persistent" variant
  And "App Drawer" should be "opened"

Dependencies

Masthead
App Drawer
Mini Guide
Pivot Bar

Masthead

Overview

Masthead is a top app bar, which displays information and actions relating to the current screen as well as static elements related to branding, navigation, and search.

Design

Acceptance criteria

Feature: Masthead

As a user I want to see a top app bar with a logo and a hamburger
menu button, which opens or closes the navigation drawer sidebar.
The logomark is the symbol or icon, and the logotype is the name
of the company or brand. 

Scenario: Extra small resolution
  Given screen resolution is maximum "600px"
  Then I should NOT see a "Guide Button"
  And I should see a "Logo"

Scenario: Small resolution
  Given screen resolution is minimum "601px"
  Then I should see a "Guide Button"
  And I should see a "Logo"

Scenario: Logomark
  Given "Logo" is visible
  Then I should see "FakeTube" logomark

Scenario: Logotype
  Given "Logo" is visible
  Then I should see "FakeTube" logotype

Scenario: Click logo
  When I click a "Logo"
  Then I should go to "/" URL

Scenario: Hover over logo
  When I "hover" over logo
  Then I should see "FakeTube Home" tooltip

Dependencies

Guide Button
Logo

App Drawer

Overview

App drawer is a navigation sidebar, which provides an ergonomic access to a site navigation.

Design

Acceptance criteria

Feature: App Drawer

As a user I want to see a left sidebar with a navigation menu.
It should be temporary or persistent variant, depending on the
screen resolution. Can be opened or closed by a hamburger menu button.

Scenario: No app drawer
  Given screen resolution is maximum "600px"
  Then I "App Drawer" should NOT be present

Scenario: Closed temporary variant
  Given screen resolution is minimum "601px"
  And screen resolution is maximum "1312px"
  Then "App Drawer" should have a "temporary" variant
  And "App Drawer" should be "closed"

Scenario: Opened temporary variant
  Given screen resolution is minimum "601px"
  And screen resolution is maximum "1312px"
  And "App Drawer" has a "temporary" variant
  And "App Drawer" is "closed"
  When I click "Guide Button"
  Then "App Drawer" should be "opened"

Scenario: Opened persistent variant
  Given screen resolution is minimum "1313px"
  Then "App Drawer" should have a "persistent" variant
  And "App Drawer" should be "opened"
  And I should see a "Guide"

Dependencies

Guide

Guide

Overview

Guide is a navigation menu, which is inside a navigation drawer sidebar.

Design

Acceptance criteria

Feature: Guide

As a user I want to see a left sidebar with navigation items.

Scenario: Home item
  Given "Guide" is "opened"
  Then I should see "/" link "Item"
  And "Item" should have "Home" icon
  And "Item" should have "Home" title

Mini Guide

Overview

Mini Guide is a mini variant of a persistent navigation drawer sidebar with a navigation menu inside.

Design

Acceptance criteria

Feature: Mini Guide

As a user I want to see a left sidebar with navigation items.

Scenario: Home item
  Given screen resolution is minimum "793px"
  And screen resolution is maximum "1312px"
  Then I should see a "Mini Guide"
  And I should see "/" link "Item"
  And "Item" should have "Home" icon
  And "Item" should have "Home" title

Pivot Bar

Overview

Pivot Bar is a bottom navigation bar that allows users to switch between primary views in an app.

Design

Acceptance criteria

Feature: Pivot Bar

As a user I want to switch between different views in the
application.

Scenario: Extra small resolution
  Given screen resolution is maximum "600px"
  Then I should see a "Pivot Bar"
  And I should see "/" link "Item"
  And "Item" should have "Home" icon
  And "Item" should have "Home" title

Home Page

Overview

Home Page is the main page, which displays video feed in a form of a responsive grid of media items or media skeleton when content is loading.

Design

Acceptance criteria

Feature: Home Page

As a user I want to see a video feed on the main page.

Scenario: Home page
  Given I am on the "/" URL
  Then I should see a "Home Page"

Scenario: Content loading
  Given video feed is "loading"
  Then I should see a "Media Skeleton"
  And I should see a "Thumbnail" placeholder
  And I should see a "Channel Avatar" placeholder
  And I should see a "Title" placeholder
  And I should see a "Channel Name" placeholder 

Scenario: Browse Grid
  Given I am on the "Home Page"
  Then I should see a "Grid" layout
  And there is a "column gap" of "16px"
  And there is a "row gap" of "32px"
  And each "item" is the "same size"
  And minimum "item" width is "310px"

Scenario: Dynamic number of columns
  Given "Home Page" width is "resized"
  Then number of "Grid" columns should be adjusted
  And it should be based on number of "310px" items
      which will fit horizontally

Dependencies

Browse Grid
Media Skeleton
Media Item

Media Item

Overview

Media item represents a video. I look similar to a Material Design's Card component with a thumbnail and details about a given video. Thumbnail can be replaced by a real video player in an autoplay mode.

Design

Acceptance criteria

Feature: Media Item

As a user I want to see a card which represents a video.
It should show a video thumbnail and detailed metadata
related to video and channel.

Scenario: Thumbnail
  Given "Media" is loaded
  Then I should see a video a "Thumbnail"
  And "Image" aspect ratio is "16/9"
  And I should see a "Time status" badge

Scenario: Details
  Given "Media" is loaded
  Then I should see a "Channel Avatar"
  And I should see a "Channel Name"
  And I should see video a "Title"
  And I should see a a "Publish Date"

Scenario: Player
  Given "Media" is loaded
  And I "hover" over "Media" item
  Then I should see a video a "Player"
  And it should "autoplay"
  And "Progress Bar" should show current progress
  And "Time Status" should show current playback time

Scenario: Unmute
  Given "Player" is visible
  And video is "muted"
  When I click "Unmuted" button
  Then video should be "unmuted"

Scenario: Mute
  Given "Player" is visible
  And video is "unmuted"
  When I click "Muted" button
  Then video should be "muted"

Project Management

We will need some project management tool, where we can create our backlog of tasks and track its progress. For a start it can be a simple Kanban style board with only 3 columns

Todo
In progress
Done

I used a few different tools over the years, like Jira, GitLab or Asana, but a lot of open-source projects are just using GitHub, not only as a repository, but also for project planning and tracking. It's very popular, quite powerful and free, that's why we will use it as our primary tool.

At the same time I want to explore and test what's available from AWS (Amazon Web Services), because it's my cloud provider of choice. That's why I will also look into Amazon CodeCatalyst and compare it with GitHub.

GitHub

GitHub offers GitHub Projects, which

is an adaptable, flexible tool for planning and tracking work on GitHub.

That's exactly what we need.

I will start by going to my GitHub account, selecting the "Projects tab" and clicking the "New Project" button. Let's select the "Team planning" template, name our project "FakeTube" and click the "Create project" button.

Project was successfully created, so now we can create our backlog. Click "+ Add item" at the bottom of the "Todo" column. We will name the item "Application Shell" and select the "Create new issue" button. We will select the "JacekKosciesza/FakeTube" repository and use "Blank issue" for now. We can copy paste our requirements prepared earlier as an issue description. Our first backlog item is ready.

Cool thing is that GitHub markdown supports syntax highlighting for Gherkin language out of the box.

We have to do one more change in the project configuration - increase the limit of allowed items in the "Todo" column. Column limit of 15 items should be enough for now.

Now let's create all the remaining backlog items.

Amazon CodeCatalyst

Amazon CodeCatalyst allows you to do similar things in terms of project management as GitHub. It also has a concept of projects and issues.

You can plan work, collaborate on code, and build, test, and deploy applications with continuous integration/continuous delivery (CI/CD) tools.

Use issues to create backlogs and monitor the status of in-progress tasks with boards. Creating and maintaining a healthy backlog of items for your team to work on is an important part of developing software.

I already created a personal JKosciesza space in CodeCatalyst, but I don't have any projects yet. Let's create one by clicking the "Create project" button.

We will "Start from scratch" and name the project "FakeTube". For the final confirmation let's click "Create project" again.

Let's open the "Issues" tab. By default there are 4 columns

To do
In progress
In review
Done

At the moment we don't need an "In review" column, plus we didn't use it in GitHub, so let's remove it. We have to open the "Active issues" dropdown and click "Settings". At the very bottom there is a "Statuses" section, where we can disable the "In review" column.

Now we can create our backlog. Click "Create issue", put "Application Shell" as a title and copy-paste requirements which we prepared earlier as an issue description.

Unfortunately it seems that CodeCatalyst doesn't support syntax highlighting for a Gherkin language.

Now let's create all the remaining backlog items.

Repository

You can find all of the acceptance criteria (Gherkin feature files) and components hierarchy (YAML file) in the GitHub JacekKosciesza/FakeTube repository. GitHub project is here: FakeTube.

DJI FlightHub Sync: Media File Direct Transfer to AWS

Jacek Kościesza — Sun, 31 Mar 2024 10:19:49 +0000

There are many drone management platforms and DJI has its own called FlightHub 2. It's quite a powerful software, where you can do a route planning, mission management, watch livestream from a drone or do some basic media files management.

Drones have many use cases, so sometimes there is a need to customize your workflow - e.g. use your own AI/ML models for object detection or share media files captured by a drone to with a 3rd party software.

To achieve this - you have to somehow integrate your software with the DJI ecosystem. There are a few possibilities how to do this.

DJI Cloud API

There is DJI Cloud API, which is a powerful framework that allows developers to interact with DJI drones and their associated data through common standard protocols such as MQTT, HTTPS, and WebSocket.

It gives you a great flexibility, but in some cases it would be too much work. The problem is that you can either use FlightHub 2 or your Cloud API based solution. Using both at the same time is not supported, see Can the third-party platform developed by Cloud API and Flighthub 2 be used at the same time support topic.

This means that you can't for example process media files in our own software, but do the rest e.g. route planning, mission management in FlightHub 2. You would have to also implement those advanced features in your app.

Fortunately, DJI has created a solution for such use cases - FlightHub Sync.

FlightHub Sync

FlightHub Sync is a feature within DJI FlightHub 2 that facilitates communication and data exchange between FlightHub 2 and third-party platforms. This includes APIs for

Media File Direct Transfer
Telemetry Data Transfer
Stream Forwarding

We will focus on media files (photos, videos) transfer.

To configure FlightHub Sync, you must have "Super Admin" or "Organization Admin" role. Go to My Organization and click "Organization Settings" action (icon button with a "cog").

You will see FlightHub Sync (Beta) configuration in the upper-right corner.

Click "Details >" link and you will see FlightHub Sync configuration divided into sections.

We are interested in "Basic Information" and "Media File Direct Transfer" settings. Let's explore what information we will have to provide.

Basic Information

We have to configure a few things

Organization Key
Third-Party Cloud Name
Webhook URL

Format will be somethings like this:

{
  "Organization Key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "Third-Party Cloud Name": "My app",
  "Webhook URL": "https://xxxxxxxxxx.execute-api.eu-west-1.amazonaws.com/prod/dji/flighthub2/notify"
}

We can find more info about this in Configure Information on FlightHub Sync.

Organization Key

"Organization Key" is just a very long (64 hexadecimal digits) unique ID for the organization, which is generated by FlightHub 2.

It's used for example in FlightHub Sync APIs. When you call an API endpoint e.g. Get Task Details - you have to provide it as a header parameter.

Third-Party Cloud Name

It's a name of the third-party cloud platform, so an arbitrary name of your application. Let's use something like "My app".

Webhook URL

It's a unique URL for receiving notifications from FlightHub 2, so the endpoint which we have to provision.

When media files are uploaded - FlightHub 2 will send a POST request to notify us about synced files. Body of the callback will be similar to this:

{
  "notify_type": "way_line_file_upload_complete",
  "org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "org_name": "My Organization",
  "prj_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "prj_name": "My Project",
  "sn": "XXXXXXXXXXXXXX",
  "task_info": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_type": "way_line",
    "tags": []
  },
  "files": [
    {
      "id": 123456,
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "file_type": 10,
      "sub_file_type": 0,
      "name": "DJI_20240329091034_0001",
      "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/DJI_20240329091034_0001.jpeg"
    },
    {
      "id": 123457,
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "file_type": 10,
      "sub_file_type": 0,
      "name": "DJI_20240329091112_0002",
      "key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/DJI_20240329091112_0002.jpeg"
    }
  ],
  "folder_info": {
    "expected_file_count": 2,
    "uploaded_file_count": 2,
    "folder_id": 123458
  }
}

Media File Direct Transfer

We have to configure only one thing

Storage Location

It's a JSON string, like this:

{
  "access_key_id": "XXXXXXXXXXXXXXXXXXXX",
  "access_key_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "region": "eu-west-1",
  "bucket": "flighthub2-xxxxxxxxxxxx",
  "arn": "arn:aws:iam::xxxxxxxxxxxx:role/flighthub2",
  "role_session_name": "flighthub2",
  "provider": "aws" 
}

We can find more info about this configuration in Configure Media File Direct Transfer and FlightHub Sync Documentation.

Storage Location

Storage location is a configuration of OSS (Object Storage Service).

According to FlightHub Sync Documentation - currently supported OSS solutions are

AWS (Simple Storage Service)
Alibaba Cloud (Object Storage Service)

Project

To make it work, we will have to also enable Media File Direct Transfer on the FlightHub 2 project level.

Important thing to note is that:

When enabled, data collected by dock will only be uploaded to My app. DJI FlightHub 2 will not receive any data

Infrastructure

It's now clear that we have to build a cloud based infrastructure to integrate our solution with FlightHub Sync.

Two high level building blocks will be

OSS (Object Storage Service)
API (Application Programming Interface)

Let's build our solution using AWS. We will use AWS CDK (Cloud Development Kit) and TypeScript to define our cloud application resources.

AWS

OSS (Object Storage Service)

Our OSS solution will include two things: S3 bucket where media files will be uploaded and access configuration using IAM.

S3 (Simple Storage Service)

Let's start with defining flighthub2-xxxxxxxxxxxx bucket, where media files will be uploaded by Media File Direct Transfer feature of FlightHub Sync. Bucket name must be globally unique, so we will add account number as a postfix.

s3.cdk.ts

import { Construct } from "constructs";
import * as cdk from "aws-cdk-lib";
import * as s3 from "aws-cdk-lib/aws-s3";

export class S3CdkConstruct extends Construct {
  public bucket: s3.Bucket;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.bucket = new s3.Bucket(this, "bucket", {
      bucketName: `flighthub2-${cdk.Stack.of(this).account}`,
    });

    new cdk.CfnOutput(this, "bucket", {
      value: this.bucket.bucketName,
    });
  }
}

IAM (Identity and Access Management)

Now let's define flighthub2 user and role. User will not have access to anything, but using AWS STS (Security Token Service) he will be able to assume flighthub2 role and get temporary security credentials with access to the Amazon S3 bucket.

iam.cdk.ts

import { Construct } from "constructs";
import * as cdk from "aws-cdk-lib";
import * as iam from "aws-cdk-lib/aws-iam";

export class IamCdkConstruct extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const user = new iam.User(this, "User", {
      userName: "flighthub2",
    });

    const accessKey = new iam.CfnAccessKey(this, "CfnAccessKey", {
      userName: user.userName,
    });

    new cdk.CfnOutput(this, "access_key_id", { value: accessKey.ref });
    new cdk.CfnOutput(this, "access_key_secret", {
      value: accessKey.attrSecretAccessKey,
    });

    const role = new iam.Role(this, "role", {
      assumedBy: new iam.ArnPrincipal(user.userArn),
      roleName: "flighthub2",
      managedPolicies: [
        // TODO: restrict it to flighthub2-xxxxxxxxxxxx bucket and s3:PutObject action
        iam.ManagedPolicy.fromAwsManagedPolicyName("AmazonS3FullAccess")
      ],
    });

    new cdk.CfnOutput(this, "arn", { value: role.roleArn });
  }
}

Keep in mind that we attached AmazonS3FullAccess policy to the flighthub2 role. For the production ready solution we should limit access to the flighthub2 bucket we created and allow only uploading files, so s3:PutObject action. This is example of "Principle of least privilege".

API (Application Programming Interface)

API will consist of a single endpoint, which will get notification about uploaded files. We will build it using API Gateway and a Lambda function.

API Gateway

Let's start with defining REST API using API Gateway

gw.cdk.ts

import * as cdk from "aws-cdk-lib";
import * as gw from "aws-cdk-lib/aws-apigateway";
import { Construct } from "constructs";

export class ApiGatewayCdkConstruct extends Construct {
  public api: gw.RestApi;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.api = new gw.RestApi(this, "my-app");
  }
}

Next we will create our endpoint by defining resources and method for our webhook and integrating a lambda function with it.

api.cdk.ts

import * as gw from "aws-cdk-lib/aws-apigateway";
import * as path from "path";
import { Construct } from "constructs";

import { ApiGatewayCdkConstruct } from "../../../gw.cdk";
import { LambdaCdkConstruct } from "../../../lambda.cdk";

interface Props {
  apigateway: ApiGatewayCdkConstruct;
}

export class ApiCdkConstruct extends Construct {
  constructor(scope: Construct, id: string, { apigateway: { api } }: Props) {
    super(scope, id);

    const dji = api.root.addResource("dji", {
      // TODO: restrict CORS
      defaultCorsPreflightOptions: {
        allowHeaders: gw.Cors.DEFAULT_HEADERS,
        allowMethods: gw.Cors.ALL_METHODS,
        allowOrigins: gw.Cors.ALL_ORIGINS,
      },
    });
    const flighthub2 = dji.addResource("flighthub2");
    const notify = flighthub2.addResource("notify");

    const notifyLambda = new LambdaCdkConstruct(this, "Notify", {
      name: "dji-flighthub2-notify",
      description: "Notification from DJI FlightHub 2",
      entry: path.join(__dirname, "./functions/notify.lambda.ts"),
    });

    notify.addMethod("POST", new gw.LambdaIntegration(notifyLambda.function));
  }
}

Keep in mind that CORS configuration is very permissive. For the production ready solution we should restrict it.

Lambda

Lambda function will be a core of our workflow. It will get a notification about uploaded media files. What we will do next highly depends on our use case. We can for example process uploaded files (generate thumbnail, detect objects), notify other parts of our app about synced files e.g. using Amazon EventBridge etc.

There are also some requirements about response, which we have to send to FlightHub Sync. According to the FlightHub Sync Documentation we have to respond with HTTP status code 200 and return { code: 0 }.

notify.lambda.ts

import { APIGatewayProxyHandler } from "aws-lambda";

import { Notification } from "../notification";

export const handler: APIGatewayProxyHandler = async (event) => {
  console.log(JSON.stringify(event));

  let notification: Notification;
  try {
    notification = JSON.parse(event.body) as Notification;
  } catch (error) {
    console.error(error);
    return {
      statusCode: 400,
      body: JSON.stringify({ code: 1, message: "JSON parse error" }),
    };
  }

  switch (notification.notify_type) {
    case "way_line_file_upload_complete":
      // TODO: your workflow
      break;
    default:
      console.log("Unknown notification type", notification.notify_type);
      break;
  }

  return {
    statusCode: 200,
    body: JSON.stringify({ code: 0 }),
  };
};

notification.ts

export interface Notification {
  notify_type: "way_line_file_upload_complete" | string;
  org_id: string;
  org_name: string;
  prj_id: string;
  prj_name: string;
  sn: string;
  task_info: TaskInfo;
  files: File[];
  folder_info: FolderInfo;
}

export interface TaskInfo {
  task_id: string;
  task_type: "way_line" | string;
  tags: string[];
}

export interface File {
  id: number;
  uuid: string;
  file_type: number;
  sub_file_type: number;
  name: string;
  key: string;
}

export interface FolderInfo {
  expected_file_count: number;
  uploaded_file_count: number;
  folder_id: number;
}

Testing

After deploying our application to the AWS cloud. It's time for some testing.

Before we do a final end-to-end test with a real drone and FlightHub 2, we can write an integration test, which will mimic what FlightHub Sync is doing.

Integration Test

Let's create a simple Node.js app which will upload a file to our S3 bucket and call our webhook.

async function mediaFileDirectTransfer(): Promise<void> {
  try {
    const credentials = await getCredentialsFromAssumedRole();
    await uploadToS3(credentials);
    await sendNotification();
  } catch (error) {
    logger.error(error);
  }
}

We are doing three things here

getting credentials from the assumed role using STS
uploading test file to S3 using those credentials
sending notification to our API endpoint

When we run the app, we should see 3 things:

file should be uploaded to our S3 bucket
call to our API endpoint should return HTTP status code 200 and return { code: 0 }
we should see logs with our notification in Amazon CloudWatch

Let's see in details how the above functions are implemented.

Get credentials

async function getCredentialsFromAssumedRole(): Promise<Credentials> {
  const sts = new STSClient({
    region: process.env.REGION,
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    },
  });

  const { Credentials } = await sts.send(
    new AssumeRoleCommand({
      RoleArn: process.env.ARN,
      RoleSessionName: process.env.ROLE_SESSION_NAME
    })
  );
  logger.info(Credentials);

  return Credentials;
}

Upload file to S3

async function uploadToS3(credentials: Credentials): Promise<void> {
  const s3 = new S3Client({
    region: process.env.REGION,
    credentials: {
      accessKeyId: credentials.AccessKeyId,
      secretAccessKey: credentials.SecretAccessKey,
      sessionToken: credentials.SessionToken,
    },
  });

  const response = await s3.send(
    new PutObjectCommand({
      Bucket: process.env.BUCKET,
      Key: "fh2.txt",
      Body: `Hello from FlighHub 2 ${new Date().toISOString()}`,
    })
  );

  logger.info(response);
}

Send notification

async function sendNotification(): Promise<void> {
  const response = await axios.post(process.env.API_URL, notification);
  logger.info(response.data);
}

notification is just a JSON file like this:

notification.json

{
  "notify_type": "way_line_file_upload_complete",
  "org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "org_name": "My Organization",
  "prj_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "prj_name": "My Project",
  "sn": "XXXXXXXXXXXXXX",
  "task_info": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_type": "way_line",
    "tags": []
  },
  "files": [
    {
      "id": 123456,
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "file_type": 10,
      "sub_file_type": 0,
      "name": "fh2",
      "key": "fh2.txt"
    }
  ],
  "folder_info": {
    "expected_file_count": 1,
    "uploaded_file_count": 1,
    "folder_id": 123456
  }
}

Environment variables

Our .env file (with environment variables) will have a structure very similar to the FlightHub Sync configuration. We can take values from the AWS CDK/CloudFormation outputs after we deployment our solution using cdk deploy.

.env

AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
REGION=eu-west-1
BUCKET=flighthub2-xxxxxxxxxxxx
ARN=arn:aws:iam::xxxxxxxxxxxx:role/flighthub2
ROLE_SESSION_NAME=flighthub2
PROVIDER=aws
API_URL=https://xxxxxxxxxx.execute-api.eu-west-1.amazonaws.com/prod/dji/flighthub2/notify

Conclusion

Although FlightHub Sync is still in beta, it has some bugs and I definitely have a wishlist of improvements (I sent feedback to the DJI) - it works and opens a lot of new possibilities for a custom drone related workflows.

Modernizing Express, Heroku tech stack with NestJS and AWS - PoC

Jacek Kościesza — Fri, 31 Mar 2023 08:56:02 +0000

TL;DR

We will create a working PoC which proves that migration from Express based app hosted in Heroku to NestJS app hosted in AWS with serverless architecture based on API Gateway, Fargate and Aurora is not so complicated. We will also use the IaC approach based on AWS CDK.

MVP Solution

When I joined moojo as a Head of Engineering September 2022 - beta tests phase was almost done and we were preparing for the official launch of our MVP (Minimum Viable Product) with invoicing and instant payment features.

Backend was a monolithic, Node.js app using Express framework and Postgress database, both hosted on Heroku. Solution was using a functional programming approach, TypeScript and modern, next-generation ORM (Object Relational Mapper) like Prisma, which provided us with type-safety and automated migration.

It was simple approach following KISS (Keep It Simple Stupid) design principle, which was perfect at the time for the MVP solution. This was also a conscious decision the interim tech lead, who started the project and wanted to create unopinioned solution and leave bigger decisions for the successor.

Challenges

This setup was quite good, but when the application started to grow - we noticed a few challenges.

Framework

It was hard to manage dependencies without modern design patterns known as Dependency Injection, OpenAPI/Swagger documentation was often out of sync with actual implementation, freedom of doing things in unopinionated framework was not optimal for less experienced team members (they needed some guidance and documentation).

We could of course improve existing solution, but on the other hand - there are already frameworks, which provide those things out-of-the-box, so it would be like reinventing the wheel. NestJS seemed like a perfect fit for us, question was - how hard will it be to migrate.

Cloud

Heroku's advantage is that it's super easy to setup and deploy your app. A few clicks in the Heroku Dashboard is enough to setup a compute or data store. Some disadvantage is lack of flexibility - it's always about trade-offs. Heroku is built on top of AWS, but it doesn't give you access to the full richness of 200+ AWS services. Configuration is sometimes limited e.g. Bucketeer Heroku add-on vs S3 (Simple Storage Service).

We potentially needed something more advanced (in the long term). AWS (Amazon Web Services), which I used in other projects seemed like a natural migration step.

PoC (Proof of Concept)

As every startup - we are busy with delivering new features e.g. Insurance for IT freelancers, so rewriting everything was not an option. I decided to create PoC (Proof of Concept) to check what is possible and answer some questions:

Is it possible to implement new features using NestJS, but leave already implemented features in Express unchanged in our monolith (but rewrite them one-by-one using The Boy Scout Rule when we have time)?
Is it easy to Dockerize our app, take advantage of modern approach such as serverless, IaC (Infrastructure as Code) in AWS?

NestJS

Hello World!

I started with creating a new Nest project, by following First steps in NestJS Documentation.

npm i -g @nestjs/cli
nest new moojo

This created the working "Hello World!" NestJS app:

Source code: NestJS new project | GitHub

Express app in NestJS

Next thing I wanted to verify is using the existing Express app in NestJS. I found a solution in the Stack Overflow question - Adding NestJS as express module results in Nest being restarted.

All you have to do is to modify bootstrap function in main.ts and use ExpressAdapter:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const adapter = new ExpressAdapter(expressApp);
  const app = await NestFactory.create(AppModule, adapter);

  await app.listen(3000);
}

At this point I had two working endpoints, one for NestJS and one from Express:

Source code: Express app in NestJS | GitHub

Prisma

I wanted to create some more realistic example for the migration to AWS, so I decided to add a Postgres database and Prisma (ORM we already use at moojo).

There is a great example for that (with users and blog posts) in NestJS documentation - Prisma | NestJS, so just follow the recipe.

The only thing missing in the recipe steps was updating app.module.ts with a newly created services

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { PostService } from './post.service';
import { PrismaService } from './prisma.service';
import { UserService } from './user.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
  providers: [AppService, UserService, PostService, PrismaService],
})
export class AppModule {}

Source code: Prisma recipe | GitHub

OpenAPI (Swagger)

In order to easily test this solution I decided to setup OpenAPI/Swagger documentation.

Everything you need to know is again in NestJS documentation - OpenAPI (Swagger) | NestJS, so you can take a look.

You just have to initialize Swagger using SwaggerModule in main.ts and add use @ApiProperty decorators in a few places.

At this point OpenAPI / Swagger UI was working

and I was able to create user, post and publish it

Source code: OpenAPI/Swagger | GitHub

AWS

Architecture

It would be great to start migration to AWS without bigger refactoring of our code. Later we can gravitate to more cloud-native solution, but lift-and-shift is a great first step.

I really like the serverless-first approach and used it a lot in my previous projects. With lift-and-shift approach - possibilities are limited, but we still can leverage benefits of serverless computing such as no servers to manage, automatic scaling, built-in high availability or pay-for-use billing which can be especially beneficial for staging and developer environments.

All of this can be achieved with the following high level architecture with API Gateway, Fargate and Aurora Serverless.

In order to integrate API Gateway with Fargate in a secure and reliable way - we also need ALB (Application Load Balancer) and VPC Link.

Fargate and Aurora will run within a private subnet... actually two private subnets in two different Availability Zones to achieve high availability.

To enable Fragate tasks to download Docker image from ECR (Elastic Container Registry), we will have to deploy two NAT Gatways in a public subnets.

Security groups can be used to control the traffic that is allowed between all resources.

You can find out more about this architecture on AWS blog e.g. Access Private applications on AWS Fargate using Amazon API Gateway PrivateLink

Infrastructure as Code

There are many benefits of IaC (Infrastructure as Code), including speed of provisioning new environments, lower risk of human errors, improved consistency or a way to version your infrastructure.

There are also many great solutions which can help with that - Terraform, Pulumi, CloudFormation, AWS CDK (Cloud Development Kit) - just to name a few. For me - using the same programming language e.g. TypeScript for all aspects of the technology stack is a powerful concept. I also like to use native technologies in the given environment and I already have experience with AWS CDK, so I decided to go with it.

AWS CDK app

Before we create a new AWS CDK app, we need to install and setup a few things. There is a good tutorial Getting started with the AWS CDK in the official AWS CDK v2 Developer Guide.

When all prerequisites done and AWS CDK installed

npm install -g aws-cdk

we can finally create our First AWS CDK app in moojo folder, which we rename later to cloud.

cdk init app --language typescript

Source code: AWS CDK app | GitHub

VPC (Virtual Private Cloud)

Let's start building our infrastructure with VPC (Virtual Private Cloud) with private and public subnet configurations, Availability Zones and NAT Gateways.

vpc.cdk.ts

import { Construct } from "constructs";
import * as ec2 from "aws-cdk-lib/aws-ec2";

export class VpcCdkConstruct extends Construct {
  public readonly vpc: ec2.Vpc;

  constructor(scope: Construct, id: string) {
    super(scope, id);

    this.vpc = new ec2.Vpc(this, "moojo-vpc", {
      vpcName: "moojo-vpc",
      cidr: "10.0.0.0/16",
      maxAzs: 2,
      natGateways: 2,
      natGatewayProvider: ec2.NatProvider.gateway(),
      subnetConfiguration: [
        {
          name: "moojo-public-subnet",
          subnetType: ec2.SubnetType.PUBLIC,
          cidrMask: 24,
        },
        {
          name: "moojo-private-subnet",
          subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS,
          cidrMask: 24,
        },
      ],
    });
  }
}

moojo-stack.ts

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { VpcCdkConstruct } from "./vpc.cdk";

export class MoojoStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    cdk.Tags.of(this).add("app", "Moojo");

    const vpc = new VpcCdkConstruct(this, "vpc").vpc;
  }
}

After those changes we can deploy our app

cdk deploy

and watch our stack being created in CloudFormation

You can also verify if VPC was created in a VPC dashboard

Source code: VPC | GitHub

RDS (Relational Database Service)

Let's create Aurora Serverless (part of RDS) next. We will create a Serverless Cluster with Aurora PostgreSQL engine in our VPC. We will setup things like removal policy to destroy to easily cleanup after we are done with PoC, scaling configuration to some bare minimum to save some costs. We also need to enable the Data API to be able to use Query Editor in AWS Console.

As you can see - some of the configuration makes sense only for PoC and it's not production ready. Point of PoC is to check and verify possible solutions, answer some questions NOT become production ready solution.

rds.cdk.ts

import { Construct } from "constructs";
import * as cdk from "aws-cdk-lib";
import * as ec2 from "aws-cdk-lib/aws-ec2";
import * as rds from "aws-cdk-lib/aws-rds";

interface RdsProps {
  vpc: ec2.Vpc;
}

export class RdsCdkConstruct extends Construct {
  public readonly cluster: rds.ServerlessCluster;

  constructor(scope: Construct, id: string, { vpc }: RdsProps) {
    super(scope, id);

    const securityGroup = new ec2.SecurityGroup(this, "moojo-rds-sg", {
      vpc,
      securityGroupName: "moojo-rds-sg",
      description: "Security group for Moojo RDS (Amazon Relational Databases)",
    });

    this.cluster = new rds.ServerlessCluster(this, "moojo-dbcluster", {
      clusterIdentifier: "moojo-dbcluster",
      defaultDatabaseName: "moojo",
      engine: rds.DatabaseClusterEngine.AURORA_POSTGRESQL,
      parameterGroup: new rds.ParameterGroup(this, "ParameterGroup", {
        engine: rds.DatabaseClusterEngine.auroraPostgres({
          version: rds.AuroraPostgresEngineVersion.VER_10_21, // TODO: adjust supported version
        }),
      }),
      enableDataApi: true, // TODO: needed for Query Editor (AWS console)
      removalPolicy: cdk.RemovalPolicy.DESTROY, // TODO: only for PoC
      vpc,
      scaling: {
        // TODO: adjust it
        autoPause: cdk.Duration.hours(1),
        minCapacity: rds.AuroraCapacityUnit.ACU_2,
        maxCapacity: rds.AuroraCapacityUnit.ACU_2,
      },
      securityGroups: [securityGroup],
    });
  }
}

moojo-stack.ts

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { RdsCdkConstruct } from "./rds.cdk";
import { VpcCdkConstruct } from "./vpc.cdk";

export class MoojoStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    cdk.Tags.of(this).add("app", "Moojo");

    const vpc = new VpcCdkConstruct(this, "vpc").vpc;
    const rds = new RdsCdkConstruct(this, "rds", { vpc });
  }
}

After deploying our stack again, we can check if our database works. Let's go to Query Editor and connect to our database

You copy Secrets manger ARN in Secrets Manager

When connected - we can copy SQL from the migration.sql file generated by Prisma

and execute it to create our tables.

Source code: RDS | GitHub

ELB (Elastic Load Balancer)

As a next step - let's create ALB (Application Load Balancer) with a target group, listener and security group.

elb.cdk.ts

import { Construct } from "constructs";
import * as ec2 from "aws-cdk-lib/aws-ec2";
import * as elbv2 from "aws-cdk-lib/aws-elasticloadbalancingv2";

interface ElbProps {
  vpc: ec2.Vpc;
}

export class ElbCdkConstruct extends Construct {
  public readonly alb: elbv2.ApplicationLoadBalancer;
  public readonly listener: elbv2.ApplicationListener;
  public readonly securityGroup: ec2.SecurityGroup;
  public readonly targetGroup: elbv2.ApplicationTargetGroup;

  constructor(scope: Construct, id: string, { vpc }: ElbProps) {
    super(scope, id);

    this.securityGroup = new ec2.SecurityGroup(this, "moojo-elb-sg", {
      vpc,
      securityGroupName: "moojo-elb-sg",
      description: "Security group for Moojo ELB (Elastic Load Balancer)",
    });

    this.securityGroup.addIngressRule(
      ec2.Peer.anyIpv4(), // TODO: restrict?
      ec2.Port.tcp(80),
      "Allow from anyone on port 80"
    );

    this.alb = new elbv2.ApplicationLoadBalancer(this, "moojo-alb", {
      loadBalancerName: "moojo-alb",
      vpc,
      securityGroup: this.securityGroup,
      deletionProtection: false,
    });

    this.targetGroup = new elbv2.ApplicationTargetGroup(this, "moojo-alb-tg", {
      vpc,
      targetType: elbv2.TargetType.IP,
      protocol: elbv2.ApplicationProtocol.HTTP,
      port: 80,
      targetGroupName: "moojo-alb-tg",
    });

    this.listener = new elbv2.ApplicationListener(this, "moojo-alb-listener", {
      loadBalancer: this.alb,
      port: 80,
      protocol: elbv2.ApplicationProtocol.HTTP,
      defaultAction: elbv2.ListenerAction.forward([this.targetGroup]),
    });
  }
}

moojo-stack.ts

import { RdsCdkConstruct } from "./rds.cdk";
import { VpcCdkConstruct } from "./vpc.cdk";
import { ElbCdkConstruct } from "./elb.cdk";

export class MoojoStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    cdk.Tags.of(this).add("app", "Moojo");

    const vpc = new VpcCdkConstruct(this, "vpc").vpc;
    const rds = new RdsCdkConstruct(this, "rds", { vpc });
    const elb = new ElbCdkConstruct(this, "elb", { vpc });
  }
}

Source code: ELB | GitHub

API Gateway

Let's create API Gateway (v2) with HTTP API and integrate it with our ALB (Application Load Balancer) using VPC Link.

gw.cdk.ts

import { Construct } from "constructs";
import * as apigwv2 from "@aws-cdk/aws-apigatewayv2-alpha";
import * as ec2 from "aws-cdk-lib/aws-ec2";
import * as integrations from "@aws-cdk/aws-apigatewayv2-integrations-alpha";

import { ElbCdkConstruct } from "./elb.cdk";

interface ApiGatewayProps {
  vpc: ec2.Vpc;
  elb: ElbCdkConstruct;
}

export class ApiGatewayCdkConstruct extends Construct {
  constructor(scope: Construct, id: string, { vpc, elb }: ApiGatewayProps) {
    super(scope, id);

    const httpApi = new apigwv2.HttpApi(this, "moojo-http-api", {
      apiName: "moojo-http-api",
    });

    const vpcLink = new apigwv2.VpcLink(this, "moojo-vpc-link", {
      vpc,
      vpcLinkName: "moojo-vpc-link",
    });

    const integration = new integrations.HttpAlbIntegration(
      "moojo-http-alb-integration",
      elb.listener,
      {
        method: apigwv2.HttpMethod.ANY, // TODO: restrict?
        vpcLink,
      }
    );

    const route = new apigwv2.HttpRoute(this, "moojo-http-route", {
      httpApi,
      routeKey: apigwv2.HttpRouteKey.with("/{proxy+}", apigwv2.HttpMethod.ANY), // TODO: restrict?
      integration,
    });
  }
}

moojo-stack.ts

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";

import { ApiGatewayCdkConstruct } from "./gw.cdk";
import { ElbCdkConstruct } from "./elb.cdk";
import { RdsCdkConstruct } from "./rds.cdk";
import { VpcCdkConstruct } from "./vpc.cdk";
import { ElbCdkConstruct } from "./elb.cdk";

export class MoojoStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    cdk.Tags.of(this).add("app", "Moojo");

    const vpc = new VpcCdkConstruct(this, "vpc").vpc;
    const rds = new RdsCdkConstruct(this, "rds", { vpc });
    const elb = new ElbCdkConstruct(this, "elb", { vpc });
    const gw = new ApiGatewayCdkConstruct(this, "gw", { vpc, elb });
  }
}

Source code: GW | GitHub

ECS (Elastic Container Service)

It's time for the last part - the heart of our backend. We will create ECS (Elastic Container Service) Cluster, Fargate task definition and service. I will show you how I Dockerized our app and pushed the docker image to ECR (Elastic Container Registry).

Dockerization is super simple. All you have to do is to grab Dockerfile from Tom Ray's article How to write a NestJS Dockerfile optimized for production and save it in our NestJS moojo folder.

Image will be created and pushed to ECR with this simple code

const image = new DockerImageAsset(this, "moojo-ecr-image", {
  directory: path.join(__dirname, "../../", "moojo"),
  platform: Platform.LINUX_AMD64,
});

Keep in mind that this ECR configuration is for PoC only, it has to be adjusted for the production workload. There is also a security issue - I get the database URL and pass it as an environment variable in an unsafe way (this will have to be fixed in a production ready solution, but it's good enough for the PoC).

ecs.cdk.ts

import { Construct } from "constructs";
import { DockerImageAsset, Platform } from "aws-cdk-lib/aws-ecr-assets";
import * as cdk from "aws-cdk-lib";
import * as ec2 from "aws-cdk-lib/aws-ec2";
import * as ecs from "aws-cdk-lib/aws-ecs";
import * as elbv2 from "aws-cdk-lib/aws-elasticloadbalancingv2";
import * as sm from "aws-cdk-lib/aws-secretsmanager";
import * as path from "path";

import { ElbCdkConstruct } from "./elb.cdk";
import { RdsCdkConstruct } from "./rds.cdk";

interface EcsProps {
  vpc: ec2.Vpc;
  elb: ElbCdkConstruct;
  rds: RdsCdkConstruct;
}

export class EcsCdkConstruct extends Construct {
  constructor(scope: Construct, id: string, { vpc, elb, rds }: EcsProps) {
    super(scope, id);

    const cluster = new ecs.Cluster(this, "moojo-ecs-cluster", {
      clusterName: "moojo-ecs-cluster",
      vpc,
    });

    const securityGroup = new ec2.SecurityGroup(this, "moojo-ecs-sg", {
      vpc,
      securityGroupName: "moojo-ecs-sg",
      description: "Security group for Moojo ECS (Elastic Container Service)",
    });

    const taskDefinition = new ecs.FargateTaskDefinition(
      this,
      "moojo-ecs-task-definition",
      {
        // TODO: adjust it
        memoryLimitMiB: 1024,
        cpu: 512,
      }
    );

    const image = new DockerImageAsset(this, "moojo-ecr-image", {
      directory: path.join(__dirname, "../../", "moojo"),
      platform: Platform.LINUX_AMD64,
    });

    const logging = new ecs.AwsLogDriver({
      streamPrefix: "moojo",
    });

    taskDefinition.addContainer("moojo-ecs-container", {
      containerName: "moojo-ecs-container",
      logging,
      image: ecs.ContainerImage.fromDockerImageAsset(image),
      portMappings: [
        {
          containerPort: 3000,
          protocol: ecs.Protocol.TCP,
        },
      ],
      environment: {
        NODE_ENV: "production",
        DATABASE_URL: this.getDatabaseUrlUnsafe(rds.cluster.secret!), // TODO: do it in a secure way
      },
    });

    const service = new ecs.FargateService(this, `${id}`, {
      serviceName: "moojo-ecs-service",
      taskDefinition,
      securityGroups: [securityGroup],
      cluster,
      // TODO: adjust it
      desiredCount: 1,
      enableExecuteCommand: true,
      maxHealthyPercent: 200,
      minHealthyPercent: 100,
    });

    // TODO: adjust it
    const scaling = service.autoScaleTaskCount({
      minCapacity: 1,
      maxCapacity: 2,
    });

    // TODO: adjust it
    scaling.scaleOnCpuUtilization(`${id}-cpuscaling`, {
      targetUtilizationPercent: 85,
      scaleInCooldown: cdk.Duration.seconds(120),
      scaleOutCooldown: cdk.Duration.seconds(30),
    });

    rds.cluster.connections.allowDefaultPortFrom(
      service,
      "Fargate access to Aurora"
    );

    service.connections.allowFrom(
      elb.alb,
      ec2.Port.tcp(80),
      "Allow traffic from ELB"
    );

    elb.listener.addTargets("moojo-ecs-targets", {
      protocol: elbv2.ApplicationProtocol.HTTP,
      targets: [service],
      healthCheck: {
        // TODO: adjust it
        healthyHttpCodes: "200",
        healthyThresholdCount: 3,
        interval: cdk.Duration.seconds(30),
      },
    });
  }

  // TODO: do it in a secure way!!!
  private getDatabaseUrlUnsafe(secret: sm.ISecret): string {
    const host = secret.secretValueFromJson("host").unsafeUnwrap();
    const port = secret.secretValueFromJson("port").unsafeUnwrap();
    const username = secret.secretValueFromJson("username").unsafeUnwrap();
    const password = secret.secretValueFromJson("password").unsafeUnwrap();
    const database = secret.secretValueFromJson("dbname").unsafeUnwrap();

    return `postgresql://${username}:${password}@${host}:${port}/${database}`;
  }
}

moojo-stack.ts

import { Construct } from "constructs";

import { ApiGatewayCdkConstruct } from "./gw.cdk";
import { EcsCdkConstruct } from "./ecs.cdk";
import { ElbCdkConstruct } from "./elb.cdk";
import { RdsCdkConstruct } from "./rds.cdk";
import { VpcCdkConstruct } from "./vpc.cdk";
export class MoojoStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    cdk.Tags.of(this).add("app", "Moojo");

    const vpc = new VpcCdkConstruct(this, "vpc").vpc;
    const rds = new RdsCdkConstruct(this, "rds", { vpc });
    const elb = new ElbCdkConstruct(this, "elb", { vpc });
    const gw = new ApiGatewayCdkConstruct(this, "gw", { vpc, elb });
    const ecs = new EcsCdkConstruct(this, "ecs", { vpc, elb, rds });
  }
}

When deployed - you can grab API Gateway URL from the AWS Console

and give it a try using Swagger UI.

As you can see everything worked like in our local environment.

Source code: ECS | GitHub

Build YouTube Clone with AWS - FakeTube #0

Jacek Kościesza — Fri, 31 Mar 2023 08:54:13 +0000

I'm a builder. For over a year I've been building a project which is a YouTube clone called FakeTube.

Fig. 1. FakeTube - Responsive / Adaptive Web Design

I spent a lot of time researching and applying the best practices in software engineering, starting from DDD (Domain Driven Design) analysis, clear requirements (including UX/UI design and Gherkin style acceptance criteria).

On the frontend side - RWD/AWS (Responsive/Adaptive Web Design), building a components library with atomic design or effective state management.

DevOps aspects like advanced CI/CD pipelines (including all sorts of automated tests) and IaC (Infrastructure as Code).

Finally cloud-native, event-driven and microservices approach with some advanced serverless architecture on AWS, which look like this:

Fig. 2. Architecture Overview - over 30 different AWS service used

There are over 30 different AWS services used. I will go into details - what are those services and how they are interconnected, so stay tuned for that, but first let me show you how the app looks and what features I've implemented.

Demo

FakeTube is a web application which has a lot of features from the main YouTube app, as well as from the YouTube Studio.

Responsive / Adaptive Web Design

It's fully Responsive and Adaptive Web Design, which means that it renders well on many devices. Some components are different on mobile and desktop resolutions. You can see that the main menu is changing from a bottom navigation bar on mobile, through a mini drawer on tablet, to a fully opened drawer on desktop.

Fig. 3. Mobile - bottom navigation bar

Fig. 4. Tablet - mini drawer

Fig. 5. Desktop - fully opened drawer

Appearance and language

There is quite an extensive Settings / Account menu, where we can adjust different things. This includes appearance, where we can switch between light and dark themes. Internationalization (i18n) and localization are another important aspect. At the moment you can switch between English and Polish languages, but it's easy to add more, including right-to-left ones. Here you can see the home page with a dark theme in and a Polish language selected.

Fig. 6. Dark theme and Polish language

Watch page

Watch page is probably the most important place, where as a viewer you can actually watch the video or engage, connect with the creator. A lot of features like video player, metadata (with title, channel or owner info and description), watch next sections (with related, recommended videos) or comments are already implemented. I'm actively working on some other features like subscriptions, like/dislike or save (to playlist).

Fig. 7. Watch page - player, metadata, comments and related videos

Accounts

Many features on YouTube (and FakeTube) such as adding comments or uploading videos are available only for signed in users. That's why I need to implement account creation, sign up or forgot password features early on.

Fig. 8. Sign in - identifier

Fig. 9. Sign in - password

Fig. 10. Create account

Studio

Upload video

One of the coolest features I implemented is that you can actually upload your videos. It's part of the FakeTube Studio and a lot is going on under the hood. Video file is uploaded to the object store. This triggers an event which kicks off the video transcoding process, which converts original video into suitable Video On Demand formats and sizes and generates thumbnails. Our web application is notified in real-time about video upload and processing progress.

You can add video metadata like title, description and category. It will be automatically saved as a draft, but you can set visibility to private, unlisted or just publish. It will be immediately visible in the Content section of the Studio and available to watch on FakeTube.

Fig. 11. Studio - dashboard

Fig. 12. Upload videos - select files

Fig. 13. Upload videos - details

Fig. 14. Upload videos - visibility

Fig. 15. Studio - content

Fig. 16. Watch - uploaded and published video

As you can see I put a lot of effort into this project. I've learned a lot and that's why I decided to share this knowledge, but also discuss some potential improvements with you. We will build together what you see here and even go beyond. There are many more features to build and ideas to verify. This tutorial will have many episodes and seasons. Let's take this journey together.

Why, How, What

I bet that many of you know "Simon Sinek" and his great book "Start with Why". I broke the rules and started with “What” we are going to build. Let me fix it now. I will explain:

Why YouTube?
Why AWS?
How we will use AWS to build such a complex application

Learning

There is no end to education. It is not that you read a book, pass an examination, and finish with education. The whole of life, from the moment you are born to the moment you die, is a process of learning.
~Jiddu Krishnamurti

This quote couldn't be more true in the field of software engineering. What is the best way of learning? Theory is a foundation, but real understanding and experience comes for practice. So how can you learn “by doing” effectively?

We can start with “Hello World!” example, but that is good for like 5 minutes. There are tutorials and this is really a good way of getting hands-on experience with a given technology, but you have to be careful. Don't believe that you will learn AWS (end to end) in 3 hours or even over the weekend. Finally we can build another TODO app.

All those ways are useful, but there is a problem…

It's like with this anecdote “How to draw a horse” (in 5 simple steps). Just draw 2 circles (or actually ellipses), draw a few lines as legs, face, hair...

Fig. 17. How to draw a horse - steps 1-4 of 5

...and the last step - add a few small details. “Taaaaaa-daaaaaa” here it is, beautiful horse:

Fig. 18. How to draw a horse - steps 1-4 of 5

And then you are starting to think how the heck should I go from step 4) to 5)? This reminds me of the difference between simple tutorials and real life commercial projects like Twitter, Reddit - you name it.

Depending on which stage of the project we get to - we will have different challenges. In the early stages of the project you can choose technology, design architecture, but probably it's not the right time to build multi-site disaster recovery. On the other hand, in mature projects things like analytics, A/B split testing will be important, but some decisions are already made and you don't have much influence on them. It would be great to go through all those stages, but only few of us have that opportunity.

Fig. 19. Skeleton vs Prototype vs MVP vs MMP vs MLP/MDP

So, what can you do - create this opportunity yourself. With your own long-term project you can do whatever you want. Go through all those stages, experiment, make mistakes, change your mind, learn a lot along the way.

YouTube

The subject of the project must be thought through very carefully. Why do I think that building a YouTube (clone) is a good idea? I can see three main reasons for this:

Business domain

First thing is the business domain. The application is well known to everyone and it's pretty simple to understand, at least on the high-level, how the YouTube ecosystem works. Here's quick summary form a book “The YouTube Formula” by Derral Eves:

...creators make videos and upload them to YouTube. Brands pay YouTube to run advertising alongside uploaded content, either before or during a video. When a channel meets the ad sharing program requirements, it gets a cut of the money from the ads running on their content.

We want to focus on software engineering, not on creating new innovative business, so this is perfect - we have a ready plan for what we will build.

Backlog

Second (related) thing is that we have almost a ready backlog of things to implement. Of course we have to discover some not obvious features, make some DDD (Domain Driven Design) analysis, maybe an EventStorming session, but we don't have to do it from scratch. We have an existing app, so we can check how it works. There is an official “How YouTube works” website, there are books, videos about the topic. We also have ready UX/UI design, what's more - it's based on Material Design, so we can use one of the existing component libraries and focus on composing more complicated UI elements and layouts.

Challenges

Last thing is challenges. This model of how YouTube works is simple, but it results in many complicated challenges to overcome.

YouTube wants users to spend time in the app and watch as many interesting videos for them as possible, because it means more ads, therefore profits. This means that the recommendation system becomes a crucial part of the solution. We can start to implement something simple e.g. based on tags and then improve it using graph databases or Machine Learning models.

All sorts of analytics also become super important. It's not only about analytics for creators inside YouTube Studio. All those events like impressions, clicks, watchtime, likes/dislikes, survey responses, comments are also signals for the recommendation system.

Statistics related to YouTube are astonishing. They have more than 2.6 billion users and there is 500 hours of content uploaded to YouTube every minute. As Marques Brownlee put it “...if there's a problem that's so small it only affects 0.1% of people on YouTube, that problem now affects 2.6 million people.”

As Eric Schmidt said “Every problem they have is a problem at scale”. We can also think from the engineering perspective how we can design our solution to be so scalable.

There are many more things under the hood, things which we don't see in the UX/UI, but are key aspects of the YouTube ecosystem.

AWS

Choosing a cloud provider for your project is not a trivial task. You can take dozens of factors into account. I wanted to focus on major players on the market, because I wanted mature, well tested solutions with large communities. The three biggest players on the market are:

AWS (Amazon Web Services) with over 30% of the market share
Microsoft Azure with over 20%
GCP (Google Cloud Platform) with around 10%

Google Cloud Platform seems like a reasonable choice for FakeTube - YouTube is part of Google, so it probably works on GCP, right? It's not so simple. In 2021 Thomas Kurian, CEO of GCP announced that Google will migrate part of YouTube's infrastructure to Google Cloud. Turns out that YouTube is/was hosted on internal infrastructure separate from GCP. So unfortunately that's not as simple as “let's use the same services which real YouTube is using”.

After doing some research, I found that AWS and Azure offerings seem more complete and mature. This conclusion can also be made when you look at “Gartner® Magic Quadrant™ for Cloud Infrastructure and Platform Services”.

Fig. 20. Gartner - Magic Quadrant for Cloud Infrastructure and Platform Services 2022

So AWS or Azure? Frankly speaking I think that both of them would work well, but a few things convinced me to AWS.

I really like the serverless-first approach. It seems that AWS has the most mature and complete offering of serverless services. There are serverless services in all categories - compute, data store, application integration and even analytics. AFAIK AWS is still the only cloud provider which offers serverless GraphQL service (called AppSync).

Infrastructure as Code was another good practice I wanted to use. AWS has a great, native solution for that called AWS CDK (Cloud Development Kit), where you can use programming languages you know to define cloud infrastructure.

Great offer of more than 15 purpose-built databases, which allows me to use polyglot persistence was also a plus.

This project is a VOD (Video on Demand) solution, so super important for me was the offering of media services called AWS Elemental (Azure also has similar services).

LEGO

Fig. 21. LEGO - Star Wars Millennium Falcon - Assembled

This is the LEGO Star Wars Millennium Falcon, a mega big set, which has over 75 000 pieces and when assembled it's 84 cm long and 60 cm wide.

Fig. 22. LEGO - Star Wars Millennium Falcon - Pieces

Such a big number of elements is overwhelming. Fortunately, there are always instructions included with LEGO sets, which guides you step-by-step how to create another increment. You find a few pieces, connect them together and put them in the right place. Imagine how hard it would be to assemble this set without an instruction.

What does this have to do with AWS and building software? AWS services are similar to LEGO bricks, you need to find the right ones, connect them together and put them in the right place in the architecture to build an app. There are also similar problems - the number of services is overwhelming - there are more than 200 of them.

Fig. 23. 200+ AWS services

Now imagine that you have to build an app in AWS without an instruction. Luckily I have one, so let's see which services we can use and how to compose them to deliver FakeTube features.

Fig. 24. AWS instruction

Hosting

Fig. 25. Hosting

This project is a web application, so we have to host it somewhere. Service which is perfect for this is Amplify. Under the hood there are a lot of other services which you can use directly if you need more control, but Amplify simplifies this a lot. Those services include Route 53 which is DNS (Domain Name System) in the cloud, you can for example register and configure your own domain. Certificate Manager can be used to manage SSL/TLS certificates to enable HTTPS communication. CloudFront is a CDN (Content Delivery Network) which allows you to deliver app assets, images, and videos faster. S3 (Simple Storage Service) is an object store where we upload and keep all those assets. There is also Lambda@Edge, which is FaaS (Function as a Service) on the CDN level (it's part of CloudFront). It allows you for example to use SSR (Server Side Rendering) with a framework like Next.js.

Homepage

Fig. 26. Homepage

The YouTube homepage is mainly a list of recommended videos. In a simplest solution, without personalized recommendations, we will need some kind of API and database where we will keep a list of videos. There are at least two ways of doing it.

We can go with a more traditional approach with a RESTful API and relational database. API Gateway will be perfect to build this kind of API. When it comes to databases, there are a number of different services in RDS (Relational Database Service). I would recommend a serverless version of Aurora with a Postgres compatible engine. We will also need to run some code, so Lambda will be a good fit.

Second approach, which is the modern one, would be to use GraphQL and noSQL database. For the API we can use AppSync, which is a kind of GraphQL gateway, which has direct integration with many other AWS services, including DynamoDB, which is a key-value database. This means that we don't need additional code which runs on Lambda, but in practice it's sometimes simpler to use one, instead of doing complicated things in VTL (Velocity Template Language) templates.

We will keep static assets in S3 (Simple Storage Service) and deliver them using CloudFront.

Authentication

Fig. 27. Authentication

You have to be signed in user to use some of the YouTube features. Examples would be adding a comment or uploading a video. Cognito can help us with that. It's an identity and access management service which we can use to authenticate users and create accounts. Integration is very simple with Amplify library, it's only one function call to sign in a user. SES (Simple Email Service) allows us to send confirmation emails. We can keep templates of those emails in S3 (Simple Storage Service) and use Lambda function to prepare content of this email based on the template and needed data.

Upload

Fig. 28. Upload

The real fun starts when we upload videos. In a simplest version we can upload a file to S3 (Simple Storage Service). This will trigger Lambda function, which will run a job in Elemental MediaConvert to transcode original video into suitable VOD (Video On Demand) formats and sizes and generate thumbnails. Those assets are uploaded back to S3 and we use CloudFront to efficiently deliver them. We can track progress of the transcoding process using CloudWatch and even send notifications using SNS (Simple Notification Service) and Lambda.

In practice this workflow can be even more complicated and enhanced.

Fig. 29. Upload - enhanced

In Fig. 29 we can see Glacier which can be used to archive original video files in a cost-effective way. Step Functions will provide a state machine, which will orchestrate the whole workflow in a reliable way, for example by providing retries if needed. We also have an Elemental MediaPackage, which will prepare video content for a broad range of connected devices.
There are even more Elemental services such as MedaTaylor which can insert personalized ads to video, which is essential in the YouTube ecosystem.

Recommendations

Fig. 30. Recommendations

Another key feature is “Watch next” and its video recommendations. We will need an API for that for example GraphQL based solution in AppSync. We will keep a list of videos in DynamoDB, but we need a way to deliver related and personalized video recommendations. One option is to use a graph database called Neptune and Gremlin query language. A Simple use case would be like this: I like video “A” and “B”, other user likes video “B”, so let's recommend video “A” for him, maybe he will enjoy it as I did. It's pretty simple to write queries like that using graph databases. Another possibility is to use Personalize, ML (Machine Learning) based service created exactly for this purpose - personalized recommendations. It's used by Amazon.com, so you can imagine how powerful it is.

Search

Fig. 31. Search

Search is an important feature of many apps. YouTube is no different. As previously we keep a list of videos in DynamoDB, but for search there are better, specialized solutions such as Elaticsearch. In AWS there is OpenSearch which is derived from Elasticsearch and even more powerful. This is an example of polyglot persistence, where we use multiple data storage services in a single solution, depending on the use case. This is also an example of CQRS (Command Query Responsibility Segregation) - we use different technologies for commands (e.g. create, update, delete video) and queries (e.g. search). Interesting problem is how can we synchronize data between DynamoDB and OpenSearch, how can we create materialized views in OpenSearch. Luckily DynamoDB supports streams, which are a time-ordered sequence of modifications, which we can process using Lambda and modify the OpenSearch index appropriately.

Comments

Fig. 32. Comments

Comments are not very complicated in their basic form. As always we need an API for example using GraphQL based AppSync. We can keep comments in DynamoDB, but we will need two indexes for sorting comments by date (“Newest first” option) or by relevance (“Top comments” option). Comments can give us useful analytical data and become a signal for recommendations. Number of comments for the given video is important, but we can also check sentiment (negative or positive comment). For that purpose we can use Comprehend, which is an NLP (Natural-Language Processing) service.

Analytics

Fig. 33. Analytics

Analytics is important not only for creators in Studio, but to make the whole YouTube ecosystem work efficiently. There are a few options here. We can use Kinesis Data Firehose directly and store all the events from the web app directly in S3 (Simple Storage Service). S3 will be used as a Data Lake in this scenario. We can also send events directly to Pinpoint, which is an engagement and communication service. In that use case it's also possible to upload this stream of events from Pinpoint to S3 using Kinesis Data Firehose. Next we can query S3 using SQL thanks to Athena and visualize interesting things in QuickSight, which is a BI (Business Intelligence) tool.

Payments

Fig. 34. Payments

Renting or buying a movie is a less known feature in YouTube. Implementing this feature can be however a great opportunity to practice integration with some 3rd party services e.g. payment processing service like Stripe. In addition to the standard service we already used, we can use SQS (Simple Queue Service) to provide better scalability and decoupling. Very useful can be EventBridge, which is a kind of event bus, which can be used for internal communication between microservices, as well as for external integrations. Things like API keys can be stored in Secrets Manager in a secure way.

Just a start

As you can see possibilities are almost endless and this is just the tip of the iceberg. We didn't discuss security topics like WAF (Web Application Firewall) or Shield service, which can protect us from DDoS (Distributed Denial of Service) attacks. We can try different Disaster Recovery solutions including the most advanced Multi-Site Active/Active option. There are more advanced, scalable services related to analytics like Redshift which is a Data Warehouse solution. We can experiment with different versions of UX/UI and features with A/B, split testing thanks to CloudWatch Evidently. We will try all of this, so stay tuned.