Build a UGC Live Streaming App with Amazon IVS: Schema Overview (Lesson 1.5)

Build a UGC Live Streaming App with Amazon IVS: Schema Overview (Lesson 1.5)

Welcome to Lesson 1.5 in this series where we're looking at building a web based user-generated content live streaming application with Amazon IVS. This entire series is available in video format on the AWS Developers YouTube channel and all of the code related to the sample application used in this series can be viewed on GitHub. Refer to the links at the end of the post for more information.

Todd Sharp
Amazon Employee
Published Dec 12, 2023


In this lesson, we'll take a look at the database schema behind the StreamCat application. After this lesson, you will understand the individual model objects and their properties, and how they relate to one another.

User Model

The User model is very basic - besides the id, created_at, and updated_at properties that are common to almost all entities in the application, it contains only a username and password. This model is persisted in the users table which looks like this:
User Model
Your UGC application may contain much more information about a User, but since we are focusing on the live streaming aspect of the application, our User model is intentionally lightweight.

User Relationships

When a User is created, three AWS resources are created via the AWS SDK for JavaScript (v3) and information about those resources is stored in the StreamCat database so that it can easily be retrieved without requiring SDK calls later on.
Why Is This Info Stored in the Database? Technically, the information about these resources could be retrieved by StreamCat via the AWS SDK for JavaScript (v3), but that could quickly lead to our application hitting the Amazon IVS service quotas for SDK calls. Since these values do not change, it makes sense to store them in our application's database to avoid unnecessary SDK calls.
1. Amazon IVS Channel (Channel)
2. Amazon IVS Chat Room (ChatRoom)
3. Amazon IVS Stage (Stage)
The Channel, ChatRoom, and Stage entity each have a one-to-one relationship with a User.
user relationships
User Relationships


The Channel model is persisted in the channels table, and stores the arn, playback_url, ingest_endpoint, and stream_key that are returned by the SDK. These values are used by the application for broadcasting and playback. The Channel model includes additional properties:
  • title is the default title for all streams on this channel. This title is applied to the current live stream.
  • is_live indicates when a streamer is broadcasting to the channel. This value is updated automatically via our AWS Lambda function that is triggered by the EventBridge rule that we looked at in lesson 1.4.
  • is_partner indicates that a channel has reached "partner" status. We'll look at what this means in a subsequent lesson.
  • category_id - the category that the user has associated this channel with


The ChatRoom model is persisted in the chat_rooms table and stores the name, arn, and endpoint.


The Stage model is persisted in the stages table and stores the name, and arn. An additional boolean is_live property indicates when a real time stream is being broadcast by the user.

Channel Relationships

A Channel has a one-to-one relationship with a User (as shown above) and belongs to an optional Category which lets viewers know the topic of the channel. Each time a user live streams on a Channel, a Stream is automatically created which tracks information specific to that stream. The current title and category_id are copied into the Stream, and can be edited after the stream is offline to help viewers discover VODs. The Stream start and end timestamps (started_at and ended_at) and recording start and end timestamps (recording_started_at and recording_ended_at) are captured when the appropriate values are received via EventBridge events. When a recording is complete, the duration (recording_duration_ms) and the path to the recorded assets (recording_path) are persisted. A Stream has many Metric objects related to it. While viewers view a live stream, they periodically publish Metric entities. These metrics are used to determine current stream viewers and provide analytics to the streamer.
channel relationship model
Channel Relationship Model

ChatRoom Relationships

A ChatRoom has a one-to-one relationship with a User (as shown above) and has many ChatMessage entities. Each ChatMessage belongs to a Stream which has many Metric (as shown above).
ChatRoom relationship model
ChatRoom Relationship Model

Stage Relationships

A Stage has a one-to-one relationship with a User (as shown above) and has many StageToken entities. The StageToken belongs to a User and this property indicates the User who is invited to the current stage session (which is not _always_ the user who owns the stage). The token property represents the token that is generated via the AWS SDK for JavaScript (v3). This token has an an expiration timestamp which is represented by the expires_at timestamp.
Stage relationship model
Stage Relationship Model


In this lesson, we learned about the schema and persistence model for the StreamCat application. This concludes lesson 1. In lesson 2, we will see how to create the cloud architecture that we learned about in lesson 1.4.


Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.