DEV Community: Salih Guler

Component hydration patterns that actually work with Jaspr

Salih Guler — Wed, 25 Mar 2026 21:26:54 +0000

Every framework with server-side rendering faces the same problem. You render HTML on the server, send it to the browser, then your JavaScript needs to take over without breaking what's already there. This is hydration, and most frameworks make you think about it constantly.

React introduced SSR years ago. In the older "Pages Router" model, you had to serialize state manually and often fought hydration mismatches. Modern Next.js (App Router) improved this with React Server Components, which stream data to the client automatically. However, you are still managing the "boundary" between server and client explicitly. You mark components with "use server" or "use client" and carefully manage which code runs where. Vue and Svelte have similar patterns. Every component that needs server data requires explicit data fetching and passing.

The core issue is that frameworks treat server rendering and client rendering as separate concerns. You render on the server, somehow get the data to the client, then render again. If these two renders produce different output, hydration breaks. If you forget to pass some state, components remount with empty data and flicker.

Jaspr takes a different approach. Components are universal by default. State syncs automatically. The same component code runs on server and client, and the framework handles transferring state between them without manual serialization.

This isn't specific to Jaspr. The pattern applies to any SSR framework. Some implement it better than others. Understanding how automatic hydration works makes you better at building SSR apps in any framework.

Why manual hydration is error-prone

Here's what most SSR frameworks make you do. First, fetch data on the server:

// Next.js example
export async function getServerSideProps() {
  const data = await fetchSomeData();
  return { props: { data } };
}

export default function Page({ data }) {
  return <div>{data.title}</div>;
}

This works, but you're managing data flow manually. The server fetches data, passes it as props, and the component renders. When this reaches the client, Next.js serializes data as JSON in the HTML, then deserializes it during hydration.

The problem shows up when you have nested components with their own data needs:

export default function Page({ data }) {
  return (
    <div>
      <Header data={data.header} />
      <Content data={data.content} />
      <Sidebar data={data.sidebar} />
    </div>
  );
}

You're threading props through every level. If Sidebar has a child component that needs data, you pass it down again. This is prop drilling, and it's a code smell.

You could use Context to avoid prop drilling, but that doesn't solve the real problem. You still fetched all the data at the top level and distributed it manually. If one component needs different data based on user interaction, you fetch it client-side and now you have two data fetching patterns in the same app.

Some frameworks let components fetch their own data. React Server Components do this. Each component can be async and fetch what it needs. The server waits for all async components, renders the tree, and sends it to the client.

This is better, but you still manage the boundary between server and client explicitly. You mark components with "use server" or "use client" and think about which code runs where. This is necessary complexity for React's architecture, but it's still complexity you're managing.

Automatic state sync reduces cognitive load

The better pattern is making state sync automatic. Components should be able to have state, and that state should transfer from server to client without you writing transfer code.

In modern Jaspr, the build method returns a single Component, aligning with Flutter’s syntax and enabling better performance optimizations in the Dart-to-JS compiler. Here's how it works in Jaspr:

class CounterComponent extends StatefulComponent {
  @override
  State createState() => _CounterState();
}

class _CounterState extends State<CounterComponent> {
  int _count = 0;

  void _increment() {
    setState(() {
      _count++;
    });
  }

  @override
  Component build(BuildContext context) {
    return button(
      events: {'click': (_) => _increment()},
      [.text('Count: $_count')],
    );
  }
}

When this renders on the server, _count is 0. Jaspr serializes that state and embeds it in the HTML. When the client hydrates, it reads that data and initializes the component with _count = 0. The button works immediately because the state is already there.

For complex data, Jaspr provides the @sync annotation. It automatically generates the logic needed to move data from the server to the client.

// article_page.dart
import 'article_page.sync.dart';

class ArticlePage extends StatefulComponent {
  final String id;
  const ArticlePage({required this.id});

  @override
  State createState() => _ArticlePageState();
}

class _ArticlePageState extends State<ArticlePage> with _ArticlePageStateSyncMixin, PreloadStateMixin {
  @sync
  Article? _article;

  @sync
  List<Comment> _comments =;

  @override
  Future<void> preloadState() async {
    // Only runs on the server to fetch data before the first render
    _article = await api.fetchArticle(widget.id);
    _comments = await api.fetchComments(widget.id);
  }

  @override
  Component build(BuildContext context) {
    if (_article == null) {
      return div([.text('Loading...')]);
    }

    return div([
      ArticleHeader(article: _article!),
      ArticleContent(article: _article!),
      CommentList(comments: _comments),
    ]);
  }
}

The PreloadStateMixin handles the server-side acquisition of data, delaying the render until the futures complete. The @sync annotation then ensures that once the client takes over, it already has the values for _article and _comments in its local state, preventing a "flash of loading" or redundant API calls.

Handling non-serializable state

Some state can't serialize: WebSocket connections, file handles, or DOM references. These exist only on the client.

class _RealtimeComponentState extends State<RealtimeComponent> {
  WebSocketChannel? _channel;
  List<Message> _messages =;

  @override
  void initState() {
    super.initState();
    // Only connect WebSocket on client
    if (kIsWeb) {
      _connectWebSocket();
    }
  }

  @override
  Component build(BuildContext context) {
    return div();
  }
}

The pattern handles this by checking kIsWeb. The server renders the initial UI, and the client establishes the live connection upon hydration.

Optimized tree reconciliation

Jaspr follows the Flutter model. It uses a component tree that produces a render tree. When you call setState, the framework reconciles the changes and applies surgical updates to the DOM. Because the build methods now return a single component, Jaspr can more efficiently track these dependencies and update only specific nodes without expensive full-page re-renders.

When to use SSR vs SSG vs CSR

While automatic hydration is powerful, you must choose the right rendering mode for your project. In Jaspr, this is a structural configuration defined in your pubspec.yaml or during the jaspr create step.

Unlike some frameworks, there is no --mode flag for the jaspr build command; the CLI reads your project's configuration to decide how to build your assets.

jaspr:
  mode: static # Can be 'static', 'server', or 'client'

Static (SSG): Pre-renders pages at build time. Ideal for blogs and documentation. Run jaspr build to generate static HTML.
Server (SSR): Renders components dynamically for every request. Essential for personalized or frequently changing content.
Client (CSR): Skips the server. Useful for behind-the-login dashboards where SEO isn't a priority.

Testing hydration without deploying

Jaspr includes a test package that simulates the full lifecycle in a single process, without needing a real browser.

import 'package:jaspr_test/jaspr_test.dart';

void main() {
  testComponents('Counter hydrates correctly', (tester) async {
    // 1. Setup component
    await tester.pumpComponent(CounterComponent());
    expect(find.text('Count: 0'), findsOneComponent);

    // 2. Simulate hydration transition
    await tester.hydrate();

    // 3. Interact with client-side logic
    await tester.click(find.tag('button'));
    expect(find.text('Count: 1'), findsOneComponent);
  });
}

This runs in a single test process. No actual server or browser needed. You can test the full lifecycle: server render, hydration, interaction, state updates.

For complex components with async data loading:

testComponents('Article page hydrates with data', (tester) async {
  final mockApi = MockArticleApi();
  when(mockApi.fetchArticle(any)).thenAnswer((_) async => testArticle);

  await tester.pumpComponent(
    ArticlePage(id: '123', api: mockApi),
  );

  // Wait for async data loading
  await tester.pump();

  expect(find.text(testArticle.title), findsOneComponent);

  // Hydration should preserve the loaded data
  await tester.hydrate();

  expect(find.text(testArticle.title), findsOneComponent);
  verify(mockApi.fetchArticle('123')).called(1);
});

Performance characteristics of different hydration strategies

Hydration has a cost. The server renders HTML, the client downloads JavaScript, parses it, and then "boots up" components. For large pages, this can take time.

Here's how different strategies compare:

Strategy	Initial Render	Time to Interactive	Server Load	Best For
Full SSR + hydration	Fast (HTML from server)	Medium (load & hydrate JS)	High (render per request)	Dynamic content, SEO-critical
SSG + hydration	Fastest (pre-rendered HTML)	Medium (load & hydrate JS)	None (built once)	Static content, blogs
CSR only	Slow (wait for JS)	Medium (render in browser)	None (static files)	Authenticated apps
Partial hydration	Fast (HTML from server)	Fast (hydrate only interactive parts)	Medium	Mostly static with interactive widgets
Islands architecture	Fast (HTML from server)	Fastest (minimal JS)	Medium	Content sites with isolated interactivity

Automatic state sync traditionally fits the "Full SSR + hydration" strategy. However, Jaspr now has first-class support for the Islands Architecture via the @island annotation and dedicated templates.

In an Islands approach, you render the page as static HTML and only hydrate specific, annotated components. This allows you to ship significantly less JavaScript to the client. You can use the jaspr create -t islands command to set up a project designed for this architecture from the start.

What this pattern enables

Automatic state sync changes how you think about building SSR apps. Instead of managing data flow between server and client, you write components with state and let the framework handle transfer.

The core insight is the same across frameworks: when the framework knows about your state, it can transfer it for you. The less you manage serialization and data flow manually, the fewer bugs you introduce.

For Dart developers, Jaspr makes this feel natural because the component model matches Flutter. If you've built Flutter apps, you already know how to manage state with setState. Making that work on the server and client is the framework's job, not yours.

The tradeoff is giving up control over exactly how and when state transfers. If you need custom serialization logic or want to optimize what data transfers, you're fighting the framework. For most apps, automatic is better. For apps with unique performance constraints, manual control might be necessary.

Resources

Connect with me on social media:

Twitter: @salihgueler
LinkedIn: @salihgueler
GitHub: @salihgueler
Bluesky: @salihgueler

Analyzing React Best Practices with Kiro Powers

Salih Guler — Wed, 21 Jan 2026 08:59:21 +0000

Developers pair-program with AI assistants to build software outside your expert areas. One big example I have observed is, backend and cloud engineers building frontends. However, they all have the same concern: how do you verify the frontend code quality and be sure you follow the best practices?

On last Wednesday (Jan 14th), Vercel announced the set of AI skills to follow the best practices for React and Next.js applications, addressing this exact need. Therefore, I decided to bring these best practices to Kiro as well by building a Kiro Power.

Before we move forward, a disclaimer: This is not an official version, it is just me using Kiro to build a Kiro power :)

Power Builder

We have been talking about Kiro Powers but what are they? Kiro Powers inject specialized context and tools into Kiro agents on-demand, providing focused knowledge exactly when needed. Unlike traditional context injection that loads everything upfront, Powers activate specific capabilities dynamically.

You might be wondering, why not just use MCP? Even though MCP is a great solution for many problems, it comes with trade-offs. To find an answer or a content, it still needs to go through information and it has an impact on the context window. However with powers, you can focus and bring only what you need and save some context window.

To build Kiro Powers you can use the Power Builder. You can add it with a single click to your project.

Once you add that, now Kiro has the resources and context to build new Kiro Powers.

Prompt that bringing all together

Writing a proper prompt is one of the most fun but also challenging parts of building with AI nowadays. We have to have crisp, well written instructions on what we want to build and how we want to build. We can't say "build me a sign up" page and expect AI to build everything without missing a point with the design that we are imagining.

There are great resources such as this FAQ section from Open AI on how to write prompts but I highly recommend the the great article that my colleague Danilo Poccia wrote on how you can optimize your AI assistant to optimize itself and it helped me a lot to optimize my prompt as well.

Each step in this prompt serves a purpose: Step 1 ensures complete feature coverage, Step 2 guarantees proper Power structure, Step 3 defines clear specifications, and Step 4 creates a review checkpoint before execution. This structure helps you adapt the prompt for your own Power creation.

1. I want to create a Kiro Power from the Vercel agent-skills repository. Clone https://github.com/vercel-labs/agent-skills and analyze all files including subfolders to understand the complete feature set.

2. Research the official Kiro Powers documentation online to understand the correct folder structure, POWER.md frontmatter syntax (name, displayName, description, keywords, mcpServers), and steering file best practices.

3. Create a Power called "react-best-practices" with:
a. Publisher: "Salih Güler"
b. All agent skills converted to steering files (exclude Vercel deployment content)
c. Proper keywords that match how developers naturally talk about React/Next.js optimization
d. A README explaining how to install and use the Power

4. Prepare a detailed plan first and propose it to me before creating any files. Show me:
a. Which agent skill files you found and what they cover
b. How you'll organize them into steering files
c. The proposed keywords for activation
d. The POWER.md frontmatter you'll use

Once I ran the prompt, Kiro activated the "Power Builder", went through the files, came up with a plan to map rules to steering files and created a plan to create a POWER.md file and asked me if I want to execute it. After I said yes, all was done in a few seconds:

Using Kiro Powers

You can use Kiro Powers in three different ways. You can use the official ones with a click and install. You can use them from GitHub repositories and from your local folders.

You can use the GitHub repository reference or the local folder to install the power.

Running the React Best Practices on an Actual Project

I built a project to teach some students about how to build a full-stack application with AWS.

When I built it, I was more prototyping and building to create a starting point for my students. With this I will check how much improvement that we can make on the project.

Once you run the project, it analyzes your codebase and identifies improvements. In my case, it found:

Missing error boundaries in React components
Unoptimized image loading without Next.js Image component
Client-side data fetching that could move to server components

Here's the full analysis:

After you are good with all, you can tell it to implement everything for your project. Once it is done, you can check the project on how many files changed and what changes happened.

You can also define a global steering file rule to commit the changes by splitting them logically.

Conclusion

AI transforms how we build software daily. Kiro Powers offer a focused approach to code quality—activating expert knowledge when you need it without overwhelming your context window.

What you learned:

How to convert existing agent skills into Kiro Powers
The difference between Powers and MCP servers
A practical workflow for code quality checks

Considerations:

Powers work best with well-defined rule sets
Initial setup requires understanding Power structure
Results depend on your project's complexity

This Power is part of promptz.dev (a website that you can find great prompts and context files to enhance your development workflow) for broader availability (and you can check the source code and create issues on the on the promptz.dev repository. Try it on your React projects and share feedback—your input helps improve the Power for everyone.

Building Real-Time Multiplayer Android Apps with AWS AppSync Events API

Salih Guler — Wed, 03 Sep 2025 11:31:29 +0000

Real-time experiences are essential for modern applications, from collaboration tools to multiplayer games. However, building these experiences traditionally meant managing complex WebSocket connections, handling state synchronization, and maintaining scalable infrastructure. AWS AppSync now offers a solution with its Events API, enabling developers to create interactive multi-user experiences without the burden of managing underlying real-time communication infrastructure.

In this blog post, you'll build QuizSync - a real-time multiplayer quiz app for Android that synchronizes player actions instantly across devices. By following along, you'll learn how to integrate the AWS AppSync Events API into a native Android application for real-time events and implement a real-time data synchronization mechanism while managing the game state across multiple clients.

Before diving into building QuizSync, ensure you have the following prerequisites set up:

Android Development

Android Studio (latest stable version)
Android SDK with minimum API level 24 (Android 7.0)
Kotlin 2.1.0 or higher
Gradle 8.0 or higher

AWS Account & Tools

AWS Account with appropriate permissions
AWS CLI installed and configured
Node.js 18+ (for AWS CDK)
AWS CDK v2 installed globally (npm install -g aws-cdk)

AWS AppSync Events API - The Foundation

Before you start diving into the development of the application, you have to understand how the Events API work. AWS AppSync Events is a fully-managed Pub/Sub service powered by serverless WebSocket APIs. It allows developers to publish and receive messages directly over WebSocket connections, and supports publishing messages over an HTTP endpoint as well. AppSync Events API allows developers to use a single WebSocket connection for both publishing and receiving events, making it easy to develop real-time features and reducing implementation complexity.

AWS AppSync Events API operates through a six-step process that eliminates traditional WebSocket complexity:

Clients establish WebSocket connections to the service.
Events are organized into hierarchical namespaces (like /chat or /game) containing specific channels (like chat/room1).
Clients subscribe to relevant channels with our simple client side library methods.
Events can be published via either HTTP POST requests or directly through the connected WebSocket.
Optional backend processing on the service side with handlers to process, filter, and authorize events in real-time.
Events are automatically distributed to all subscribed clients using unicast, multicast, or broadcast patterns.

The service provides enterprise-grade authentication through five methods (API Key, IAM, Cognito, OIDC, Lambda) and delivers key benefits including serverless operation, automatic scaling, sub-second latency, built-in security, global distribution, pay-per-use pricing, and guaranteed message ordering - all without requiring any infrastructure management.

To simplify client-side development, AWS AppSync Events provides libraries for TypeScript and Kotlin. These client libraries make it easy to:

Establish WebSocket connections
Manage subscriptions
Handle real-time events
Implement error handling and reconnection logic

In the next section, we'll use these concepts to implement real-time features in our QuizSync application.

Building the QuizSync Game

QuizSync game follows a modern architecture that cleanly separates concerns across the Android client and AWS AppSync Events API. The system uses AppSync Event API’s real-time event capabilities to enable multiplayer quiz experiences, with structured event channels handling different aspects of gameplay from lobby management to live competition mechanisms.

Building the Backend

For building the backend infrastructure, we will use Cloud Development Kit (CDK). This way we can create the infrastructure through a programming language, in this case TypeScript. To start with the implementation, create a new folder for your project.

mkdir quizsyncbackend
cd quizsyncbackend

Afterwards, initialize the CDK project:

What this creates:

bin/ - Entry point for your CDK application
lib/ - Your CDK stack definitions
test/ - Unit tests for your infrastructure
package.json - Dependencies and scripts
tsconfig.json - TypeScript configuration
cdk.json - CDK-specific configuration

Open the entry point file bin/quizsyncbackend.ts and replace its contents with the following:

#!/usr/bin/env node
import * as cdk from "aws-cdk-lib";
import { QuizSyncStack } from "../lib/quizsyncbackend-stack";

const app = new cdk.App();

// Get environment from context or default to 'dev'
const environment = app.node.tryGetContext("environment") || "dev";

// Create the QuizSync stack with best practices
const stack = new QuizSyncStack(app, `QuizSyncStack-${environment}`, {
  // Specify the environment for the stack
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION || "us-east-1",
  },

  // Stack configuration
  environment,
  enableTracing: true,
  logRetentionDays:
    environment === "prod"
      ? cdk.aws_logs.RetentionDays.ONE_MONTH
      : cdk.aws_logs.RetentionDays.ONE_WEEK,

  // Add stack description
  description: `QuizSync Real-time Quiz Application - AppSync Events API Infrastructure (${environment})`,

  // Add tags for resource management
  tags: {
    Project: "QuizSync",
    Environment: environment,
    Purpose: "Production-Ready Implementation",
    ManagedBy: "CDK",
    Version: "2.0",
  },
});

The QuizSyncStack represents the main building block of our application. When you update lib/quizsyncbackend-stack.ts, you'll create an AppSync Events API that handles real-time event management. The stack includes API key configuration for authorization, enabling clients to connect, publish, and subscribe to real-time events. For monitoring purposes, the stack also provisions a dedicated CloudWatch log group and creates an IAM role for logging.

To implement these changes, open lib/quizsyncbackend-stack.ts and update it with the stack definition code:

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

export interface QuizSyncStackProps extends cdk.StackProps {
  environment?: string;
  enableTracing?: boolean;
  logRetentionDays?: logs.RetentionDays;
}

export class QuizSyncStack extends cdk.Stack {
  public readonly eventApi: appsync.EventApi;

  constructor(scope: Construct, id: string, props: QuizSyncStackProps = {}) {
    super(scope, id, props);

    const {
      environment = "dev",
      logRetentionDays = logs.RetentionDays.ONE_WEEK,
    } = props;

    // Create log configuration
    const logConfig: appsync.AppSyncLogConfig = {
      retention: logRetentionDays,
      excludeVerboseContent: false,
      fieldLogLevel: appsync.AppSyncFieldLogLevel.ALL,
    };

    // Create AppSync Events API with security best practices using L2 construct
    this.eventApi = new appsync.EventApi(this, "QuizSyncEventApi", {
      apiName: `QuizSyncEventApi-${environment}`,
      authorizationConfig: {
        authProviders: [
          {
            authorizationType: appsync.AppSyncAuthorizationType.API_KEY,
          },
        ],
        connectionAuthModeTypes: [appsync.AppSyncAuthorizationType.API_KEY],
        defaultPublishAuthModeTypes: [appsync.AppSyncAuthorizationType.API_KEY],
        defaultSubscribeAuthModeTypes: [
          appsync.AppSyncAuthorizationType.API_KEY,
        ],
      },
      logConfig,
      ownerContact: "QuizSync Admin",
    });

    // Add tags to the API
    cdk.Tags.of(this.eventApi).add("Environment", environment);
    cdk.Tags.of(this.eventApi).add("Project", "QuizSync");
    cdk.Tags.of(this.eventApi).add("ManagedBy", "CDK");

    // Create Channel Namespace for quiz events using L2 construct
    const quizNamespace = new appsync.ChannelNamespace(this, "QuizNamespace", {
      api: this.eventApi,
      channelNamespaceName: "quiz", // Creates channels like quiz/game123/lobby
      authorizationConfig: {
        publishAuthModeTypes: [appsync.AppSyncAuthorizationType.API_KEY],
        subscribeAuthModeTypes: [appsync.AppSyncAuthorizationType.API_KEY],
      },
    })

    // Add tags to the namespace
    cdk.Tags.of(quizNamespace).add("Environment", environment);
    cdk.Tags.of(quizNamespace).add("Project", "QuizSync");

    // Create API Key with proper expiration (1 year)
    const apiKey = new appsync.CfnApiKey(this, "QuizSyncApiKey", {
      apiId: this.eventApi.apiId,
      description: `API Key for QuizSync Events API - ${environment}`,
      expires: Math.floor(Date.now() / 1000) + 365 * 24 * 60 * 60, // 1 year from now (Unix timestamp)
    });

    // Create comprehensive outputs for Android app
    this.createOutputs(environment, apiKey);
  }

  private createOutputs(environment: string, apiKey: appsync.CfnApiKey) {
    new cdk.CfnOutput(this, "EventApiId", {
      value: this.eventApi.apiId,
      description: "AppSync Events API ID",
      exportName: `QuizSyncEventApiId-${environment}`,
    });

    new cdk.CfnOutput(this, "EventApiEndpoint", {
      value: this.eventApi.realtimeDns,
      description: "AppSync Events WebSocket Endpoint",
      exportName: `QuizSyncEventApiEndpoint-${environment}`,
    });

    new cdk.CfnOutput(this, "EventApiHttpEndpoint", {
      value: this.eventApi.httpDns,
      description: "AppSync Events HTTP Endpoint",
      exportName: `QuizSyncEventApiHttpEndpoint-${environment}`,
    });

    new cdk.CfnOutput(this, "ApiKey", {
      value: apiKey.attrApiKey,
      description: "API Key for authentication",
      exportName: `QuizSyncApiKey-${environment}`,
    });

    new cdk.CfnOutput(this, "Region", {
      value: this.region,
      description: "AWS Region",
      exportName: `QuizSyncRegion-${environment}`,
    });
  }
}

Now we are ready to, validate that our CDK code compiles correctly and prepare the CDK for deployment:

# Install the packages
npm install

# Build the TypeScript project
npm run build

# Synthesize CloudFormation templates (recommended over just building)
cdk synth

# Bootstrap CDK in your AWS account (only needed once per account/region)
cdk bootstrap

Now it is time to deploy:

cdk deploy

After the successful deployment, we will see outputs like the following:

 ✅  QuizSyncStack-dev

✨  Deployment time: 54.26s

Outputs:
QuizSyncStack-dev.ApiKey = <API_KEY_REDACTED>
QuizSyncStack-dev.EventApiEndpoint = <API_ENDPOINT_REDACTED>.appsync-realtime-api.us-east-1.amazonaws.com
QuizSyncStack-dev.EventApiHttpEndpoint = <API_ENDPOINT_REDACTED>.appsync-api.us-east-1.amazonaws.com
QuizSyncStack-dev.EventApiId = <API_ID_REDACTED>
QuizSyncStack-dev.Region = us-east-1
Stack ARN:
arn:aws:cloudformation:us-east-1:<ACCOUNT_ID_REDACTED>:stack/QuizSyncStack-dev/<STACK_ID_REDACTED>

✨  Total time: 57.43s

Now that the backend infrastructure is in place, let's build the Android application.

Building the Android App

A starter project is provided that includes all the necessary UI elements for the application. You can focus on implementing the real-time functionality without building the UI from scratch. Clone the project from GitHub to start the implementation.

First, enable isCoreLibraryDesugaringEnabled for the AWS AppSync Android libraries. Add the following configuration to your app-level build.gradle file:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
        // Enable core library desugaring for AWS SDK compatibility
        isCoreLibraryDesugaringEnabled = true
    }
}

Also, add these dependencies to implement the AWS AppSync functionality:

dependencies {
    // AWS AppSync Events library
    implementation("com.amazonaws:aws-sdk-appsync-events:1.0.0")

    // Core library desugaring for AWS SDK compatibility (updated version)
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

After syncing your Gradle changes, configure the AppSync connection details. Open config/AppSyncConfig.kt and replace the API_KEY and HTTP_ENDPOINT values with your backend information:

const val API_KEY = "<API-KEY>"

const val HTTP_ENDPOINT = "<API_ENDPOINT_REDACTED>.appsync-api.us-east-1.amazonaws.com/event"

Create a new AppSync client to manage the backend connection. In your project:

Delete MockAppSyncEventsClient.kt
Create a new file called AppSyncEventsClient.kt

package com.example.quizsync.service

import com.example.quizsync.data.GameEvent
import kotlinx.coroutines.flow.Flow

/**
 * AppSync Events API client for QuizSync real-time communication
 */
class AppSyncEventsClient : EventsClient {

    override suspend fun publishEvent(channel: String, event: GameEvent): PublishEventResult {
        TODO("Not yet implemented")
    }

    override fun subscribeToGame(gameId: String): Flow<GameEvent> {
        TODO("Not yet implemented")
    }

    override suspend fun disconnect() {
        TODO("Not yet implemented")
    }
}

Add the following variables to AppSyncEventsClient.kt:

A WebSocket client to connect to the Events API for updates
An events endpoint for publishing events
A custom logger mechanism to display messages (optional)

The client code after adding these variables should look like this:

package com.example.quizsync.service

import android.util.Log
import com.amazonaws.sdk.appsync.core.LogLevel
import com.amazonaws.sdk.appsync.core.Logger
import com.amazonaws.sdk.appsync.core.authorizers.ApiKeyAuthorizer
import com.amazonaws.sdk.appsync.events.Events
import com.amazonaws.sdk.appsync.events.EventsWebSocketClient
import com.example.quizsync.config.AppSyncConfig
import com.example.quizsync.data.GameEvent
import kotlinx.coroutines.flow.Flow

/**
 * AppSync Events API client for QuizSync real-time communication
 */
class AppSyncEventsClient : EventsClient {

    // Initialize Events client with HTTP endpoint
    private val events: Events = Events(AppSyncConfig.HTTP_ENDPOINT)
    private val apiKeyAuthorizer = ApiKeyAuthorizer(AppSyncConfig.API_KEY)

    private val webSocketClient: EventsWebSocketClient = events.createWebSocketClient(
        connectAuthorizer = apiKeyAuthorizer,
        subscribeAuthorizer = apiKeyAuthorizer,
        publishAuthorizer = apiKeyAuthorizer,
        options = Events.Options.WebSocket(
            loggerProvider = { namespace -> AndroidLogger(namespace, LogLevel.DEBUG) }
        )
    )

    private val restApiClient: EventsRestClient = events.createRestClient(
        publishAuthorizer = apiKeyAuthorizer,
        options = Events.Options.Rest(
            loggerProvider = { namespace -> AndroidLogger(namespace, LogLevel.DEBUG) }
        )
    )

    override suspend fun publishEvent(channel: String, event: GameEvent): PublishEventResult {
        TODO("Not yet implemented")
    }

    override fun subscribeToGame(gameId: String): Flow<GameEvent> {
        TODO("Not yet implemented")
    }

    override suspend fun disconnect() {
        TODO("Not yet implemented")
    }
}

/**
 * Android Logger implementation for AppSync Events library
 */
class AndroidLogger(
    private val namespace: String,
    override val thresholdLevel: LogLevel
) : Logger {

    override fun error(message: String) {
        if (!thresholdLevel.above(LogLevel.ERROR)) {
            Log.e(namespace, message)
        }
    }

    override fun error(message: String, error: Throwable?) {
        if (!thresholdLevel.above(LogLevel.ERROR)) {
            Log.e(namespace, message, error)
        }
    }

    override fun warn(message: String) {
        if (!thresholdLevel.above(LogLevel.WARN)) {
            Log.w(namespace, message)
        }
    }

    override fun warn(message: String, issue: Throwable?) {
        if (!thresholdLevel.above(LogLevel.WARN)) {
            Log.w(namespace, message, issue)
        }
    }

    override fun info(message: String) {
        if (!thresholdLevel.above(LogLevel.INFO)) {
            Log.i(namespace, message)
        }
    }

    override fun debug(message: String) {
        if (!thresholdLevel.above(LogLevel.DEBUG)) {
            Log.d(namespace, message)
        }
    }

    override fun verbose(message: String) {
        if (!thresholdLevel.above(LogLevel.VERBOSE)) {
            Log.v(namespace, message)
        }
    }
}

Update the publishEvent function to publish messages to the Events API. This function uses the specified channel name to route messages to the appropriate subscribers:


/**
* Publish a game event to a specific channel
* 
* Make sure to add the below imports
* import com.amazonaws.sdk.appsync.events.data.PublishResult 
* import kotlinx.serialization.encodeToString 
* import kotlinx.serialization.json.Json
*/
override suspend fun publishEvent(channel: String, event: GameEvent): PublishEventResult {
    return try {
        val jsonElement = Json.encodeToJsonElement(event)
        Log.d("AppSyncEvents", "Publishing to channel: $channel, event: $jsonElement")
        // Get the AWS PublishResult from the SDK
        val publishResult = webSocketClient.publish(
            channelName = channel,
            event = jsonElement
        )
        // Convert AWS PublishResult to our generic PublishEventResult
        when (publishResult) {
            is PublishResult.Response -> {
                Log.d(
                    "AppSyncEvents",
                    "Publish successful: ${publishResult.successfulEvents.size} events sent"
                )
                if (publishResult.failedEvents.isNotEmpty()) {
                    Log.w(
                        "AppSyncEvents",
                        "Some events failed: ${publishResult.failedEvents.size}"
                    )
                    PublishEventResult.Failure("Some events failed: ${publishResult.failedEvents.joinToString()}")
                } else {
                    PublishEventResult.Success("Successfully published ${publishResult.successfulEvents.size} events")
                }
            }
            is PublishResult.Failure -> {
                Log.e("AppSyncEvents", "Publish failed", publishResult.error)
                PublishEventResult.Failure(
                    "AWS publish failed: ${publishResult.error.message}",
                    publishResult.error
                )
            }
        }
    } catch (e: Exception) {
        Log.e("AppSyncEvents", "Exception during publish", e)
        PublishEventResult.Failure("Exception during publish: ${e.message}", e)
    }
}

Add the subscribeToGame function to handle and map incoming events. This function converts incoming messages into GameEvent objects, which represent different game states such as:

Player joins
Answer submissions
Other game-related events

/**
* Subscribe to all channels for a specific game using wildcard
* Make sure to import the following:
* import kotlinx.coroutines.flow.catch 
* import kotlinx.coroutines.flow.map 
* import kotlinx.coroutines.flow.onCompletion
* import kotlinx.serialization.json.decodeFromJsonElement
*/
override fun subscribeToGame(gameId: String): Flow<GameEvent> {
    val wildcardChannel = allGameChannels(gameId)
    return subscribeToChannel(wildcardChannel)
}

/**
 * Wildcard subscription for all game channels
 */
private fun allGameChannels(gameId: String) = "quiz/$gameId/*"

/**
 * Subscribe to a channel and receive game events
 */
private fun subscribeToChannel(channel: String): Flow<GameEvent> {
    Log.d("AppSyncEvents", "Subscribing to channel: $channel")
    return webSocketClient.subscribe(channel)
        .onCompletion {
            Log.d("AppSyncEvents", "Subscription to $channel completed")
        }
        .catch { throwable ->
            Log.e("AppSyncEvents", "Subscription to $channel failed", throwable)
            throw throwable
        }
        .map { eventsMessage ->
            try {
                // Convert JsonElement to GameEvent
                Json.decodeFromJsonElement<GameEvent>(eventsMessage.data)
            } catch (e: Exception) {
                Log.e("AppSyncEvents", "Error parsing event data", e)
                // Return a generic error event
                GameEvent.Error("Failed to parse event data: ${e.message}")
            }
        }
}

To properly manage resources, implement the cleanup function to disconnect any active WebSocket connections:

/**
* Disconnect the WebSocket client
*/
override suspend fun disconnect() {
    try {
        Log.d("AppSyncEvents", "Disconnecting WebSocket client")
        webSocketClient.disconnect(flushEvents = true)
    } catch (e: Exception) {
        Log.e("AppSyncEvents", "Error disconnecting WebSocket", e)
    }
}

Now you test the real-time functionality by:

Building and running the application on your device or emulator.
Observing the real-time updates as they appear on the screen.

Clean up resources

To avoid ongoing charges, delete the resources you created:

Run the following command to destroy all CDK-deployed resources:

cdk destroy

Verify the cleanup in the AWS Management Console by confirming that the resources have been deleted.

Wrapping Up

AWS AppSync's Events API provides a managed solution for implementing real-time functionality in your applications. This solution offers several benefits:

Managed WebSocket connections eliminate the need for custom infrastructure maintenance
Client libraries simplify implementation
Infrastructure as code through CDK enables consistent deployments

For detailed information, see the AWS AppSync documentation and official documentation for Android libraries. Also, you can check the fully implementation version of the project over GitHub.

If you're using AI development tools like Amazon Q Developer CLI, configure your environment to use Model Context Protocol (MCP) servers from AWS Labs in your coding assistants.

How I Built a Flame Engine MCP Server to Build Flutter Games

Salih Guler — Wed, 02 Jul 2025 20:00:26 +0000

Building cross-platform games with Flutter and the Flame engine offers exciting possibilities, but the learning curve can be steep. Developers often struggle with grasping new concepts, finding appropriate libraries, and efficiently navigating between development environments and documentation. In this blog post, we will show how to leverage Amazon Q Developer to improve your Flutter game development process, enabling you to focus on creativity rather than wrestling with technical hurdles.

In this blog post, we show how you can create a Model Context Protocol (MCP) server that integrated into any tool that supports MCP, e.g. Amazon Q Developer CLI. The server can be used to improve your Flutter game development workflow. By the end of this tutorial, you'll have a custom MCP server that:

Provides real-time, context-sensitive coding assistance for Flame engine development
Offers instant access to relevant documentation and best practices
Helps debug common issues specific to Flutter game development
Accelerates your learning of game development concepts within your familiar IDE

The approach outlined in this post can help developers to improve their game creation process. Whether you're building your first Flutter game or looking to optimize your existing development workflow, this integration of Amazon Q Developer CLI through an MCP server can significantly increase your productivity.

Let's dive into how you can set up this game development sidekick and start building Flutter games more efficiently.

Requirements

Latest version of Flutter and Dart SDKs. Install them through official docs.
An active GitHub account with a personal access token.Learn how to create a GitHub token
Amazon Q Developer CLI installed and configured. Install and set up Amazon Q Developer. You can use the Amazon Q Developer CLI through BuilderID.
An IDE or text editor of your choice (we recommend Visual Studio Code with the Dart extension)

If you are interested in the source code, you can:

Check out the Flame MCP Server project
Check out the source code of the Pong game

Understanding MCP

The Model Context Protocol (MCP) standardizes how applications provide context to Large Language Models (LLMs). It serves as an intelligent intermediary between AI models and external tools or data sources for our AI workflows.

MCP provides the following three core capabilities:

Resources: File-like data that clients can read, such as Flame engine documentation, tutorial content, and code examples from your game project
Tools: Functions that LLMs can execute (with user approval), such as searching through documentation, analyzing game code, or providing relevant code snippets
Prompts: Pre-written templates that help users accomplish specific tasks, like finding the right animation implementation or debugging game physics

For example, when working with Flutter and the Flame engine, MCP can help you quickly find relevant documentation about sprite animations while you're coding, suggest optimizations for your game loop implementation, or provide step-by-step guidance for implementing complex game mechanics - all without leaving your development environment.

Now that we understand what MCP is and how it can enhance game development, let's look at how to build an MCP server that integrates with Amazon Q Developer to create this seamless documentation and learning experience.

Building the MCP Server for Flame Engine with AI Assistant

Building an MCP server for the Flame engine presented an exciting challenge that combined cutting-edge AI integration with game development. After discussions with Lukas, one of the Flame Engine maintainers, I decided to implement the MCP server in Dart to ensure consistency with the engine's ecosystem. This approach would provide seamless integration for Flame developers.

While the official MCP website offers tutorials and SDKs, creating a custom MCP server without these tools can be complex. To overcome this challenge, I used the power of AI-assisted development using Amazon Q Developer CLI. This tool significantly improved the development process by providing context-aware coding assistance and access to relevant documentation. In the following sections, we'll explore how Amazon Q Developer CLI helped me with the creation of our Dart-based MCP server, offering a blueprint for integrating AI assistance into your own game development workflow.

To kick off, open up the Q Developer CLI by writing q to the terminal:

Next, we'll walk through the process of using Amazon Q Developer CLI to create our Dart-based MCP server for the Flame engine. Follow these steps to implement your own server:

Copy the contents of the MCP server guide file into the CLI. This file contains essential information about MCP server requirements.
Describe your specific MCP server requirements. Here's an example prompt:

With the provided context, I want to build a Model Context Protocol (MCP) server from scratch that provides AI assistants like Claude Desktop and Amazon Q Developer 
with comprehensive access to Flame game engine documentation and tutorials. The MCP server should be written in Dart and implement the MCP specification (JSON-RPC 
over stdio). It needs two main tools: 'search_documentation' for searching through cached Flame docs, and 'tutorial' for providing step-by-step game development 
tutorials (space shooter, platformer, klondike). The server should read from a local cache directory containing 146+ markdown files downloaded from the 
flame-engine/flame GitHub repository's doc folder. Include proper error handling, absolute path resolution for cross-platform compatibility, and clean 
separation between the MCP server (read-only operations) and a separate sync script that downloads documentation from GitHub API. The server should support 
both resource listing ( for Claude Desktop) and tool execution, with proper MCP protocol responses including initialize, tools/list, tools/call, and 
resources/list methods. Make it production-ready with proper logging, documentation, and a build script that compiles everything into a single executable 
that can be configured in MCP client settings.

Allow Amazon Q Developer CLI to generate the server code. Once complete, review the output carefully:

Examine the overall structure and package imports
Verify that all requested capabilities are implemented
Check for Dart-specific best practices and Flame engine compatibility

To test and validate, you can perform the following tests to ensure your MCP server functions correctly:

Manual testing:

Use different MCP clients to test server responses
Verify that documentation access works as expected
Test the search functionality with various queries

Data and behavior verification:

Cross-reference server responses with official Flame documentation
Check for any inconsistencies or unexpected behaviors

Code quality assessment:

Run Dart analyzer: dart analyze
Apply lint rules
Review generated code for readability and maintainability

With Amazon Q Developer CLI, we've demonstrated how to rapidly create an MCP server for the Flame engine. However, for those who prefer a more hands-on approach or want to deepen their understanding of MCP server architecture, the following sections will guide you through building the server manually.

This step-by-step walkthrough will not only showcase what your project might look like when built from scratch but also provide valuable insights into the inner workings of an MCP server. By comparing the AI-assisted and manual approaches, you'll gain a comprehensive understanding of MCP server development for game engines like Flame.

Building the MCP Server Manually

Creating the Dart Projeect

First, create a Dart project:

dart create -t cli flame_mcp_server

This command will create a project with following structure:

When building your MCP server in Dart, it's important to organize your code following Dart's conventional project structure. Here's how to set up your project directories:

bin/

Contains executable applications
Place your MCP server entry point here
This code will be directly executable

lib/

Houses your core business logic
Contains internal MCP server implementation
Includes service integrations and utilities

lib/src/

Stores Dart resource files
Keep implementation details here
Contains reusable components and helpers

This structure ensures clean separation of concerns and follows Dart best practices for maintainable code.

Creating the Doc Syncer

Before implementing our MCP server, we need to gather the documentation resources it will use to provide answers. In this section, we'll create a Dart program that downloads Flame engine documentation locally using the GitHub API.

The following diagram shows how the documentation synchronizer interacts with GitHub's API to download and store documentation files:

Let's create a new file called flame_doc_syncer.dart under the bin folder. First, we'll implement the main entry point:

void main() async {
  print('🔄 Syncing Flame Documentation');
  print('==============================');

  final syncer = FlameDocSyncer();

  try {
    await syncer.syncDocs();
    print('✅ Documentation sync completed successfully!');
  } catch (e) {
    print('❌ Sync failed: $e');
    exit(1);
  } finally {
    syncer.dispose();
  }
}

Next, we'll create the FlameDocSyncer class with the core functionality:

class FlameDocSyncer {
  FlameDocSyncer({String? githubToken})
      : _githubToken = githubToken ?? Platform.environment['GITHUB_TOKEN'];

  static const String repoApiUrl =
      'https://api.github.com/repos/flame-engine/flame/contents/doc';
  static const String rawBaseUrl =
      'https://raw.githubusercontent.com/flame-engine/flame/main/doc';

  // Use absolute path for cache directory
  static String get cacheDir {
    // Get the directory where the script is located
    final scriptPath = Platform.script.toFilePath();
    final scriptDir =
        File(scriptPath).parent.parent.path; // Go up from bin/ to project root
    return path.join(scriptDir, 'flame_docs_cache');
  }

  final http.Client _client = http.Client();
  final String? _githubToken;

  //TODO: Add the header logic 

  /// Sync documentation from GitHub
  Future<void> syncDocs() async {
    // Show authentication status
    if (_githubToken != null && _githubToken.isNotEmpty) {
      print('🔑 Using GitHub personal access token (higher rate limits)');

      // Check rate limit
      final rateLimitInfo = await getRateLimitStatus();
      if (rateLimitInfo.containsKey('rate')) {
        final rate = rateLimitInfo['rate'];
        print(
            '📊 API Rate Limit: ${rate['remaining']}/${rate['limit']} requests remaining');
        if (rate['remaining'] < 10) {
          print('⚠️  Warning: Low API rate limit remaining!');
        }
      }
    } else {
      print(
          '⚠️  No GitHub token found - using unauthenticated requests (60/hour limit)');
      print(
          '💡 Set GITHUB_TOKEN environment variable for higher limits (5000/hour)');
    }

    // Create cache directory
    final dir = Directory(cacheDir);
    if (await dir.exists()) {
      print('🗑️  Clearing existing cache...');
      await dir.delete(recursive: true);
    }
    await dir.create(recursive: true);
    print('📁 Cache directory: $cacheDir');

    // Fetch all markdown files
    await _fetchDirectory('');

    // Count cached files
    int fileCount = 0;
    await for (final entity in dir.list(recursive: true)) {
      if (entity is File && entity.path.endsWith('.md')) {
        fileCount++;
      }
    }

    print('📚 Cached $fileCount documentation files');
  }

  //TODO: Check rate limit

  //TODO: Add Directory Check

  //TODO: Download file

  //TODO: Dispose logic
}

The code above:

Creates the Flame doc syncer object with a GitHub token if provided. If not, it checks the environment variables or keeps it null. The reason for this implementation is to prevent hitting GitHub API limitations when making calls without a personal access token. With the token, we can make 5,000 calls to the GitHub API per hour without hitting any limits.
We define our API doc URLs and the directory to cache the documentation.
Next, we create our HTTP client.
When the syncDocs function is called, it downloads the full documentation.

However, our implementation includes additional checks and logic throughout the process. For instance, we verify if we've reached the API rate limit for the current token using the following code:

Future<Map<String, dynamic>> getRateLimitStatus() async {
  try {
    final response = await _client.get(
      Uri.parse('https://api.github.com/rate_limit'),
      headers: _getHeaders(),
    );

    if (response.statusCode == 200) {
      return jsonDecode(response.body);
    } else {
      throw Exception('Failed to get rate limit: ${response.statusCode}');
    }
  } catch (e) {
    return {'error': e.toString()};
  }
}

/// Get HTTP headers for GitHub API requests
Map<String, String> _getHeaders() {
  final headers = <String, String>{
    'Accept': 'application/vnd.github.v3+json',
    'User-Agent': 'Flame-MCP-Server/1.0',
  };

  if (_githubToken != null && _githubToken.isNotEmpty) {
    headers['Authorization'] = 'token $_githubToken';
  }

  return headers;
}

To download all documentation files, including those in subfolders, we implement a recursive download process. The following code handles both individual file downloads at a specific path and complete subfolder traversal when no path is specified:

Future<void> _fetchDirectory(String relativePath) async {
  final apiUrl =
      relativePath.isEmpty ? repoApiUrl : '$repoApiUrl/$relativePath';

  try {
    final response = await _client.get(
      Uri.parse(apiUrl),
      headers: _getHeaders(),
    );

    if (response.statusCode == 403) {
      // Check if it's a rate limit issue
      final rateLimitRemaining = response.headers['x-ratelimit-remaining'];
      if (rateLimitRemaining == '0') {
        throw Exception(
            'GitHub API rate limit exceeded. Please wait or use a personal access token.');
      }
      throw Exception(
          'Access forbidden: ${response.statusCode}. Check your GitHub token permissions.');
    } else if (response.statusCode != 200) {
      throw Exception('Failed to fetch directory: ${response.statusCode}');
    }

    final List<dynamic> items = jsonDecode(response.body);

    for (final item in items) {
      final name = item['name'] as String;
      final type = item['type'] as String;
      final itemPath = relativePath.isEmpty ? name : '$relativePath/$name';

      if (type == 'dir') {
        // Create local directory and recurse
        final localDir = Directory(path.join(cacheDir, itemPath));
        await localDir.create(recursive: true);
        await _fetchDirectory(itemPath);
      } else if (type == 'file' && name.endsWith('.md')) {
        // Download markdown file
        await _downloadFile(itemPath);
      }
    }
  } catch (e) {
    print('⚠️  Error fetching directory $relativePath: $e');
    rethrow;
  }
}

Future<void> _downloadFile(String remotePath) async {
  final rawUrl = '$rawBaseUrl/$remotePath';
  final localPath = path.join(cacheDir, remotePath);

  try {
    final response = await _client.get(
      Uri.parse(rawUrl),
      headers: _getHeaders(),
    );

    if (response.statusCode == 200) {
      await File(localPath).writeAsString(response.body);
      print('📄 Downloaded: $remotePath');
    } else if (response.statusCode == 403) {
      print('⚠️  Access forbidden for $remotePath: ${response.statusCode}');
    } else {
      print('⚠️  Failed to download $remotePath: ${response.statusCode}');
    }
  } catch (e) {
    print('⚠️  Error downloading $remotePath: $e');
  }
}

Finally, implement the dispose method to properly close the HTTP client connection:

void dispose() {
  _client.close();
}

To run the documentation synchronization tool, execute the following command in your terminal:

dart run bin/flame_doc_syncer.dart

Building the MCP Server

Before implementing the MCP server, let's examine its architecture and core components:

The diagram illustrates the key components of our MCP server architecture:

A client interface for user interaction
JSON-RPC for message delivery between client and server
Two core tools:
- A documentation search tool
- A tutorial retrieval tool
A build script to automate the entire process

Before we dive into the server implementation, let's briefly explain JSON-RPC:

JSON-RPC is a lightweight communication protocol that enables remote procedure calls using JSON formatting. Let's explore its key aspects:

Core concepts

JSON-RPC operates as a stateless protocol with built-in error handling. It uses a simple request-response pattern:

The client sends a JSON-formatted request
The server processes the request
The server returns a JSON-formatted response

Message structure

Every JSON-RPC message includes these required fields:

jsonrpc: Identifies the protocol version
id: Matches requests with their corresponding responses
method: Specifies which function to execute

Request messages contain:

params: Arguments for the method call

Response messages include either:

result: Contains successful operation data
error: Contains error details with codes and messages

Transport options

JSON-RPC supports multiple transport methods:

HTTP/HTTPS: For web APIs and REST services
WebSocket: For real-time, persistent communication
stdio: For process-to-process communication (used in our MCP implementation)
TCP/UDP: For direct network connections

Let's go back to building. First create a flame_mcp_live.dart file under bin folder and start the server from there:

import 'package:flame_mcp_server/src/flame_mcp_live.dart';

void main() async {
  final server = FlameMcpLive();
  await server.start();
}

Now create a file under lib/src called flame_mcp_live.dart and start with the implementation:

import 'dart:convert';
import 'dart:io';
import 'flame_live_docs.dart';

/// Local MCP server for Flame documentation
class FlameMcpLive {
  final FlameLiveDocs _docs = FlameLiveDocs();

  /// Start the MCP server
  Future<void> start() async {
    // MCP servers must not print to stdout - only JSON-RPC messages
    // Use stderr for logging instead
    stderr.writeln('🎮 Starting Flame MCP Server (Local Mode)');

    // Initialize documentation system
    await _docs.initialize();

    // Start MCP server
    stdin
        .transform(utf8.decoder)
        .transform(const LineSplitter())
        .listen(_handleRequest);
  }

  //TODO: Handle Request
  //TODO: Process Request
  //TODO: Handle Initialize
  //TODO: Handle Resource List
  //TODO: Hanle Reading Resources
  //TODO: Handle tools list
  //TODO: Handle tools call
  //TODO: Handle tutorials
}

When calling the start function, we initialize the FlameLiveDocs class. This separate class follows the single responsibility principle, where each class has one specific purpose:

FlameDocSyncer: Handles documentation download and caching
FlameLiveDocs: Manages documentation search and serving

This separation prevents cache management issues by ensuring that:

Only FlameDocSyncer can modify the documentation cache
The MCP server (FlameLiveDocs) has read-only access to the cache
Cache updates occur only when explicitly requested

Let's implement this by adding the following code to lib/src/flame_doc_syncer.dart:

import 'dart:io';
import 'package:path/path.dart' as path;

/// Simple, robust live documentation fetcher for Flame engine
class FlameLiveDocs {
  // Use absolute path for cache directory
  static String get cacheDir {
    // Get the directory where the executable is located
    final executablePath = Platform.resolvedExecutable;
    final executableDir = File(executablePath).parent.path;

    // The executable is in build/, so go up one level to project root
    final projectRoot = Directory(executableDir).parent.path;
    return path.join(projectRoot, 'flame_docs_cache');
  }

  /// Initialize the documentation system
  Future<void> initialize() async {
    // Check if cache exists and build index
    final dir = Directory(cacheDir);
    if (await dir.exists()) {
      await _buildIndex();
    }
  }

  // Cache for indexed resources
  List<String>? _cachedResources;

  /// Build index of all cached files
  Future<void> _buildIndex() async {
    final resources = <String>[];
    final dir = Directory(cacheDir);

    if (await dir.exists()) {
      await for (final entity in dir.list(recursive: true)) {
        if (entity is File && entity.path.endsWith('.md')) {
          final relativePath = path.relative(entity.path, from: cacheDir);
          final uri =
              'flame://${relativePath.replaceAll(path.separator, '/').replaceAll('.md', '')}';
          resources.add(uri);
        }
      }
    }

    _cachedResources = resources;
  }

  //TODO: getResources call
  //TODO: getContent call
  //TODO: _sanitizeContent call
  //TODO: search call
  //TODO: searchTutorials call
}

With the documentation indexing in place, we can now implement the search functionality in our MCP server. Let's update the flame_mcp_live.dart file by replacing the TODO items with the key components of this implementation.

Core Request Handling

_handleRequest(String line):

Parses and validates incoming JSON-RPC requests
Routes them to appropriate handlers
Manages error responses for malformed requests

*_processRequest(Map request):
*

Routes validated requests to specific method handlers
Supports methods like initialize, tools/list, and resources/read
Differentiates between notifications and regular requests

void _handleRequest(String line) async {
  dynamic requestId;
  try {
    // First try to parse the JSON
    final request = jsonDecode(line);

    // Extract the ID for error handling
    requestId = request['id'];

    // Validate required fields
    if (request['jsonrpc'] != '2.0') {
      _sendError(requestId, -32600, 'Invalid JSON-RPC version');
      return;
    }

    if (request['method'] == null) {
      _sendError(requestId, -32600, 'Missing method field');
      return;
    }

    // Check if this is a notification (no id field)
    final isNotification = requestId == null;

    final response = await _processRequest(request);

    // Only send response for requests, not notifications
    if (!isNotification && response.isNotEmpty) {
      final jsonResponse = jsonEncode(response);
      stdout.writeln(jsonResponse);
    }
  } catch (e) {
    // Use the extracted ID if available, otherwise null
    _sendError(requestId, -32700, 'Parse error: $e');
  }
}

Future<Map<String, dynamic>> _processRequest(
    Map<String, dynamic> request) async {
  final method = request['method'] as String?;
  final id = request['id'];
  final params = request['params'] as Map<String, dynamic>?;

  // Check if this is a notification (no id field)
  final isNotification = id == null;

  // Validate that we have a method
  if (method == null || method.isEmpty) {
    if (isNotification) {
      // For notifications, we can't send an error response
      stderr.writeln('Warning: Received notification without method');
      return {};
    }
    return _createError(id, -32600, 'Missing or empty method field');
  }

  switch (method) {
    case 'initialize':
      if (isNotification) {
        stderr.writeln(
            'Warning: Initialize should be a request, not notification');
        return {};
      }
      return _handleInitialize(id);

    case 'notifications/initialized':
      // Handle initialized notification - no response needed
      stderr.writeln('Received initialized notification');
      return {};

    case 'resources/list':
      if (isNotification) {
        stderr.writeln(
            'Warning: resources/list should be a request, not notification');
        return {};
      }
      return await _handleResourcesList(id);

    case 'resources/read':
      if (isNotification) {
        stderr.writeln(
            'Warning: resources/read should be a request, not notification');
        return {};
      }
      return await _handleResourcesRead(id, params);

    case 'tools/list':
      if (isNotification) {
        stderr.writeln(
            'Warning: tools/list should be a request, not notification');
        return {};
      }
      return _handleToolsList(id);

    case 'tools/call':
      if (isNotification) {
        stderr.writeln(
            'Warning: tools/call should be a request, not notification');
        return {};
      }
      return await _handleToolsCall(id, params);

    case 'ping':
      if (isNotification) {
        stderr.writeln('Warning: ping should be a request, not notification');
        return {};
      }
      return _handlePing(id);

    default:
      if (isNotification) {
        stderr.writeln('Warning: Unknown notification method: $method');
        return {};
      }
      return _createError(id, -32601, 'Method not found: $method');
  }
}

Connection Management

_handleInitialize(dynamic id):

Manages MCP initialization handshake
Returns server capabilities and protocol version
Establishes initial connection parameters

Map<String, dynamic> _handleInitialize(dynamic id) {
  return {
    'jsonrpc': '2.0',
    'id': id,
    'result': {
      'protocolVersion': '2024-11-05',
      'capabilities': {
        'resources': {'listChanged': true},
        'tools': {'listChanged': true},
      },
      'serverInfo': {
        'name': 'flame-mcp-local',
        'version': '1.0.0',
        'description':
            'Local Flame game engine MCP server with on-demand GitHub documentation'
      }
    }
  };
}

Resource Management

_handleResourcesList(dynamic id):

Provides a catalog of available Flame documentation
Includes URIs, names, and descriptions

_handleResourcesRead(dynamic id, Map? params):

Retrieves documentation content by URI
Returns formatted content for client consumption

Future<Map<String, dynamic>> _handleResourcesList(dynamic id) async {
  final resources = await _docs.getResources();

  final resourceList = resources.map((uri) {
    final name = uri.replaceFirst('flame://', '').replaceAll('/', ' > ');
    return {
      'uri': uri,
      'name': 'Flame: $name',
      'description': 'Flame engine documentation: $name',
      'mimeType': 'text/markdown'
    };
  }).toList();

  return {
    'jsonrpc': '2.0',
    'id': id,
    'result': {'resources': resourceList}
  };
}

Future<Map<String, dynamic>> _handleResourcesRead(
    dynamic id, Map<String, dynamic>? params) async {
  final uri = params?['uri'] as String?;
  if (uri == null) {
    return _createError(id, -32602, 'Missing uri parameter');
  }

  final content = await _docs.getContent(uri);
  if (content == null) {
    return _createError(id, -32603, 'Resource not found: $uri');
  }

  // Additional content sanitization for JSON safety
  final safeContent = _safeJsonContent(content);

  return {
    'jsonrpc': '2.0',
    'id': id,
    'result': {
      'contents': [
        {'uri': uri, 'mimeType': 'text/markdown', 'text': safeContent}
      ]
    }
  };
}

Tools and Tutorial Management

_handleToolsList(dynamic id):

Lists available MCP tools (search_documentation and tutorial)
Includes tool descriptions and input schemas

_handleToolsCall(dynamic id, Map? params):

Executes requested tools with provided arguments
Returns formatted results

Map<String, dynamic> _handleToolsList(dynamic id) {
  final tools = [
    {
      'name': 'search_documentation',
      'description': 'Search through Flame documentation',
      'inputSchema': {
        'type': 'object',
        'properties': {
          'query': {'type': 'string', 'description': 'Search query'}
        },
        'required': ['query']
      }
    },
    {
      'name': 'tutorial',
      'description':
          'Get complete Flame tutorials with step-by-step instructions for building games (space shooter, platformer, klondike). Use this for learning how to build specific games.',
      'inputSchema': {
        'type': 'object',
        'properties': {
          'topic': {
            'type': 'string',
            'description':
                'Tutorial topic: "space shooter" for complete space shooter game tutorial, "platformer" for platformer game tutorial, "klondike" for card game tutorial, or "list" to see all available tutorials'
          }
        },
        'required': ['topic']
      }
    },
  ];

  return {
    'jsonrpc': '2.0',
    'id': id,
    'result': {'tools': tools}
  };
}

Future<Map<String, dynamic>> _handleToolsCall(
    dynamic id, Map<String, dynamic>? params) async {
  final toolName = params?['name'] as String?;
  final arguments = params?['arguments'] as Map<String, dynamic>? ?? {};

  if (toolName == null) {
    return _createError(id, -32602, 'Missing tool name');
  }

  try {
    String result;

    switch (toolName) {
      case 'search_documentation':
        final query = arguments['query'] as String? ?? '';
        if (query.isEmpty) {
          result = '❌ Search query cannot be empty';
        } else {
          final results = await _docs.search(query);
          if (results.isEmpty) {
            result = 'No results found for "$query"';
          } else {
            final buffer = StringBuffer();
            buffer.writeln('Found ${results.length} results for "$query":\n');
            for (final result in results.take(5)) {
              buffer.writeln('📄 **${result['title']}** (${result['uri']})');
              buffer.writeln('   ${result['snippet']}\n');
            }
            result = buffer.toString();
          }
        }
        break;

      case 'tutorial':
        final topic = arguments['topic'] as String? ?? '';
        if (topic.isEmpty) {
          result = '❌ Tutorial topic cannot be empty';
        } else {
          result = await _handleTutorialRequest(topic);
        }
        break;

      default:
        result = 'Unknown tool: $toolName';
    }

    return {
      'jsonrpc': '2.0',
      'id': id,
      'result': {
        'content': [
          {'type': 'text', 'text': result}
        ]
      }
    };
  } catch (e) {
    return _createError(id, -32603, 'Tool execution failed: $e');
  }
}

Tutorial Processing

_handleTutorialRequest(String topic):

Lists all tutorials
Provides step-by-step game guides
Enables tutorial content search

_getCompleteTutorial(String tutorialName):

Assembles comprehensive game tutorials
Orders steps sequentially
Supports multiple game types (space shooter, platformer, klondike)

/// Handle tutorial requests
Future<String> _handleTutorialRequest(String topic) async {
  final lowerTopic = topic.toLowerCase();

  // Handle "list" request to show all available tutorials
  if (lowerTopic == 'list') {
    return await _listAllTutorials();
  }

  // For specific tutorial requests, provide comprehensive step-by-step content
  if (lowerTopic.contains('space shooter') ||
      lowerTopic.contains('spaceshooter')) {
    return await _getCompleteTutorial('space_shooter');
  } else if (lowerTopic.contains('platformer')) {
    return await _getCompleteTutorial('platformer');
  } else if (lowerTopic.contains('klondike')) {
    return await _getCompleteTutorial('klondike');
  }

  // Fallback to search for tutorials matching the topic
  final tutorialResults = await _docs.searchTutorials(lowerTopic);

  if (tutorialResults.isEmpty) {
    return 'No tutorials found for "$topic". Try "list" to see all available tutorials.';
  }

  final buffer = StringBuffer();
  buffer.writeln(
      '🎓 Found ${tutorialResults.length} tutorial(s) for "$topic":\n');

  for (final tutorial in tutorialResults) {
    buffer.writeln('📚 **${tutorial['title']}** (${tutorial['uri']})');
    buffer.writeln('   ${tutorial['snippet']}\n');
  }

  return buffer.toString();
}


/// Get complete tutorial with all steps
Future<String> _getCompleteTutorial(String tutorialName) async {
  final resources = await _docs.getResources();
  final tutorialResources = resources
      .where((uri) => uri.contains('tutorials/$tutorialName/'))
      .toList();

  if (tutorialResources.isEmpty) {
    return 'No tutorial found for "$tutorialName".';
  }

  // Sort to get main tutorial first, then steps in order
  tutorialResources.sort((a, b) {
    final aName = a.split('/').last;
    final bName = b.split('/').last;

    // Main tutorial file comes first
    if (aName == tutorialName) return -1;
    if (bName == tutorialName) return 1;

    // Sort steps numerically
    final aStep = _extractStepNumber(aName);
    final bStep = _extractStepNumber(bName);
    return aStep.compareTo(bStep);
  });

  final buffer = StringBuffer();
  buffer.writeln(
      '🎮 ${_formatTopicName(tutorialName)} Tutorial - Complete Guide\n');
  buffer.writeln('\\=' * 50);
  buffer.writeln();

  for (int i = 0; i < tutorialResources.length; i++) {
    final uri = tutorialResources[i];
    final content = await _docs.getContent(uri);

    if (content != null) {
      final fileName = uri.split('/').last;
      final isMainTutorial = fileName == tutorialName;
      final stepNumber = isMainTutorial ? 0 : _extractStepNumber(fileName);

      if (isMainTutorial) {
        buffer.writeln('📖 **Overview**\n');
      } else {
        buffer.writeln('📝 **Step $stepNumber**\n');
      }

      // Get first few paragraphs of content
      final lines = content.split('\n');
      final contentLines = lines
          .where((line) =>
              line.trim().isNotEmpty &&
              // dev.to does not allow me to put the backsticks together. 
              !line.startsWith('`' + '`' + '`') &&
              !line.startsWith('![') &&
              !line.startsWith('{'))
          .take(10)
          .toList();

      for (final line in contentLines) {
        if (line.startsWith('#')) {
          buffer.writeln('**${line.replaceAll('#', '').trim()}**');
        } else {
          buffer.writeln(line);
        }
      }

      buffer.writeln('\n📄 Full content: $uri\n');
      buffer.writeln('-' * 30);
      buffer.writeln();
    }
  }

  buffer.writeln('💡 **Next Steps:**');
  buffer.writeln('• Use the URIs above to get full content for each step');
  buffer.writeln('• Follow the steps in order for best results');
  buffer.writeln('• Each step builds upon the previous one');

  return buffer.toString();
}

/// List all available tutorials
Future<String> _listAllTutorials() async {
  final resources = await _docs.getResources();
  final tutorials =
      resources.where((uri) => uri.contains('tutorials/')).toList();

  if (tutorials.isEmpty) {
    return 'No tutorials found in the documentation cache.';
  }

  final buffer = StringBuffer();
  buffer.writeln('🎓 Available Flame Tutorials:\n');

  // Group tutorials by main topic
  final tutorialGroups = <String, List<String>>{};

  for (final uri in tutorials) {
    // Parse URI like "flame://tutorials/space_shooter/step_1"
    final parts = uri.replaceFirst('flame://', '').split('/');
    if (parts.length >= 2 && parts[0] == 'tutorials') {
      final mainTopic = parts.length >= 3 ? parts[1] : 'general';
      tutorialGroups.putIfAbsent(mainTopic, () => []).add(uri);
    }
  }

  for (final entry in tutorialGroups.entries) {
    final topic = entry.key;
    final uris = entry.value;

    buffer.writeln('📖 **${_formatTopicName(topic)}**');

    // Sort URIs to show main tutorial first, then steps
    uris.sort((a, b) {
      final aName = a.split('/').last;
      final bName = b.split('/').last;

      // Main tutorial files (same name as directory) come first
      if (aName == topic) return -1;
      if (bName == topic) return 1;

      // Then sort steps numerically
      return aName.compareTo(bName);
    });

    for (final uri in uris) {
      final title = uri.replaceFirst('flame://', '').replaceAll('/', ' > ');
      buffer.writeln('   • $title');
    }
    buffer.writeln();
  }

  buffer
      .writeln('💡 Use `tutorial <topic>` to get specific tutorial content.');
  buffer.writeln(
      '   Example: `tutorial space shooter` or `tutorial platformer`');

  return buffer.toString();
}

/// Format topic name for display
String _formatTopicName(String topic) {
  return topic
      .split('_')
      .map((word) => word[0].toUpperCase() + word.substring(1))
      .join(' ');
}

Map<String, dynamic> _handlePing(dynamic id) {
  return {'jsonrpc': '2.0', 'id': id, 'result': {}};
}

Utility Functions

_safeJsonContent(String content):

Sanitizes markdown content
Normalizes line endings
Ensures safe JSON transmission

_extractStepNumber(String filename) and _formatTopicName(String topic):

Parse and format tutorial metadata
Enable proper content organization

/// Safely encode content for JSON transmission
String _safeJsonContent(String content) {
  // Additional safety for JSON encoding
  return content
      .replaceAll('\r\n', '\n') // Normalize line endings
      .replaceAll('\r', '\n') // Handle old Mac line endings
      .replaceAll('\t', '    ') // Replace tabs with spaces
      .replaceAll(RegExp(r'[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]'),
          ''); // Remove control chars
}

/// Extract step number from filename
int _extractStepNumber(String filename) {
  final match = RegExp(r'step_?(\d+)').firstMatch(filename);
  return match != null ? int.parse(match.group(1)!) : 999;
}

Error Handling

_createError(dynamic id, int code, String message) and _sendError(dynamic id, int code, String message):

Create standardized error responses
Handle JSON encoding failures
Ensure reliable error communication

Map<String, dynamic> _createError(dynamic id, int code, String message) {
  return {
    'jsonrpc': '2.0',
    'id': id,
    'error': {'code': code, 'message': message}
  };
}

void _sendError(dynamic id, int code, String message) {
  try {
    stdout.writeln(jsonEncode(_createError(id, code, message)));
  } catch (e) {
    // Fallback for encoding errors
    stdout.writeln(
        '{"jsonrpc":"2.0","id":null,"error":{"code":-32603,"message":"Internal JSON encoding error"}}');
  }
}

The key aspect of this implementation is that we communicate with our server using the JSON-RPC protocol over standard input/output (stdio).

Now, let's implement the final piece of the FlameLiveDocs class:

/// Get all available documentation resources
Future<List<String>> getResources() async {
  // Return cached resources if available
  if (_cachedResources != null) {
    return _cachedResources!;
  }

  // Build index if not cached
  await _buildIndex();
  return _cachedResources ?? [];
}

/// Get content for a specific resource
Future<String?> getContent(String uri) async {
  final docPath = uri.replaceFirst('flame://', '');
  final filePath = path.join(cacheDir, '$docPath.md');
  final file = File(filePath);

  if (await file.exists()) {
    final content = await file.readAsString();
    return _sanitizeContent(content);
  }

  return null;
}

/// Sanitize content to avoid JSON encoding issues
String _sanitizeContent(String content) {
  // Remove or replace characters that might cause JSON parsing issues
  return content
      // Replace text emoticons that might cause issues
      .replaceAll(':)', '🙂')
      .replaceAll(':(', '🙁')
      .replaceAll(':D', '😀')
      .replaceAll(';)', '😉')
      // Remove control characters except newlines and tabs
      .replaceAll(RegExp(r'[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]'), '')
      // Ensure content is valid UTF-8
      .replaceAll('\uFFFD', '?'); // Replace replacement character
}

/// Search through documentation
Future<List<Map<String, dynamic>>> search(String query) async {
  final results = <Map<String, dynamic>>[];
  final resources = await getResources();

  for (final uri in resources) {
    try {
      final content = await getContent(uri);
      if (content != null &&
          content.toLowerCase().contains(query.toLowerCase())) {
        final title = uri.replaceFirst('flame://', '').replaceAll('/', ' > ');
        final snippet = _extractSnippet(content, query);

        results.add({
          'uri': uri,
          'title': title,
          'snippet': snippet,
        });
      }
    } catch (e) {
      // Skip files that can't be read
    }
  }

  return results;
}

/// Search specifically through tutorial documentation
Future<List<Map<String, dynamic>>> searchTutorials(String query) async {
  final results = <Map<String, dynamic>>[];
  final resources = await getResources();

  // Filter to only tutorial resources
  final tutorialResources =
      resources.where((uri) => uri.contains('tutorials/')).toList();

  for (final uri in tutorialResources) {
    try {
      final content = await getContent(uri);
      if (content != null &&
          content.toLowerCase().contains(query.toLowerCase())) {
        final title = uri.replaceFirst('flame://', '').replaceAll('/', ' > ');
        final snippet = _extractSnippet(content, query);

        results.add({
          'uri': uri,
          'title': title,
          'snippet': snippet,
        });
      }
    } catch (e) {
      // Skip files that can't be read
    }
  }

  return results;
}

String _extractSnippet(String content, String query) {
  final lines = content.split('\n');
  for (int i = 0; i < lines.length; i++) {
    if (lines[i].toLowerCase().contains(query.toLowerCase())) {
      final start = (i - 1).clamp(0, lines.length - 1);
      final end = (i + 2).clamp(0, lines.length);
      return lines.sublist(start, end).join('\n').trim();
    }
  }
  return lines.take(3).join('\n').trim();
}

getResources() - Returns a list of all available documentation resource URIs, using cached results if available or building the index from the local cache directory if needed.
getContent(String uri) - Retrieves the actual markdown content for a specific documentation resource by converting the URI to a file path and reading the corresponding cached file.
_sanitizeContent(String content) - Cleans markdown content by replacing text emoticons with Unicode emojis, removing control characters, and ensuring valid UTF-8 encoding to prevent JSON parsing issues.
search(String query) - Performs a case-insensitive search across all documentation resources, returning matching results with URI, formatted title, and content snippet for each match.
searchTutorials(String query) - Conducts a focused search specifically within tutorial documentation by filtering resources to only those containing "tutorials/" in their URI path.
_extractSnippet(String content, String query)- Creates a contextual preview by finding the line containing the search query and returning it along with one line before and one line after, or the first three lines if no match is found.

Running the MCP Server

To launch the MCP server, execute the following command in your terminal:

dart compile exe bin/flame_mcp_live.dart -o build/flame_mcp_live

Now that we have the executable MCP server, we can integrate it into our development process. To do this, we'll add a reference to the executable in our MCP client.

However, running each file separately would make the process more cumbersome. To streamline the development workflow, let's create a shell script to automate the entire process.

#!/bin/bash

echo "🔨 Building Flame MCP Server (Local)"
echo "===================================="

# Install dependencies
echo "📦 Installing dependencies..."
dart pub get

if [ $? -ne 0 ]; then
    echo "❌ Failed to install dependencies"
    exit 1
fi

# Create build directory
mkdir -p build

echo "🏗️  Building MCP server..."
dart compile exe bin/flame_mcp_live.dart -o build/flame_mcp_live

if [ $? -ne 0 ]; then
    echo "❌ Failed to build MCP server"
    exit 1
fi

# Make executable
chmod +x build/flame_mcp_live

echo ""
echo "📚 Fetching Flame documentation..."
echo "   • This may take 30-60 seconds depending on network speed"

# Use the standalone sync script to fetch documentation
dart run bin/flame_doc_syncer.dart

if [ $? -ne 0 ]; then
    echo "⚠️  Documentation sync failed, but build completed"
    echo "   You can manually sync later with: dart run bin/flame_sync_standalone.dart"
else
    echo "✅ Documentation cached successfully!"
fi

echo ""
echo "✅ Build completed successfully!"
echo ""
echo "📋 Available:"
echo "   • build/flame_mcp_live           - MCP server (search only)"
echo "   • bin/flame_doc_syncer.dart - Manual documentation sync"
echo ""
echo "📁 Documentation cache:"
echo "   • flame_docs_cache/              - Local Flame documentation"
echo ""
echo "🚀 Usage:"
echo "   # Start MCP server"
echo "   ./build/flame_mcp_live"
echo ""
echo "   # Manual sync (refresh docs)"
echo "   dart run bin/flame_doc_syncer.dart"
echo ""

To integrate the MCP server with your MCP client, you need to update the client's configuration file. For example, if you're using Amazon Q Developer, follow these steps:

Open the Amazon Q Developer configuration file.
Add the following entry to specify the MCP server:

{
  "mcpServers": {
    "flame-docs": {
      "command": "/absolute/path/to/flame_mcp_server/build/flame_mcp_live"
    }
  }
}

After configuring the MCP client, launch the application to verify the integration. You should now see that the client recognizes and can interact with the Flame Engine documentation:

With the Flame Engine documentation now integrated, you can test the system by asking questions about Flame. Here's an example of how the AI assistant responds to Flame Engine queries:

What can I build by running the MCP Server?

So far, we've built our own MCP server using Dart to handle Flame Engine documentation. But how can we ensure everything is working as expected?

The beauty of this MCP server integration is that it unlocks the ability to build any 2D game idea using the Flame engine with minimal hassle. As a hands-on exercise, we challenge you to use the Amazon Q Developer CLI to create a fancy Pong game and see if you can match the level of polish in our example.

By leveraging the Flame engine documentation and tools accessed through the MCP server, you can rapidly prototype and develop your own creative 2D game projects. Give it a try and let us know how it goes!

Wrapping Up

This integration demonstrates how AI tools can accelerate game development workflows. By combining the Flame engine with AI assistance through our MCP server, you can prototype and develop games more efficiently.

To learn more:

Check out the Flame MCP Server project
Check out the source code of the Pong game
Explore the Flame engine documentation

If you like the content drop a like to the blog and if you have any questions, drop it as a comment or find me over LinkedIn.

AI-Guided AWS Deployment for Your Dart Backend Applications

Salih Guler — Wed, 14 May 2025 08:57:26 +0000

Dart's potential for backend development has gained a lot of attention. While Dart's official shelf library has been the traditional solution for backend development, there has been other solutions to enable full-stack Dart applications. Projects like Serverpod and Dart Frog are expanding the ecosystem, making it easier than ever to build complete applications using Dart on both frontend and backend.

In the age of AI, you ask many of your questions to AI and deploying backend as a Flutter developer can be a question that you might ask as well. In this blog post, you will see how you can deploy your Dart backends to AWS with the help of Amazon Q Developer on CLI.

You can check out the source-code for the project over GitHub to start with. Besides that you have to have an AWS Account to deploy over AWS and for using Amazon Q Developer on CLI (or IDE) you should have Builder ID and install Q developer CLI by following the official documentation.

Deploying REST APIs

First, we have to start by running the Amazon Q Developer on our CLI. At any point in your project, you can type 'q' and it will show a window for you to interact.

If you want to limit the context, you can navigate to the root folder of your project. Next, you need to tell the Q CLI what you want from it.

I want to deploy the hello.dart file in the backend folder. I don't know anything about AWS. All I know is, hello.dart is an application for a REST API. Show me the simplest, fastest and cheapest way to deploy this dart backend app over AWS.

When you run this prompt, the Q CLI analyzes your project, locates the backend file you want to deploy, and recommends the best deployment method.

The Q CLI also explains why this deployment method works best.

Next, the Q CLI creates the necessary deployment files. You can choose between supervised development or allow automated deployment with minimal intervention.

Deploying to AWS

After the Q CLI generates the necessary files, you will find a Dockerfile among them.

FROM dart:stable AS build

WORKDIR /app
COPY pubspec.* ./
RUN dart pub get
COPY . .
RUN dart pub get --offline

# Build a minimal serving image
FROM dart:stable
COPY --from=build /app /app
WORKDIR /app

# Make sure the application listens on port 8080
ENV PORT=8080

# Install dependencies in the final image
RUN dart pub get

# Start the application
CMD ["dart", "bin/hello.dart"]

# Expose the port
EXPOSE 8080

Docker creates a virtual environment that contains all necessary dependencies.

You can choose between AI-guided automated deployment or manual deployment following step-by-step instructions. For the REST API deployment, you will focus on the manual instructions first.

First, you need to create a repository in Amazon Elastic Container Registry (ECR) to store your Docker container image.

After naming the repository and keeping the default settings, click 'Create.' Amazon ECR will display commands for building and pushing the container.

After pushing the container, proceed to AWS App Runner to run it. Create a service and assign the container as a resource to this service.

Next, enter a name and keep the default settings.

The backend is now ready for deployment.

Troubleshooting

When you deploy your backend, the initial deployment may fail with the following information:

An advantage of working with AI is the ability to provide context for assistance with deployment or troubleshooting potential issues.

In this case, the system shows how to deploy containers to different architectures.

The solution requires rebuilding with multi-architecture support and updating the image in Amazon ECR:


# If you don't have buildx set up:
# Create a new builder instance
docker buildx create --name mybuilder --use

# Build with the correct platform
docker buildx build --platform=linux/amd64 --load -t hello .

# Tag and push
docker tag hello:latest AWS_USER_ID.dkr.ecr.us-east-1.amazonaws.com/full-stack-dart/hello:latest
docker push AWS_USER_ID.dkr.ecr.us-east-1.amazonaws.com/full-stack-dart/hello:latest

After rebuilding the project, the deployment completes successfully.

Also, the endpoint works as expected:

Deploying Dart Backends with Websockets

The shared codebase contains the original implementation: a game with an emoji counter. It uses WebSockets and provides real-time updates to each listener.

Now, let's switch the deployment approach from manual instructions to automated deployment using Q CLI, with human involvement limited to testing the results.

Run the following prompt on Q CLI:

Hello I want you to deploy the dart websocket backend under serverpod folder to the cheapest and fastest AWS option. I am not knowledgable with AWS so I want you to take care of necessary permissions, create necessary files and execute the deployment until it is successful. Make sure to use a service supporting websockets and service can be deployed through CLI. Also, make sure whatever way you deploy is in line with the deployment environment. E.g. if you are deploying to Linux, make sure to cover Linux related deployments. Test and make sure the connection is established before you complete the request. Once all is done and successful, document the steps and results to a markdown file.

Q CLI analyzes the project, examines the implementation, generates a solution, and provides detailed explanations.

Like before, hen prompted, enter 't' to authorize full AI implementation. After deployment, the system displays an execution summary:

As you have seen in the previous example, Dart backends lack direct deployment solutions. While AWS offers multiple services for containerized applications, Q CLI selected Elastic Beanstalk for these reasons:

It supports websockets
It's like having a hosting service specifically designed for web applications
It handles a lot of the complex infrastructure setup automatically
It's part of the AWS Free Tier, so it's cost-effective for our project

Think of Elastic Beanstalk as a service that takes your code and automatically sets up everything needed to run it online.

Containerizing Our App with Docker

Before deploying, Q CLI needed to package your app in a way that ensures it runs the same way everywhere. It updated your Dockerfile like the following:

FROM dart:stable AS build

WORKDIR /app
COPY pubspec.* ./
RUN dart pub get
COPY . .
RUN dart pub get --offline

# Build a minimal serving image
FROM dart:stable
COPY --from=build /app /app
WORKDIR /app

# Make sure the application listens on port 8080
ENV PORT=8080

# Install dependencies in the final image
RUN dart pub get

# Start the application
CMD ["dart", "bin/server.dart"]

# Expose the port
EXPOSE 8080

This Dockerfile:

Starts with a base Dart environment
Copies our app code
Installs dependencies
Sets up the command to run our server
Exposes port 8080 so the outside world can connect

Setting Up Network Security

Next, Q CLI created what AWS calls a Security Group - think of it as a virtual firewall that controls what traffic can reach our server:

✅ HTTP (port 80) - For regular web traffic
✅ HTTPS (port 443) - For secure web traffic
✅ WebSocket (port 8080) - For our real-time connections

This ensures that only the types of connections you expect can reach our server, helping to keep it secure.

Configuring WebSockets for Production

WebSockets are a bit trickier to set up in production than regular HTTP endpoints. They require special configuration to maintain long-lived connections.

Q CLI created a special configuration file for Nginx (the web server that sits in front of our application). This configuration tells Nginx how to handle WebSocket connections properly. The key parts are:

Setting up the /ws path to handle WebSocket protocol upgrades
Configuring proper headers for WebSocket connections
Setting a long read timeout so connections don't drop prematurely

Deployment Process

With everything configured, Q CLI deployed your app using the Elastic Beanstalk CLI:

Initialized the application - This creates the basic configuration
Created the environment - This provisions the actual server
Deployed the code - This uploads and runs your application

Behind the scenes, AWS:

Created a virtual machine (EC2 instance)
Set up Docker on that machine
Built your Docker container
Started your Dart server
Configured the network so it's accessible from the internet

What This Means for You as a Frontend Developer

Now that the backend is deployed, here's what you need to know:

WebSocket Connection: Update your frontend code to connect to ws://dart-emoji-backend-env.PROJECT-ID.us-east-1.elasticbeanstalk.com/ws instead of localhost
API Format: The message format remains the same:
- To send a reaction: {"type": "reaction", "emoji": "👍"}
- You'll receive: {"type": "counts", "counts": {"👍": 1, "❤️": 0, ...}}
Real-time Updates: Multiple users can now connect simultaneously from anywhere in the world, and all will see reactions in real-time

The best part? You don't need to worry about managing the server, scaling, or any of the backend infrastructure. It's all handled automatically by AWS Elastic Beanstalk.

Testing the Deployed Endpoint

Go to the websocket_service.dart file and update the getWebSocketUrl function to return your deployed URL and run the application:

Cleaning Up

If you are doing this as part of an experiment, make sure to delete the deleted resources. You can ask Q CLI to "clean up the deployed resources".

Make sure you also check the deployed services and the deletions happened successfully.

Summing up

AI-guided deployment offers powerful capabilities for Dart backend applications with Amazon Q Developer. While experience with AWS and containers enables custom workflow creation, starting with Q CLI to deploy backends provides a quicker and efficient path to successful Dart backend implementation.

To learn more about it, I challenge you to do more by doing one (or all) of the following:

Try to deploy the Serverpod backend with the same prompts
Try to deploy your Frontend with the guidance of Q CLI
Ask more complex questions about pricing :)

Make sure to check out the Amazon Q CLI docs as well as the Amazon Q on IDE to make the most out of your AWS experience for your full stack experiences.

Build Your Own AI Podcast Co-Host: Step-by-Step with Amazon Q CLI and Amazon Nova Sonic

Salih Guler — Tue, 08 Apr 2025 15:16:02 +0000

Ever dreamed of launching a podcast but struggled to find the perfect co-host? You're not alone. While we all have great ideas for content, finding a reliable podcast partner to deliver these ideas can be one of the biggest hurdles for aspiring content creators. But what if AI could solve this challenge? With this guide, you will learn how to build your own AI-powered podcast studio and create a dynamic virtual co-host using Amazon Q CLI and Amazon Nova Sonic from scratch.

At the end, you should be able to implement something similar to this:

Requirements:

Amazon Q CLI
Amazon Nova Sonic model access is granted
AWS CLI account configured to use Amazon Bedrock (in this case it is assumed to be named as default)

Planning

The app will be built with the newly announced Amazon Nova Sonic model. The model offers a state-of-the-art speech recognition and generation model that enables developers to create natural, human-like conversational AI experiences with low latency and industry-leading price performance.

Next.js app will allow the “human host” of the podcast app to communicate through voice and with the context and conversation it has, it will deliver the natural response back to the app.

Building the Frontend App

We will not be writing our frontend code now. You might be wondering why? Because this way, we will let the AI do the heavy-lifting for the UI and more importantly, we will add the proper code to proper places in our applications, in our control.

First of all, let’s start off by creating your base folder to build our application. Run the following command to create your folder:

mkdir podcastapp

And run the q chat to start your process of building your frontend:

You're tasked with creating a modern, responsive web application using Next.js 15 that will serve as
the foundation for migrating an existing Amazon Nova Sonic's Speech-to-Speech application. This new application should maintain all the core functionality of the original while providing an enhanced user experience through a clean, professional design that prioritizes accessibility and usability.

Begin by setting up a Next.js 15 project with the App Router architecture, TypeScript for type safety,
and Tailwind CSS for styling. Incorporate Shadcn/UI components to ensure a consistent design system throughout the application, and use Framer Motion for smooth animations and transitions. The application should be fully responsive, working seamlessly across desktop and mobile devices.

For the project structure, organize your code in a scalable way that will facilitate the future
integration of the actual business logic. Create directories for components, hooks, services, contexts, and types. Within the components directory, separate UI elements into logical categories such as conversation components, audio components, and layout components. This organization will make it easier to maintain and extend the application as it grows.

Implement a modern conversation interface that displays messages from both the user and AI assistant with clear visual distinction between roles. Include animated indicators for "listening," "thinking," and "speaking" states to provide users with feedback on the current system status. The chat container should auto-scroll to show new messages and maintain a clean, readable layout even with lengthy conversations.

Create audio control components that provide intuitive buttons for starting and stopping recording. Include a visual audio waveform component that animates when the user is speaking, providing visual feedback. Implement mock microphone permission handling with clear guidance for users on how to enable their microphone. While the actual audio recording functionality will be integrated later, the UI should fully simulate this behavior.

Develop a session management system that displays connection status, handles initialization flow, and provides appropriate error handling with recovery patterns. Include loading states and transitions to keep users informed about what's happening behind the scenes. This will be crucial for maintaining a good user experience when dealing with real-time audio streaming in the future.

Add a configuration panel that allows users to customize the system prompt, switch between light and dark themes, adjust accessibility settings, and configure mock AWS connection settings. This panel should be easily accessible but not intrusive to the main conversation interface.

For the initial implementation, create mock services that simulate the behavior of the actual services. The mock BedrockService should simulate connection/disconnection, fake audio streaming with appropriate timeouts, and generate plausible responses after a "processing" time. The mock AudioManager should handle fake microphone access requests, simulate recording and playback, and generate visualization data. The mock ConversationManager should maintain conversation state, handle turn-taking logic, and manage thinking/speaking indicators.

Pay special attention to accessibility features by implementing high contrast mode, ensuring screen reader compatibility, supporting keyboard navigation, and managing focus appropriately. These features should be built into the foundation of the application rather than added as an afterthought.

Document all components, hooks, and services with clear explanations of their purpose, props, and usage examples. Include notes about future integration points where the mock implementations will be replaced with actual functionality. This documentation will be invaluable when it's time to integrate the real Amazon Bedrock Nova S2S functionality.

The final deliverable should be a fully functional Next.js 15 application with mock implementations of
all core features, clean and well-documented TypeScript code, a responsive UI that works across devices, clear integration points for future business logic implementation, and basic documentation on project structure and component usage. This foundation will allow for a smooth transition when integrating the actual Amazon Nova Sonic functionality while providing an immediately usable and visually appealing interface.

This will create a website according to your description. It might not look the same, but it will look beautiful and modern at the end.

Here is what I had at one of the iterations:

Implementing the Core Service Classes

First, you will add the necessary libraries:

npm install @aws-sdk/client-bedrock-runtime @aws-sdk/credential-providers @smithy/node-http-handler @smithy/types

Then let's add some constants and types to define your configurations, these will be used throughout the application to provide and share information:

export const DefaultInferenceConfiguration = {
  maxTokens: 1024,
  topP: 0.9,
  temperature: 0.7,
};

export const DefaultAudioInputConfiguration = {
  audioType: "SPEECH" as AudioType,
  encoding: "base64",
  mediaType: "audio/lpcm" as AudioMediaType,
  sampleRateHertz: 16000,
  sampleSizeBits: 16,
  channelCount: 1,
};

export const DefaultToolSchema = JSON.stringify({
  "$schema": "http://json-schema.org/draft-07/schema#",
  type: "object",
  properties: {},
  required: [],
});

export const DefaultTextConfiguration = {
  mediaType: "text/plain" as TextMediaType,
};

export const DefaultSystemPrompt = `
You are a podcast co-host. The user and you will engage in a spoken dialog exchanging 
opinions and conversations about AWS. You should ask follow up questions and keep your responses short,
generally two or three sentences for chatty scenarios.
`;

export const DefaultAudioOutputConfiguration = {
  ...DefaultAudioInputConfiguration,
  sampleRateHertz: 24000,
  voiceId: "matthew",
};

export interface InferenceConfig {
  readonly maxTokens: number;
  readonly topP: number;
  readonly temperature: number;
}

export type ContentType = "AUDIO" | "TEXT" | "TOOL";
export type AudioType = "SPEECH";
export type AudioMediaType = "audio/wav" | "audio/lpcm" | "audio/mulaw" | "audio/mpeg";
export type TextMediaType = "text/plain" | "application/json";


export interface AudioConfiguration {
  readonly audioType: AudioType;
  readonly mediaType: AudioMediaType;
  readonly sampleRateHertz: number;
  readonly sampleSizeBits: number;
  readonly channelCount: number;
  readonly encoding: string;
  readonly voiceId?: string;
}

export interface TextConfiguration {
  readonly mediaType: TextMediaType;
}

export interface ToolConfiguration {
  readonly toolUseId: string;
  readonly type: "TEXT";
  readonly textInputConfiguration: {
    readonly mediaType: "text/plain";
  };
}

You will start by implementing the BedrockService class. It is designed to:

Create and manage sessions with Amazon Bedrock's Nova Sonic model
Handle audio streaming to the model
Register event handlers for different types of responses
Properly close sessions and clean up resources

Create it under services/bedrock/BedrockService.ts file:

import { S2SBidirectionalStreamClient, StreamSession } from './S2SBidirectionalStreamClient';
import { fromIni } from '@aws-sdk/credential-providers';

export class BedrockService {
  private client: S2SBidirectionalStreamClient;
  private sessions: Map<string, StreamSession> = new Map();

  constructor() {
    // Initialize the AWS Bedrock client with configuration
    this.client = new S2SBidirectionalStreamClient({
      requestHandlerConfig: {
        maxConcurrentStreams: 10,
      },
      clientConfig: {
        region: process.env.AWS_REGION || 'us-east-1',
        credentials: fromIni({ profile: process.env.AWS_PROFILE || 'default' })
      }
    });
  }

  /**
   * Creates a new session with AWS Bedrock and initializes it with the system prompt
   */
  async createSession(sessionId: string, systemPrompt: string): Promise<void> {
    try {
      // Create a new streaming session
      const session = this.client.createStreamSession(sessionId);
      this.sessions.set(sessionId, session);

      // Initialize the session with AWS Bedrock
      await this.client.initiateSession(sessionId);

      // Set up the prompt sequence
      await session.setupPromptStart();
      await session.setupSystemPrompt(undefined, systemPrompt);
      await session.setupStartAudio();

      console.log(`Session ${sessionId} created successfully`);
    } catch (error) {
      console.error(`Error creating session ${sessionId}:`, error);
      throw error;
    }
  }

  /**
   * Streams audio data to AWS Bedrock for processing
   */
  async streamAudio(sessionId: string, audioData: Buffer): Promise<void> {
    const session = this.sessions.get(sessionId);
    if (!session) {
      throw new Error(`Session ${sessionId} not found`);
    }

    await session.streamAudio(audioData);
  }

  /**
   * Registers an event handler for a specific session and event type
   */
  registerEventHandler(
    sessionId: string, 
    eventType: string, 
    handler: (data: any) => void
  ): void {
    const session = this.sessions.get(sessionId);
    if (!session) {
      throw new Error(`Session ${sessionId} not found`);
    }

    session.onEvent(eventType, handler);
  }

  /**
   * Properly closes a session and cleans up resources
   */
  async closeSession(sessionId: string): Promise<void> {
    const session = this.sessions.get(sessionId);
    if (!session) return;

    try {
      // Follow the proper shutdown sequence
      await session.endAudioContent();
      await session.endPrompt();
      await session.close();

      // Remove the session from our tracking
      this.sessions.delete(sessionId);
      console.log(`Session ${sessionId} closed successfully`);
    } catch (error) {
      console.error(`Error closing session ${sessionId}:`, error);
      // Even if there's an error, remove the session from tracking
      this.sessions.delete(sessionId);
    }
  }

  /**
   * Returns all active session IDs
   */
  getActiveSessions(): string[] {
    return Array.from(this.sessions.keys());
  }

  /**
   * Checks if a session is active
   */
  isSessionActive(sessionId: string): boolean {
    return this.sessions.has(sessionId);
  }
}

Next step is to implement the AudioManagerclass which handles:

Initializing the Web Audio API context
Requesting microphone access from the browser
Recording audio from the microphone and converting it to the format required by AWS Bedrock
Playing back audio responses received from the server
Proper cleanup of audio resources

Create it under services/audio/AudioManager.ts:

export class AudioManager {
  private audioContext: AudioContext | null = null;
  private audioStream: MediaStream | null = null;
  private processor: ScriptProcessorNode | null = null;
  private sourceNode: MediaStreamAudioSourceNode | null = null;
  private audioPlayer: any = null; // Will be initialized later
  private isRecording: boolean = false;

  /**
   * Initialize the audio context and player
   */
  async initialize(): Promise<void> {
    try {
      // Create audio context with 16kHz sample rate (matching Bedrock's requirements)
      this.audioContext = new AudioContext({ sampleRate: 16000 });

      // Initialize audio player (implementation will be in a separate class)
      this.audioPlayer = new AudioPlayer();
      await this.audioPlayer.start();

      console.log('AudioManager initialized successfully');
    } catch (error) {
      console.error('Error initializing AudioManager:', error);
      throw error;
    }
  }

  /**
   * Request microphone access from the browser
   */
  async requestMicrophoneAccess(): Promise<boolean> {
    try {
      this.audioStream = await navigator.mediaDevices.getUserMedia({
        audio: {
          echoCancellation: true,
          noiseSuppression: true,
          autoGainControl: true
        }
      });
      return true;
    } catch (error) {
      console.error("Error accessing microphone:", error);
      return false;
    }
  }

  /**
   * Start recording audio from the microphone
   * @param onAudioData Callback function that receives audio data
   */
  startRecording(onAudioData: (data: string) => void): void {
    if (!this.audioContext || !this.audioStream) {
      console.error('AudioContext or AudioStream not initialized');
      return;
    }

    try {
      this.isRecording = true;

      // Create audio source from microphone stream
      this.sourceNode = this.audioContext.createMediaStreamSource(this.audioStream);

      // Create script processor for audio processing
      this.processor = this.audioContext.createScriptProcessor(512, 1, 1);

      // Process audio data
      this.processor.onaudioprocess = (e) => {
        if (!this.isRecording) return;

        const inputData = e.inputBuffer.getChannelData(0);

        // Convert to 16-bit PCM (required by Bedrock)
        const pcmData = new Int16Array(inputData.length);
        for (let i = 0; i < inputData.length; i++) {
          pcmData[i] = Math.max(-1, Math.min(1, inputData[i])) * 0x7FFF;
        }

        // Convert to base64 for transmission
        const base64Data = this.arrayBufferToBase64(pcmData.buffer);

        // Send to callback
        onAudioData(base64Data);
      };

      // Connect the audio nodes
      this.sourceNode.connect(this.processor);
      this.processor.connect(this.audioContext.destination);

      console.log('Recording started');
    } catch (error) {
      console.error('Error starting recording:', error);
      this.isRecording = false;
    }
  }

  /**
   * Stop recording audio
   */
  stopRecording(): void {
    this.isRecording = false;

    // Clean up audio processing nodes
    if (this.processor) {
      this.processor.disconnect();
      this.processor = null;
    }

    if (this.sourceNode) {
      this.sourceNode.disconnect();
      this.sourceNode = null;
    }

    console.log('Recording stopped');
  }

  /**
   * Play audio data received from the server
   * @param audioData Base64 encoded audio data
   */
  playAudio(audioData: string): void {
    if (!this.audioPlayer) {
      console.error('AudioPlayer not initialized');
      return;
    }

    try {
      // Convert base64 to Float32Array for playback
      const audioBuffer = this.base64ToFloat32Array(audioData);
      this.audioPlayer.playAudio(audioBuffer);
    } catch (error) {
      console.error('Error playing audio:', error);
    }
  }

  /**
   * Clean up resources when component unmounts
   */
  cleanup(): void {
    this.stopRecording();

    if (this.audioContext) {
      this.audioContext.close();
      this.audioContext = null;
    }

    if (this.audioStream) {
      this.audioStream.getTracks().forEach(track => track.stop());
      this.audioStream = null;
    }

    if (this.audioPlayer) {
      this.audioPlayer.stop();
      this.audioPlayer = null;
    }

    console.log('AudioManager cleaned up');
  }

  /**
   * Convert ArrayBuffer to base64 string
   */
  private arrayBufferToBase64(buffer: ArrayBuffer): string {
    const binary = [];
    const bytes = new Uint8Array(buffer);
    for (let i = 0; i < bytes.byteLength; i++) {
      binary.push(String.fromCharCode(bytes[i]));
    }
    return btoa(binary.join(''));
  }

  /**
   * Convert base64 string to Float32Array for audio playback
   */
  private base64ToFloat32Array(base64String: string): Float32Array {
    const binaryString = window.atob(base64String);
    const bytes = new Uint8Array(binaryString.length);
    for (let i = 0; i < binaryString.length; i++) {
      bytes[i] = binaryString.charCodeAt(i);
    }

    const int16Array = new Int16Array(bytes.buffer);
    const float32Array = new Float32Array(int16Array.length);
    for (let i = 0; i < int16Array.length; i++) {
      float32Array[i] = int16Array[i] / 32768.0;
    }

    return float32Array;
  }

  /**
   * Get the current audio context
   */
  getAudioContext(): AudioContext | null {
    return this.audioContext;
  }

  /**
   * Check if recording is active
   */
  isActive(): boolean {
    return this.isRecording;
  }
}

/**
 * Audio Player class for handling audio playback
 * This is a simplified version that would be expanded in the actual implementation
 */
class AudioPlayer {
  private audioContext: AudioContext | null = null;
  private workletNode: AudioWorkletNode | null = null;
  private initialized: boolean = false;

  async start(): Promise<void> {
    this.audioContext = new AudioContext({ sampleRate: 24000 });

    // Load the audio worklet
    await this.audioContext.audioWorklet.addModule('/audio-player-processor.js');
    this.workletNode = new AudioWorkletNode(this.audioContext, 'audio-player-processor');
    this.workletNode.connect(this.audioContext.destination);

    this.initialized = true;
  }

  playAudio(samples: Float32Array): void {
    if (!this.initialized || !this.workletNode) {
      console.error("AudioPlayer not initialized");
      return;
    }

    this.workletNode.port.postMessage({
      type: "audio",
      audioData: samples,
    });
  }

  stop(): void {
    if (this.audioContext) {
      this.audioContext.close();
    }

    if (this.workletNode) {
      this.workletNode.disconnect();
    }

    this.initialized = false;
    this.audioContext = null;
    this.workletNode = null;
  }
}

Lastly, you will add a conversation manager as your core functionality. The ConversationManager class:

Manages the state of the conversation, including message history and speaking/thinking indicators
Provides methods to update the state and notify listeners
Handles message concatenation when multiple messages come from the same role
Includes a utility to create a React Context for easy integration with React components

Create it under services/conversation/ConversationManager.ts

export interface Message {
  role: string;
  content: string;
  timestamp: number;
}

export interface ConversationState {
  messages: Message[];
  isUserSpeaking: boolean;
  isAssistantThinking: boolean;
  isAssistantSpeaking: boolean;
  isConnected: boolean;
}

/**
 * ConversationManager handles the state of the conversation,
 * including message history and speaking/thinking indicators
 */
export class ConversationManager {
  private state: ConversationState;
  private listeners: ((state: ConversationState) => void)[] = [];

  constructor() {
    // Initialize with default state
    this.state = {
      messages: [],
      isUserSpeaking: false,
      isAssistantThinking: false,
      isAssistantSpeaking: false,
      isConnected: false
    };
  }

  /**
   * Subscribe to state changes
   * @param listener Function to call when state changes
   * @returns Function to unsubscribe
   */
  subscribe(listener: (state: ConversationState) => void): () => void {
    this.listeners.push(listener);

    // Call the listener immediately with current state
    listener({...this.state});

    // Return unsubscribe function
    return () => {
      this.listeners = this.listeners.filter(l => l !== listener);
    };
  }

  /**
   * Notify all listeners of state changes
   */
  private notifyListeners(): void {
    const stateCopy = {...this.state};
    this.listeners.forEach(listener => listener(stateCopy));
  }

  /**
   * Add a new message to the conversation
   * @param role Role of the message sender (USER or ASSISTANT)
   * @param content Content of the message
   */
  addMessage(role: string, content: string): void {
    // Check if the last message is from the same role
    const lastMessage = this.state.messages[this.state.messages.length - 1];

    if (lastMessage && lastMessage.role === role) {
      // Update the last message
      const updatedMessages = [...this.state.messages];
      updatedMessages[updatedMessages.length - 1] = {
        ...lastMessage,
        content: lastMessage.content + " " + content,
        timestamp: Date.now(),
      };

      this.state.messages = updatedMessages;
    } else {
      // Add a new message
      this.state.messages = [
        ...this.state.messages,
        {
          role,
          content,
          timestamp: Date.now(),
        },
      ];
    }

    this.notifyListeners();
  }

  /**
   * Set the user speaking state
   * @param isSpeaking Whether the user is speaking
   */
  setUserSpeaking(isSpeaking: boolean): void {
    this.state.isUserSpeaking = isSpeaking;
    this.notifyListeners();
  }

  /**
   * Set the assistant thinking state
   * @param isThinking Whether the assistant is thinking
   */
  setAssistantThinking(isThinking: boolean): void {
    this.state.isAssistantThinking = isThinking;
    this.notifyListeners();
  }

  /**
   * Set the assistant speaking state
   * @param isSpeaking Whether the assistant is speaking
   */
  setAssistantSpeaking(isSpeaking: boolean): void {
    this.state.isAssistantSpeaking = isSpeaking;
    this.notifyListeners();
  }

  /**
   * Set the connection state
   * @param isConnected Whether the WebSocket is connected
   */
  setConnected(isConnected: boolean): void {
    this.state.isConnected = isConnected;
    this.notifyListeners();
  }

  /**
   * Clear the conversation history
   */
  clearConversation(): void {
    this.state.messages = [];
    this.notifyListeners();
  }

  /**
   * Get the current state
   * @returns Copy of the current state
   */
  getState(): ConversationState {
    return {...this.state};
  }

  /**
   * End the current turn in the conversation
   */
  endTurn(): void {
    // This could be expanded to add metadata to messages
    // or perform other actions when a turn ends
    this.notifyListeners();
  }

  /**
   * Mark the conversation as ended
   */
  endConversation(): void {
    // This could add a system message or perform cleanup
    this.notifyListeners();
  }
}

/**
 * Create a React Context wrapper for the ConversationManager
 * This would be implemented in a separate file in the actual application
 */
export function createConversationContext() {
  const conversationManager = new ConversationManager();

  return {
    useConversation: () => {
      // This would be implemented using React's useState and useEffect
      // to subscribe to the ConversationManager
      return {
        state: conversationManager.getState(),
        addMessage: conversationManager.addMessage.bind(conversationManager),
        setUserSpeaking: conversationManager.setUserSpeaking.bind(conversationManager),
        setAssistantThinking: conversationManager.setAssistantThinking.bind(conversationManager),
        setAssistantSpeaking: conversationManager.setAssistantSpeaking.bind(conversationManager),
        setConnected: conversationManager.setConnected.bind(conversationManager),
        clearConversation: conversationManager.clearConversation.bind(conversationManager),
      };
    }
  };
}

Implementing the Server-side Socket Implementation

To provide a complete Socket.IO integration for both the server and client sides, with proper
context providers for React components to access the socket functionality and conversation state. The code
handles:

Socket.IO server setup with Next.js integration
Client-side socket connection management
Event handling for all the bidirectional communication
React context providers for easy access to socket and conversation state
Proper cleanup and error handling

First create a server.js file with Socket.IO implementation:

const { createServer } = require('http');
const { parse } = require('url');
const next = require('next');
const { Server } = require('socket.io');
const { fromIni } = require('@aws-sdk/credential-providers');
const { BedrockService } = require('./services/bedrock/BedrockService');

const dev = process.env.NODE_ENV !== 'production';
const app = next({ dev });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  const server = createServer((req, res) => {
    const parsedUrl = parse(req.url, true);
    handle(req, res, parsedUrl);
  });

  // Create Socket.IO server
  const io = new Server(server, {
    cors: {
      origin: '*',
      methods: ['GET', 'POST']
    }
  });

  // Create BedrockService instance
  const bedrockService = new BedrockService();

  // Socket.IO connection handler
  io.on('connection', (socket) => {
    console.log('New client connected:', socket.id);

    // Create a unique session ID for this client
    const sessionId = socket.id;

    try {
      // Set up event handlers for this session
      socket.on('promptStart', async () => {
        try {
          console.log('Prompt start received');
          // We'll create the session when system prompt is received
        } catch (error) {
          console.error('Error processing prompt start:', error);
          socket.emit('error', {
            message: 'Error processing prompt start',
            details: error instanceof Error ? error.message : String(error)
          });
        }
      });

      socket.on('systemPrompt', async (data) => {
        try {
          console.log('System prompt received', data);
          await bedrockService.createSession(sessionId, data);

          // Set up event handlers for this session
          bedrockService.registerEventHandler(sessionId, 'contentStart', (data) => {
            console.log('contentStart:', data);
            socket.emit('contentStart', data);
          });

          bedrockService.registerEventHandler(sessionId, 'textOutput', (data) => {
            console.log('Text output:', data.content.substring(0, 50) + '...');
            socket.emit('textOutput', data);
          });

          bedrockService.registerEventHandler(sessionId, 'audioOutput', (data) => {
            console.log('Audio output received, sending to client');
            socket.emit('audioOutput', data);
          });

          bedrockService.registerEventHandler(sessionId, 'error', (data) => {
            console.error('Error in session:', data);
            socket.emit('error', data);
          });

          bedrockService.registerEventHandler(sessionId, 'toolUse', (data) => {
            console.log('Tool use detected:', data.toolName);
            socket.emit('toolUse', data);
          });

          bedrockService.registerEventHandler(sessionId, 'toolResult', (data) => {
            console.log('Tool result received');
            socket.emit('toolResult', data);
          });

          bedrockService.registerEventHandler(sessionId, 'contentEnd', (data) => {
            console.log('Content end received');
            socket.emit('contentEnd', data);
          });

          bedrockService.registerEventHandler(sessionId, 'streamComplete', () => {
            console.log('Stream completed for client:', socket.id);
            socket.emit('streamComplete');
          });

        } catch (error) {
          console.error('Error processing system prompt:', error);
          socket.emit('error', {
            message: 'Error processing system prompt',
            details: error instanceof Error ? error.message : String(error)
          });
        }
      });

      socket.on('audioInput', async (audioData) => {
        try {
          // Convert base64 string to Buffer
          const audioBuffer = typeof audioData === 'string'
            ? Buffer.from(audioData, 'base64')
            : Buffer.from(audioData);

          // Stream the audio
          await bedrockService.streamAudio(sessionId, audioBuffer);
        } catch (error) {
          console.error('Error processing audio:', error);
          socket.emit('error', {
            message: 'Error processing audio',
            details: error instanceof Error ? error.message : String(error)
          });
        }
      });

      socket.on('stopAudio', async () => {
        try {
          console.log('Stop audio requested, beginning proper shutdown sequence');
          await bedrockService.closeSession(sessionId);
        } catch (error) {
          console.error('Error processing streaming end events:', error);
          socket.emit('error', {
            message: 'Error processing streaming end events',
            details: error instanceof Error ? error.message : String(error)
          });
        }
      });

      // Handle disconnection
      socket.on('disconnect', async () => {
        console.log('Client disconnected:', socket.id);
        try {
          await bedrockService.closeSession(sessionId);
        } catch (error) {
          console.error('Error during session cleanup:', error);
        }
      });

    } catch (error) {
      console.error('Error setting up session:', error);
      socket.emit('error', {
        message: 'Failed to initialize session',
        details: error instanceof Error ? error.message : String(error)
      });
      socket.disconnect();
    }
  });

  // Periodically check for and close inactive sessions (every minute)
  setInterval(() => {
    console.log("Session cleanup check");
    const activeSessions = bedrockService.getActiveSessions();
    console.log(`Active sessions: ${activeSessions.length}`);
  }, 60000);

  // Start the server
  const PORT = process.env.PORT || 3000;
  server.listen(PORT, () => {
    console.log(`Server listening on port ${PORT}`);
    console.log(`Open http://localhost:${PORT} in your browser to access the application`);
  });

  // Handle graceful shutdown
  process.on('SIGINT', async () => {
    console.log('Shutting down server...');

    const forceExitTimer = setTimeout(() => {
      console.error('Forcing server shutdown after timeout');
      process.exit(1);
    }, 5000);

    try {
      // First close Socket.IO server
      await new Promise(resolve => io.close(resolve));
      console.log('Socket.IO server closed');

      // Then close all active sessions
      const activeSessions = bedrockService.getActiveSessions();
      console.log(`Closing ${activeSessions.length} active sessions...`);

      await Promise.all(activeSessions.map(async (sessionId) => {
        try {
          await bedrockService.closeSession(sessionId);
          console.log(`Closed session ${sessionId} during shutdown`);
        } catch (error) {
          console.error(`Error closing session ${sessionId} during shutdown:`, error);
        }
      }));

      // Now close the HTTP server
      await new Promise(resolve => server.close(resolve));
      clearTimeout(forceExitTimer);
      console.log('Server shut down');
      process.exit(0);
    } catch (error) {
      console.error('Error during server shutdown:', error);
      process.exit(1);
    }
  });
});

For using the socket and relying on its logic, you can use hooks. Create one under hooks/useSocketIO.ts

'use client';

import { useEffect, useState, useCallback } from 'react';
import { io, Socket } from 'socket.io-client';
import { useConversation } from '@/context/ConversationContext';

export function useSocketIO() {
  const [socket, setSocket] = useState<Socket | null>(null);
  const [isConnected, setIsConnected] = useState(false);
  const [isSessionInitialized, setIsSessionInitialized] = useState(false);
  const { 
    addMessage, 
    setUserSpeaking, 
    setAssistantThinking, 
    setAssistantSpeaking,
    setConnected
  } = useConversation();

  // Initialize socket connection
  useEffect(() => {
    // Create socket connection
    const socketInstance = io({
      path: '/socket.io',
      autoConnect: true,
      reconnection: true,
      reconnectionAttempts: 5,
      reconnectionDelay: 1000,
    });

    // Set up event handlers
    socketInstance.on('connect', () => {
      console.log('Connected to server');
      setIsConnected(true);
      setConnected(true);
    });

    socketInstance.on('disconnect', () => {
      console.log('Disconnected from server');
      setIsConnected(false);
      setConnected(false);
      setIsSessionInitialized(false);
    });

    socketInstance.on('connect_error', (error) => {
      console.error('Connection error:', error);
      setIsConnected(false);
      setConnected(false);
    });

    socketInstance.on('error', (error) => {
      console.error('Socket error:', error);
    });

    socketInstance.on('textOutput', (data) => {
      console.log('Received text output:', data);

      if (data.role === 'USER') {
        // When user text is received, show thinking indicator for assistant response
        setUserSpeaking(false);
        addMessage(data.role, data.content);
        setAssistantThinking(true);
      }
      else if (data.role === 'ASSISTANT') {
        setAssistantThinking(false);
        setAssistantSpeaking(true);
        addMessage(data.role, data.content);
      }
    });

    socketInstance.on('audioOutput', (data) => {
      if (data.content && window.audioPlayer) {
        try {
          window.audioPlayer.playAudio(base64ToFloat32Array(data.content));
        } catch (error) {
          console.error('Error processing audio data:', error);
        }
      }
    });

    socketInstance.on('contentStart', (data) => {
      console.log('Content start received:', data);

      if (data.type === 'AUDIO' && data.role === 'ASSISTANT') {
        setAssistantSpeaking(true);
      }
    });

    socketInstance.on('contentEnd', (data) => {
      console.log('Content end received:', data);

      if (data.type === 'AUDIO' && data.role === 'ASSISTANT') {
        setAssistantSpeaking(false);
      }
    });

    socketInstance.on('streamComplete', () => {
      console.log('Stream completed');
      setUserSpeaking(false);
      setAssistantThinking(false);
      setAssistantSpeaking(false);
    });

    setSocket(socketInstance);

    // Cleanup on unmount
    return () => {
      socketInstance.disconnect();
    };
  }, [addMessage, setUserSpeaking, setAssistantThinking, setAssistantSpeaking, setConnected]);

  // Initialize session with system prompt
  const initializeSession = useCallback(async (systemPrompt: string): Promise<boolean> => {
    if (!socket || !isConnected) {
      console.error('Socket not connected');
      return false;
    }

    try {
      socket.emit('promptStart');
      socket.emit('systemPrompt', systemPrompt);
      setIsSessionInitialized(true);
      return true;
    } catch (error) {
      console.error('Failed to initialize session:', error);
      return false;
    }
  }, [socket, isConnected]);

  // Start streaming audio
  const startStreaming = useCallback(async (): Promise<boolean> => {
    if (!socket || !isConnected || !isSessionInitialized) {
      console.error('Socket not ready or session not initialized');
      return false;
    }

    setUserSpeaking(true);
    return true;
  }, [socket, isConnected, isSessionInitialized, setUserSpeaking]);

  // Stop streaming audio
  const stopStreaming = useCallback(async (): Promise<boolean> => {
    if (!socket || !isConnected) {
      console.error('Socket not connected');
      return false;
    }

    socket.emit('stopAudio');
    setUserSpeaking(false);
    return true;
  }, [socket, isConnected, setUserSpeaking]);

  // Send audio chunk to server
  const sendAudioChunk = useCallback((audioData: string): boolean => {
    if (!socket || !isConnected || !isSessionInitialized) {
      return false;
    }

    socket.emit('audioInput', audioData);
    return true;
  }, [socket, isConnected, isSessionInitialized]);

  // Helper function to convert base64 to Float32Array
  const base64ToFloat32Array = (base64String: string): Float32Array => {
    const binaryString = window.atob(base64String);
    const bytes = new Uint8Array(binaryString.length);
    for (let i = 0; i < binaryString.length; i++) {
      bytes[i] = binaryString.charCodeAt(i);
    }

    const int16Array = new Int16Array(bytes.buffer);
    const float32Array = new Float32Array(int16Array.length);
    for (let i = 0; i < int16Array.length; i++) {
      float32Array[i] = int16Array[i] / 32768.0;
    }

    return float32Array;
  };

  return {
    isConnected,
    isSessionInitialized,
    initializeSession,
    startStreaming,
    stopStreaming,
    sendAudioChunk
  };
}

And, add a context to be passed down to components:

'use client';

import React, { createContext, useContext, ReactNode } from 'react';
import { useSocketIO } from '@/hooks/useSocketIO';

interface SocketContextType {
  isConnected: boolean;
  isSessionInitialized: boolean;
  initializeSession: (systemPrompt: string) => Promise<boolean>;
  startStreaming: () => Promise<boolean>;
  stopStreaming: () => Promise<boolean>;
  sendAudioChunk: (audioData: string) => boolean;
}

const SocketContext = createContext<SocketContextType | undefined>(undefined);

export function SocketProvider({ children }: { children: ReactNode }) {
  const socketIO = useSocketIO();

  return (
    <SocketContext.Provider value={socketIO}>
      {children}
    </SocketContext.Provider>
  );
}

export function useSocket() {
  const context = useContext(SocketContext);
  if (context === undefined) {
    throw new Error('useSocket must be used within a SocketProvider');
  }
  return context;
}

Lastly but not least you will implement the client, it is a long file and you will see it at the very end to not disturb you. Let's see a breakdown:

Following implementation is the bidirectional streaming protocol that enables real-time communication with
Amazon Bedrock:

// Creating the bidirectional stream with AWS Bedrock
public async initiateSession(sessionId: string): Promise<void> {
  try {
    // Set up initial events for this session
    this.setupSessionStartEvent(sessionId);

    // Create the bidirectional stream with session-specific async iterator
    const asyncIterable = this.createSessionAsyncIterable(sessionId);

    // Send the command to AWS Bedrock
    const response = await this.bedrockRuntimeClient.send(
      new InvokeModelWithBidirectionalStreamCommand({
        modelId: "amazon.nova-sonic-v1:0",
        body: asyncIterable,
      })
    );

    // Process responses from AWS Bedrock
    await this.processResponseStream(sessionId, response);
  } catch (error) {
    console.error(`Error in session ${sessionId}:`, error);
    // Error handling and cleanup...
  }
}

Following async iterator is a critical component that enables the bidirectional streaming:

private createSessionAsyncIterable(sessionId: string): AsyncIterable<InvokeModelWithBidirectionalStreamInput> {
  const session = this.activeSessions.get(sessionId);

  return {
    [Symbol.asyncIterator]: () => {
      return {
        next: async (): Promise<IteratorResult<InvokeModelWithBidirectionalStreamInput>> => {
          try {
            // Wait for items in the queue or close signal
            if (session.queue.length === 0) {
              await Promise.race([
                firstValueFrom(session.queueSignal.pipe(take(1))),
                firstValueFrom(session.closeSignal.pipe(take(1))).then(() => {
                  throw new Error("Stream closed");
                }),
              ]);
            }

            // Get next item from the session's queue
            const nextEvent = session.queue.shift();

            return {
              value: {
                chunk: {
                  bytes: new TextEncoder().encode(JSON.stringify(nextEvent)),
                },
              },
              done: false,
            };
          } catch (error) {
            // Handle errors and stream closure
            session.isActive = false;
            return { value: undefined, done: true };
          }
        }
      };
    },
  };
}

This handles audio streaming with a sophisticated buffering mechanism:

// Stream audio for this session
public async streamAudio(audioData: Buffer): Promise<void> {
  // Check queue size to avoid memory issues
  if (this.audioBufferQueue.length >= this.maxQueueSize) {
    // Queue is full, drop oldest chunk
    this.audioBufferQueue.shift();
    console.log("Audio queue full, dropping oldest chunk");
  }

  // Queue the audio chunk for streaming
  this.audioBufferQueue.push(audioData);
  this.processAudioQueue();
}

// Process audio queue for continuous streaming
private async processAudioQueue() {
  if (this.isProcessingAudio || this.audioBufferQueue.length === 0 || !this.isActive)
    return;

  this.isProcessingAudio = true;
  try {
    // Process chunks in batches to avoid overload
    let processedChunks = 0;
    const maxChunksPerBatch = 5;

    while (this.audioBufferQueue.length > 0 && 
           processedChunks < maxChunksPerBatch && 
           this.isActive) {
      const audioChunk = this.audioBufferQueue.shift();
      await this.client.streamAudioChunk(this.sessionId, audioChunk);
      processedChunks++;
    }
  } finally {
    this.isProcessingAudio = false;

    // Schedule next processing if needed
    if (this.audioBufferQueue.length > 0 && this.isActive) {
      setTimeout(() => this.processAudioQueue(), 0);
    }
  }
}

Here the system processes responses from AWS Bedrock and dispatches appropriate events:

private async processResponseStream(sessionId: string, response: any): Promise<void> {
  try {
    for await (const event of response.body) {
      if (event.chunk?.bytes) {
        const textResponse = new TextDecoder().decode(event.chunk.bytes);
        const jsonResponse = JSON.parse(textResponse);

        // Handle different response types
        if (jsonResponse.event?.contentStart) {
          this.dispatchEvent(sessionId, "contentStart", jsonResponse.event.contentStart);
        } else if (jsonResponse.event?.textOutput) {
          this.dispatchEvent(sessionId, "textOutput", jsonResponse.event.textOutput);
        } else if (jsonResponse.event?.audioOutput) {
          this.dispatchEvent(sessionId, "audioOutput", jsonResponse.event.audioOutput);
        } else if (jsonResponse.event?.toolUse) {
          // Handle tool use events
          this.dispatchEvent(sessionId, "toolUse", jsonResponse.event.toolUse);

          // Store tool use information
          session.toolUseContent = jsonResponse.event.toolUse;
          session.toolUseId = jsonResponse.event.toolUse.toolUseId;
          session.toolName = jsonResponse.event.toolUse.toolName;
        }
        // Additional event handling...
      }
    }
  } catch (error) {
    console.error(`Error processing response stream:`, error);
    // Error handling...
  }
}

Here you manage the session's complete lifecycle:

// Create a new streaming session
public createStreamSession(sessionId: string = randomUUID()): StreamSession {
  const session: SessionData = {
    queue: [],
    queueSignal: new Subject<void>(),
    closeSignal: new Subject<void>(),
    responseSubject: new Subject<any>(),
    // Additional session properties...
    isActive: true,
    isPromptStartSent: false,
    isAudioContentStartSent: false,
    audioContentId: randomUUID(),
  };

  this.activeSessions.set(sessionId, session);
  return new StreamSession(sessionId, this);
}

// Properly close a session
public async closeSession(sessionId: string): Promise<void> {
  if (this.sessionCleanupInProgress.has(sessionId)) return;

  this.sessionCleanupInProgress.add(sessionId);
  try {
    await this.sendContentEnd(sessionId);
    await this.sendPromptEnd(sessionId);
    await this.sendSessionEnd(sessionId);
  } catch (error) {
    console.error(`Error during closing sequence:`, error);
  } finally {
    // Ensure cleanup happens even if there's an error
    const session = this.activeSessions.get(sessionId);
    if (session) {
      session.isActive = false;
      this.activeSessions.delete(sessionId);
    }
    this.sessionCleanupInProgress.delete(sessionId);
  }
}

Here you use the flexible event handling system:

// Register an event handler for a session
public registerEventHandler(
  sessionId: string,
  eventType: string,
  handler: (data: any) => void
): void {
  const session = this.activeSessions.get(sessionId);
  if (!session) {
    throw new Error(`Session ${sessionId} not found`);
  }
  session.responseHandlers.set(eventType, handler);
}

// Dispatch events to handlers
private dispatchEvent(sessionId: string, eventType: string, data: any): void {
  const session = this.activeSessions.get(sessionId);
  if (!session) return;

  const handler = session.responseHandlers.get(eventType);
  if (handler) {
    try {
      handler(data);
    } catch (e) {
      console.error(`Error in ${eventType} handler:`, e);
    }
  }

  // Also dispatch to "any" handlers
  const anyHandler = session.responseHandlers.get("any");
  if (anyHandler) {
    anyHandler({ type: eventType, data });
  }
}

Here we process the tool for enhanced functionality:

private async processToolUse(toolName: string): Promise<Object> {
  const tool = toolName.toLowerCase();

  switch (tool) {
    case "gettimetool":
      const pstTime = new Date().toLocaleString("en-US", {
        timeZone: "America/Los_Angeles",
      });
      return {
        timezone: "PST",
        formattedTime: new Date(pstTime).toLocaleTimeString("en-US", {
          hour12: true,
          hour: "2-digit",
          minute: "2-digit",
        }),
      };
    case "getdatetool":
      // Date tool implementation...
    default:
      throw new Error(`Tool ${tool} not supported`);
  }
}

// Send tool result back to the model
private async sendToolResult(sessionId: string, toolUseId: string, result: any): Promise<void> {
  // Tool content start event
  this.addEventToSessionQueue(sessionId, {
    event: {
      contentStart: {
        promptName: session.promptName,
        contentName: contentId,
        interactive: false,
        type: "TOOL",
        toolResultInputConfiguration: {
          toolUseId: toolUseId,
          type: "TEXT",
          textInputConfiguration: {
            mediaType: "text/plain",
          },
        },
      },
    },
  });

  // Tool content input event
  const resultContent = typeof result === "string" ? result : JSON.stringify(result);
  this.addEventToSessionQueue(sessionId, {
    event: {
      toolResult: {
        promptName: session.promptName,
        contentName: contentId,
        content: resultContent,
        role: "TOOL",
      },
    },
  });

  // Tool content end event
  this.addEventToSessionQueue(sessionId, {
    event: {
      contentEnd: {
        promptName: session.promptName,
        contentName: contentId,
      },
    },
  });
}

Conclusion

Amazon Nova Sonic opens up many capabilities for users to implement with its easy to use APIs and capabilities. For starting check out the official documentation and sample apps.

For any questions, please drop it as a comment.

You can find the full file link to client here.

Building a Personalized Quiz Game with Flutter, AWS Amplify Gen2, and Amazon Bedrock!

Salih Guler — Sun, 28 Jan 2024 15:44:55 +0000

From Day 1, Flutter has remained a popular choice for developers aiming to create cross-platform applications. AWS Amplify has long supported the development of applications for iOS, Android, Web, and Desktop.

Previously, AWS Amplify assisted developers in provisioning their backends using the Amplify CLI and Libraries. However, since last November, AWS Amplify announced a new generation of backend development.

This new code-first developer experience empowers developers to quickly build and deploy their backends by utilizing their TypeScript/JavaScript skills for backend development or extending the capabilities of AWS Amplify with their CDK knowledge.

AWS Cloud Development Kit (AWS CDK) accelerates cloud development using common programming languages to model your applications. Constructs—the basic building blocks of AWS Cloud Development Kit (AWS CDK) apps—abstract away the complexity of configuring cloud resources to work with API Gateway, Lambda, and one of the cool kids - Amazon Bedrock.

Amazon Bedrock is a fully managed service that offers a choice of high-performing foundation models (FMs).

In this blog post, you will be building a personalized quiz application that leverages AWS Amplify Gen2 and Amazon Bedrock.

You can also find the source code of the project on GitHub.

This tutorial will make extensive use of Amplify Gen 2. Currently in developer preview, Amplify Gen 2's mobile support is not fully implemented yet. As a result, the code samples and contracts may be subject to change. For the most up-to-date version of the app, please refer to the repository.

Before you get started, ensure that you have the following installed:

Node.js v18.17 or later
npm v9 or later
git v2.14.1 or later
Flutter 3.3.0 or later

Additionally, you will need to create an AWS account. Please note that AWS Amplify is included in the AWS Free Tier. Follow the instructions to configure your AWS account for use with Amplify.

Flutter Side

As with many other applications, your app will serve as the bridge between your data and your user. If you check out the starter project, you will find a basic app as shown below:

The app:

Utilizes Cubit (a simpler version of bloc) for state management. It leverages flutter_bloc and equatable for implementation assistance.
Implements go_router for navigation.
Incorporates google_fonts for custom font implementation and flex_color_scheme for easy theming.

From the project perspective:

QuizCubit manages and caches quiz operations.
QuizState oversees changes in the state.
Each screen (the entire UI) and view (a portion of the UI) is created under the ui folder.

Adding AWS Amplify Gen2 to the project

To add AWS Amplify functionalities to your application, you need to run the following command:

npm create amplify

Afterward, select the base project path and let it do its magic:

? Where should we create your project? (.) # Press enter if you are at your root folder

Once the process is complete, a new folder named amplify will appear in your project. This folder contains TypeScript files that enable you to define and deploy your backend using a minimal yet code-powered approach.

The next step is to build the backend, starting with authentication.

AWS Amplify Gen 2's new file-based structure enables you to create your infrastructure using code.

To add authentication, open the resource.ts file in the auth folder and update it as follows:

import { defineAuth } from '@aws-amplify/backend';

export const auth = defineAuth({
    loginWith: {
        email: true
    },
    userAttributes: {
        preferredUsername: {
            required: true,
        },
    }
});

This configuration allows users to log in using their email or phone number, and you can specify any attributes you want to require.

Now it is time to define your data layer. Ppen the resource.ts file in the data folder and update it as follows:

import {type ClientSchema, a, defineData} from '@aws-amplify/backend';

const schema = a.schema({
    Question: a
        .model({
            title: a.string().required(),
            answer: a.string().required(),
            category: a.string().required(),
            difficulty: a.string().required(),
            options: a.string().array().required(),
            createdAt: a.datetime(),
            updatedAt: a.datetime(),
            result: a.belongsTo("Result"),
        })
        .authorization([a.allow.owner()]),

    Result: a.model({
        score: a.float().required(),
        correctAnswerCount: a.integer().required(),
        answers: a.string().array().required(),
        questions: a.hasMany("Question"),
        createdAt: a.datetime(),
        updatedAt: a.datetime(),
    }).authorization([a.allow.owner()]),
});

export type Schema = ClientSchema<typeof schema>;

export const data = defineData({
    schema,
    authorizationModes: {
        defaultAuthorizationMode: 'userPool'
    }
});

In the code mentioned earlier, you are defining a question object that will be stored in a result object following a quiz. The result object will contain the score, answers, and the number of correct answers, along with the questions.

Now, it's time to test our deployment. In previous versions of AWS Amplify, each iteration on the backend required a deployment. However, with the latest generation, you can now use a CDK-powered local sandbox environment to test and rapidly iterate your backend.

To start the sandbox, run the amplify sandbox command as follows:

npx amplify sandbox --config-format=dart --config-out-dir=lib

This command initiates a sandbox environment and monitors changes in your backend files to start deployment when it is needed.

After deploying the sandbox, it's time to connect the new backend to the Flutter side.

Using AWS Amplify with Flutter

First, add authentication to Flutter using the Amplify UI Authenticator libraries. Start by adding the required libraries:

flutter pub add amplify_authenticator
flutter pub add amplify_auth_cognito
flutter pub add amplify_flutter

Afterwards, update the main.dart file to control the authentication flow:

import 'package:amplify_auth_cognito/amplify_auth_cognito.dart';
import 'package:amplify_authenticator/amplify_authenticator.dart';
import 'package:amplify_flutter/amplify_flutter.dart';
import 'package:flex_color_scheme/flex_color_scheme.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:google_fonts/google_fonts.dart';
import 'package:triv_ai/amplifyconfiguration.dart';
import 'package:triv_ai/quiz/data/quiz_cubit.dart';
import 'package:triv_ai/result/data/results_cubit.dart';
import 'package:triv_ai/routes.dart';

// ignore: depend_on_referenced_packages
import 'package:flutter_web_plugins/url_strategy.dart';

Future<void> main() async {
  usePathUrlStrategy();
  try {
    WidgetsFlutterBinding.ensureInitialized();
    await _configureAmplify();
    runApp(const TrivAIApp());
  } on AmplifyException catch (e) {
    safePrint('Error configuring Amplify: $e');
    runApp(ErrorWidget(e));
  }
}

Future<void> _configureAmplify() async {
  try {
    await Amplify.addPlugins([
      AmplifyAuthCognito(),
    ]);
    await Amplify.configure(amplifyConfig);
    safePrint('Successfully configured');
  } on Exception catch (e) {
    safePrint('Error configuring Amplify: $e');
  }
}

class TrivAIApp extends StatelessWidget {
  const TrivAIApp({super.key});

  @override
  Widget build(BuildContext context) {
    return Authenticator(
      child: MultiBlocProvider(
        providers: [
          BlocProvider(
            create: (context) => QuizCubit(),
          ),
          BlocProvider(
            create: (context) => ResultsCubit(),
          ),
        ],
        child: MaterialApp.router(
          debugShowCheckedModeBanner: false,
          builder: Authenticator.builder(),
          routerDelegate: router.routerDelegate,
          routeInformationParser: router.routeInformationParser,
          routeInformationProvider: router.routeInformationProvider,
          theme: FlexThemeData.light(
            scheme: FlexScheme.blueWhale,
            fontFamily: GoogleFonts.kanit().fontFamily,
          ),
          darkTheme: FlexThemeData.dark(
            scheme: FlexScheme.blueWhale,
            fontFamily: GoogleFonts.kanit().fontFamily,
          ),
        ),
      ),
    );
  }
}

and update the signOut function like the following:

void signOut() {
  Amplify.Auth.signOut();
}

Three important points to mention:

_configureAmplify gets the Amplify configurations and enables them for the app before it starts.
The Authenticator widget controls the entire authentication flow with the contract you decided.
You can also call the authentication libraries when you need them. In the app, we are calling the signOut function.

Now, if you run the application, you should see the authentication flow in action.

The second step involves adding the GraphQL API to the Flutter project. Before integrating Flutter libraries, we need to generate model classes based on our earlier API contract. To do this, run the following command:

npx amplify generate graphql-client-code --format=modelgen --model-target=dart --out=lib/models

This command generates the model classes in Dart, located in the lib/models folder. Next, it's time to add the necessary libraries. Execute the following command:

flutter pub add amplify_api

Then, update the _configureAmplify function by incorporating the API category into the configuration, as shown below:

Future<void> _configureAmplify() async {
  try {
    await Amplify.addPlugins([
      AmplifyAuthCognito(),
      AmplifyAPI(modelProvider: ModelProvider.instance)
    ]);
    await Amplify.configure(amplifyConfig);
    safePrint('Successfully configured');
  } on Exception catch (e) {
    safePrint('Error configuring Amplify: $e');
  }
}

With these changes, we've added the API category and the models to be used in the application.

Now, it's time to introduce the exciting feature: AI.

Adding Amazon Bedrock to the Project Backend

Amazon Bedrock is not supported by AWS Amplify Gen 2. However, thanks to the new approach powered by CDK, we can create a backend property to deliver any cloud resource we would like to have.

The first step is to go back to our amplify folder and create a new folder called custom, which will hold our custom operations. You can split the custom connections into different folders. In this example, you will create a new BedrockConnection folder.

Like the other parts of the backend, you will create a new resource.ts file for your cloud operations. Paste the following code into the resource.ts file:

import { Construct } from "constructs/lib/construct.js";
import { Runtime } from "aws-cdk-lib/aws-lambda";
import { LambdaIntegration, RestApi } from "aws-cdk-lib/aws-apigateway";
import { CfnOutput, Duration } from "aws-cdk-lib";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import * as url from "node:url";

export class BedrockConnection extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // Create Lambda function
    const quizFunction = new NodejsFunction(this, "generateQuiz", {
      entry: url.fileURLToPath(new URL("index.ts", import.meta.url)),
      runtime: Runtime.NODEJS_LATEST,
      handler: "index.handler",
      timeout: Duration.minutes(15),
    });

    // Create API Gateway
    const api = new RestApi(this, "QuizApi");

    // Add resource and method to the API Gateway
    const generateQuizResource = api.root.addResource("generateQuiz");
    const integration = new LambdaIntegration(quizFunction);
    generateQuizResource.addMethod("GET", integration);

    // Output the API Gateway endpoint URL
    new CfnOutput(this, "ApiEndpoint", {
      value: api.url,
      description: "Endpoint for the Quiz API",
    });
  }
}

This code sets up a CDK construct that creates an API using Amazon API Gateway and AWS Lambda.

A NodejsFunction is defined to host the Lambda function. The entry point is set to an index.ts file, with a 15-minute timeout.

A RestApi is constructed to define the API Gateway endpoint. The Lambda function is attached to the root resource "/generateQuiz" via a LambdaIntegration.

Finally, a CloudFormation Output is added to surface the API endpoint URL for easy access after deployment.

This setup allows hosting a serverless REST API where the Lambda function can be invoked via the API Gateway. The CDK makes it easy to define the infrastructure as code.

Next, we will create the index.ts file for the handler to perform the operation.

import { Handler } from "aws-cdk-lib/aws-lambda";
import { generateQuiz } from "./prompt.js";

export const handler: Handler = async (event: {
  queryStringParameters: {
    questionCount: String;
    categoryList: String;
    difficulty: String;
  };
}) => {
  const { questionCount, categoryList, difficulty } =
    event.queryStringParameters;

  const result = await generateQuiz(questionCount, categoryList, difficulty);
  return {
    headers: {'Content-Type': 'application/json'},
    statusCode: 200,
    body: JSON.stringify({ message: result }),
  };
}

This code generates a quiz by calling the generateQuiz function from the ./prompt.js file.

It defines a Lambda handler function that is invoked when the Lambda is triggered. The handler accepts an event parameter containing query string parameters: questionCount, categoryList, and difficulty.

These parameters are extracted from the event and passed to the generateQuiz function, which uses them to generate a quiz.

The handler then returns a JSON response with a status code of 200. It sets the 'Content-Type' header and stringifies an object with a "message" property containing the result from generateQuiz.

This setup allows the Lambda to be triggered with query parameters to dynamically generate a quiz and returns the result as JSON, which can be consumed by a client application.

The next step is to create a prompt.ts file to call Amazon Bedrock with the correct prompt and information.

import {
  BedrockRuntimeClient,
  InvokeModelCommand,
} from "@aws-sdk/client-bedrock-runtime";

const client = new BedrockRuntimeClient({
  region: "eu-central-1",
});

export const generateQuiz = async (
  questionCount: String,
  categoryList: String,
  difficulty: String
) => {
  const promptText = `
  \n\nHuman:
  You are a quiz question generator.

  Create exactly ${questionCount} questions, evenly distributed across the following categories: ${categoryList}. Ensure the questions align with ${difficulty} difficulty level.

  Requirements for each question:
  - Return the result as a list of JSON objects. 
  - Return the question with json key 'question'.
  - Include 4 different answer options, with json key 'options', each a string.
  - Specify 1 correct answer, with json key 'correctAnswer', in string format.
  - Return the category with json key 'category'.
  - Questions should not be repeated.
  \n\nAssistant:
`;


  const input = {
    modelId: "anthropic.claude-v2",
    contentType: "application/json",
    accept: "application/json",
    body: JSON.stringify({
      prompt: promptText,
      max_tokens_to_sample: 8192,
    }),
  };
  const command = new InvokeModelCommand(input);
  const response = await client.send(command);

  return JSON.parse(Buffer.from(response.body).toString("utf-8"));
};

Lastly, we will connect this CDK construct to our backend. Open the backend.ts file and update it as follows:

import { defineBackend } from "@aws-amplify/backend";
import { auth } from "./auth/resource.js";
import { data } from "./data/resource.js";
import { BedrockConnection } from "./custom/BedrockConnection/resource.js";

const backend = defineBackend({
  auth,
  data,
});

new BedrockConnection(
  backend.createStack('BedrockConnection'),
  'BedrockConnection',
);

This integration allows you to include a custom resource in the Amplify backend. The auth and data resources provide standard functionalities, while BedrockConnection introduces additional custom logic.

Writing all this code will prepare the backend for operations. However, proper IAM policies are required to execute prompts on Amazon Bedrock.

The first step is to add the Amazon Bedrock policies. Navigate to the AWS Console and access IAM. Locate your current user and open the details:

Attach a new policy by clicking the "Add Permissions" button. Search for the Bedrock policies and attach them, either as a package or individually.

Lambda will create a role to manage the resources. You can either create your own role and attach it, or update the attached role with the necessary permissions.

With our current setup, we can attach a role via the AWS Console. Open the AWS Console and navigate to the IAM page. Then, click on Roles and find the related role by searching for the "BedrockConnection" Lambda.

Next, add the Amazon Bedrock permission to the Role in the same way you did for your IAM user.

Your sandbox environment is now ready for using Amazon Bedrock.

Connecting to the API from Flutter

We have two distinct sets of APIs. The first is the GraphQL API, which handles results and questions. The second is the Rest API, serving as our gateway to Amazon Bedrock.

First, let's explore how to call Amazon Bedrock from our Flutter application.

Initially, we need to add the HTTP package to call our API. Run the following command to add the HTTP package:

flutter pub add http

Next, we will replace the question object created under question/data/question.dart and result object under result/data/result.dart with the generated one.

We will import the correct Question object into QuestionView and update the QuizCubit as follows to generate questions:

import 'dart:convert';

import 'package:amplify_api/amplify_api.dart';
import 'package:amplify_flutter/amplify_flutter.dart';
import 'package:bloc/bloc.dart';
import 'package:equatable/equatable.dart';
import 'package:triv_ai/models/ModelProvider.dart';
import 'package:http/http.dart' as http;

part 'quiz_state.dart';

class QuizCubit extends Cubit<QuizState> {
  QuizCubit() : super(QuizInitial());

  final _answers = <String>[];

  Future<void> generateQuestions(
    int questionCount,
    List<String> categories,
    String difficulty,
  ) async {
    emit(QuizLoading());
    final url = Uri.https(
      '<API-ID>.execute-api.<REGION>.amazonaws.com',
      'prod/generateQuiz',
      {
        "questionCount": questionCount.toString(),
        "categoryList": categories.join(","),
        "difficulty": difficulty,
      },
    );
    try {
      final response = await http.get(
        url,
        headers: {
          "Access-Control-Allow-Origin": "*",
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
      );
      final content = json.decode(response.body);
      final outputText = content["message"]["completion"] as String;
      final firstIndex = outputText.indexOf("[");
      final lastIndex = outputText.lastIndexOf("]");
      final chopped = outputText.substring(firstIndex, lastIndex + 1);
      final jsonToParse = json.decode(chopped) as List<dynamic>;
      final questions = <Question>[];
      for (final parsedElement in jsonToParse) {
        final optionsDynamic = parsedElement['options'] as List<dynamic>;
        final options = optionsDynamic.cast<String>();
        questions.add(
          Question(
            title: parsedElement['question'] as String,
            answer: parsedElement['correctAnswer'] as String,
            category: parsedElement['category'] as String,
            difficulty: difficulty,
            options: options,
            createdAt: TemporalDateTime(DateTime.now()),
            updatedAt: TemporalDateTime(DateTime.now()),
          ),
        );
        emit(QuizSuccess(questions, questions.first, 0));
      }
    } on Exception catch (e) {
      emit(QuizError('Could not fetch the questions: \n\n$e'));
    }
  }

  void fetchQuestions() {
    if (state is QuizSuccess) {
      emit(
        QuizSuccess(
          (state as QuizSuccess).questions,
          (state as QuizSuccess).currentQuestion,
          (state as QuizSuccess).currentQuestionIndex,
        ),
      );
    } else {
      emit(const QuizError('Quiz not found'));
    }
  }

  Future<void> changeQuestion(String selectedOption) async {
    _answers.add(selectedOption);
    if (state is QuizSuccess) {
      final questions = (state as QuizSuccess).questions;
      final currentQuestionIndex = (state as QuizSuccess).currentQuestionIndex;
      if (currentQuestionIndex < questions.length - 1) {
        emit(
          QuizSuccess(
            questions,
            questions[currentQuestionIndex + 1],
            currentQuestionIndex + 1,
          ),
        );
      } else {
        final score = _calculateScore(questions, _answers);
        emit(
          QuizFinishedState(
            questions,
            _answers,
            score,
          ),
        );
      }
    } else {
      emit(const QuizError('Quiz not found'));
    }
  }

  double _calculateScore(List<Question> questions, List<String> answers) {
    final scorePerQuestion = 100 / questions.length;
    var score = 0.0;
    for (var i = 0; i < questions.length; i++) {
      if (questions[i].answer == answers[i]) {
        score += scorePerQuestion;
      }
    }
    return score;
  }

  void resetQuiz() {
    emit(QuizInitial());
    _answers.clear();
  }

  Future<void> saveQuiz() async {
     emit(QuizSaved());
  }
}

It generates questions by making a network request to an AWS API Gateway endpoint, parsing the JSON response, and mapping it to Question model objects.
The state contains the current list of questions, the current question being displayed, and the index of that question.
Methods like changeQuestion and fetchQuestions update the state by moving to the next question or re-emitting the current state.
changeQuestion also tracks the user's answers in a list and calculates a score when all questions are answered by comparing answers to the correct answers.
The resetQuiz method resets the state and clears the answers, allowing the quiz to be restarted.

Now, deploy your API with API Gateway. Open API Gateway from the console. Open the Quiz API and click the Deploy API button to deploy it to any stage of your choice. Afterwards, it will take you to the Stages. There, you can see your base URL and deployed environment.

If you run the application now, you will see the following:

The next step is to use the GraphQL API to save the results and view them when needed.

Navigate to your quiz_cubit.dart file and update it as follows:

Future<void> saveQuiz() async {
  if (state is QuizFinishedState) {
    final currentState = (state as QuizFinishedState);
    final questions = currentState.questions;
    final answers = currentState.answers;
    final score = currentState.score;
    int correctAnswerCount = 0;
    for (var i = 0; i < questions.length; i++) {
      if (questions[i].answer == answers[i]) {
        correctAnswerCount++;
      }
    }
    emit(QuizLoading());
    final result = Result(
      score: score,
      correctAnswerCount: correctAnswerCount,
      answers: answers,
    );
    final mutation = ModelMutations.create(result);
    try {
      final response = await Amplify.API.mutate(request: mutation).response;
      for (final question in currentState.questions) {
        final questionMutation = ModelMutations.create(
          question.copyWith(
            resultQuestionsId: result.id,
            updatedAt: TemporalDateTime(DateTime.now()),
          ),
        );
        final questionResult =
            await Amplify.API.mutate(request: questionMutation).response;
        if (questionResult.hasErrors) {
          throw Exception(questionResult.errors.toString());
        }
      }
      if (response.hasErrors) {
        emit(QuizError(response.errors.toString()));
      } else {
        emit(QuizSaved());
        resetQuiz();
      }
    } on Exception catch (e) {
      emit(QuizError(e.toString()));
    }
  }
}

The code above:

It first checks that the current state is a QuizFinishedState, meaning the user has completed the quiz. It then extracts the questions, answers, and score from that state.
It loops through the questions and answers to count the number of correct answers.
It emits a loading state to indicate the save is in progress.
It creates a Result object with the score, correct count, and answers to save to the database.
It uses the Amplify API to mutate (create/save) the Result object.
It then loops through each question again, updating the question objects with the new result ID and timestamp. It mutates each question to the database.
If any errors occur during the API calls, it emits an error state with the error message.
If everything saves successfully, it emits a saved state and resets the quiz data before the user can start a new one.

Following that, the next step is to read the saved result information. To do this, open the results_cubit.dart file and update the getResults function as follows:

  Future<void> getResults() async {
    emit(ResultsLoading());
    try {
      const graphQLDocument = '''
query ListResults {
  listResults {
    items {
      id
      answers
      correctAnswerCount
      score
      questions {
        items {
          id
          answer
          category
          difficulty
          options
          title
          updatedAt
        }
      }
    }
  }
}
    ''';
      final getResultRequest = GraphQLRequest<String>(
        document: graphQLDocument,
      );
      final response =
          await Amplify.API.query(request: getResultRequest).response;

      if (response.hasErrors || response.data == null) {
        emit(ResultsError(response.errors.toString()));
      } else {
        final rawResults = response.data;
        final parsedResults = json.decode(rawResults!) as Map<String, dynamic>;
        final results = (parsedResults['listResults']['items'] as List<dynamic>)
            .cast<Map<String, dynamic>>()
            .map(
              (e) => Result(
                id: e['id'] as String,
                answers: (e['answers'] as List<dynamic>).cast<String>(),
                correctAnswerCount: e['correctAnswerCount'] as int,
                score: e['score'] as double,
                questions: (e['questions']['items'] as List<dynamic>)
                    .cast<Map<String, dynamic>>()
                    .map(
                      (e) => Question(
                        id: e['id'] as String,
                        answer: e['answer'] as String,
                        category: e['category'] as String,
                        difficulty: e['difficulty'] as String,
                        options: (e['options'] as List<dynamic>).cast<String>(),
                        title: e['title'] as String,
                        updatedAt: TemporalDateTime.fromString(
                            e['updatedAt'] as String),
                      ),
                    )
                    .toList(growable: false)
                  ..sort(
                    (a, b) => a.updatedAt!
                        .getDateTimeInUtc()
                        .compareTo(b.updatedAt!.getDateTimeInUtc()),
                  ),
              ),
            )
            .toList(growable: false);
        emit(ResultsSuccess(results));
      }
    } on Exception catch (e) {
      emit(ResultsError(e.toString()));
    }
  }

Here's an explanation of what the code does:

It defines the GraphQL query document as a multi-line string. This queries for a list of results with associated questions.
It creates a GraphQLRequest object using this document to make the API request.
It calls the Amplify API to execute the query and get a response.
It checks for errors in the response. If errors exist, it emits a error state.
If no errors, it parses the JSON response data into Dart objects.
It maps over the result items to create Result objects with associated Question objects.
It sorts the questions by their updatedAt date.
If successful, it emits a success state with the list of results.
Catches any exceptions and emits an error state.

With this, the app is now feature complete.

Deploying Resources with Amplify Gen 2

Amplify Gen 2 provides a git-branch-based deployment strategy. To begin the deployment process, publish your project on a Git provider website, such as GitHub.

Be sure to close your sandbox environment before starting the deployment process.

First, go to the AWS Amplify console. Click on the Try Amplify Gen 2 button. If it is not available, click on the New App button.

Next, select Option 2: Start with an existing app to add your application. This will present you with several options to guide you on where to start and where to publish. Choose GitHub or any other option that suits you.

Authenticate with the Git provider and select your repository and branch.

Once it verifies that it is a Gen 2 project, select everything and start the deployment process. Once it is deployed, you are ready.

You need to go through the "add permission" and "deploy your API" steps from the previous instructions again.

After the application is deployed, it is time to regenerate the configuration files for the project.

To do that, run the following command. This command is used to generate configuration information after deployment:

npx amplify generate config --app-id=<app-id> --branch=main --format=dart --out-dir=lib

If you run the application now, you will see that everything is working as expected.

Conclusion

When app developers work on applications, they always consider the backend as a source of information or authentication. However, the cloud can help you achieve goals where the only limit will be your imagination.

Thanks to Amplify Gen2, simple tasks will remain simple, and complicated tasks will become simpler.

Go ahead, check out Amplify Gen2, and let us know what you think about it.

If you have any questions, feel free to ask them on LinkedIn and Twitter.