DEV Community: Salih Guler

Making my personal website callable for AI agents with WebMCP

Salih Guler — Tue, 20 Oct 2026 08:17:31 +0000

The first time someone mentioned WebMCP to me, I assumed it was a diagnostics tool for web apps. The name sounds like something you would open next to the network tab. My second guess was worse: I thought maybe it was a Playwright alternative. Luckily, I was wrong both times, and figuring out why is how I ended up adding it to salih.dev (where probably nobody would use).

A few months ago I wrote about building an agent-friendly personal website with specs. The site serves Markdown to agents, has an llms.txt, and answers a set of .well-known discovery files. One of those files was /.well-known/webmcp.json, and it said, politely, that there were no browser tools here. In case you don't know me, I am a very open person, if I don't have something, I would say "I don't have it". But I also don't take "No" for an answer, even to myself. So let's see how I added this very useful set of features on a not very useful scenario for the sake of learning.

The code is in the salih-dev repository: the tools are in PR #15, and the speaker kit and discovery changes are in PR #16.

What is WebMCP?

WebMCP is a proposed web standard from the W3C Web Machine Learning Community Group, written by people from Microsoft and Google. It lets a web page declare tools that an AI agent running in the browser can call. The page registers each tool with a name, a description, a JSON schema for its input and a function that runs it:

document.modelContext.registerTool({
  name: "list_events",
  description: "List the conferences where Salih speaks...",
  inputSchema: { type: "object", properties: { when: { type: "string" } } },
  execute: async (input) => { /* return the answer */ },
});

The "MCP" is the same Model Context Protocol you may already run on a server. The difference is where it lives. A server MCP exposes tools from a backend. WebMCP exposes tools from the page the user has open, with the user's session and the page's state.

The tools I added

My site has three kinds of content an agent might care about: blog posts, past talks and upcoming events. I wrote eight tools around them:

Tool	What it answers
`get_site_overview`	Where I am right now, content counts, my next event, the latest post, and the filter values the other tools accept
`search_site`	Full-text search across posts, talks and events
`list_blog_posts`	Posts filtered by tag, category or text
`read_blog_post`	The full Markdown of one post
`list_talks`	Past talks by topic, event type, year, or whether a recording exists
`list_events`	Upcoming, past or all events
`get_speaker_kit`	My bio, the topics I speak on, recent talks, where I am already booked, and how to reach me
`show_talks_on_page`	Applies a filter on the Talks page so the visitor sees it too

The first seven are read-only and registered on every page. The last one only exists on /talks/, and it is the one I like most. It presses the page's real filter button, so the person watching sees the same list the agent is describing. The page's own controller stays in charge of the state, including its aria-pressed attributes.

I kept everything read-only on purpose. There is a comment form on the site, and I thought about exposing it. An agent posting comments on my behalf is a decision I want to make separately, after I have watched how agents use the read tools.

Step 1: Bake an index at build time

The tools need data, and I did not want them scraping my own HTML. The site is built with Astro, so I added a static endpoint that writes everything the tools need into one JSON file.

Create it under src/pages/api/webmcp-index.json.ts:

export const GET: APIRoute = async () => {
  const [posts, talks] = await Promise.all([
    getPublishedPosts(),
    getPublishedTalksSnapshot(),
  ]);

  return jsonResponse(
    buildSiteIndex({
      siteName: site.name,
      siteUrl: site.url,
      posts,
      talkCards: projectTalkArchive(talks).cards,
      siteContent: getSiteContent(),
    }),
    { headers: { "Cache-Control": "public, max-age=300" } },
  );
};

It reads the same published posts and talks the pages use, so the tools never disagree with what a human sees.
buildSiteIndex flattens them into a small shape with titles, URLs, dates, tags and snippets.
The file is static. My content API starts the publisher build after every write, and that build regenerates the file, so there is no extra Lambda to run.

One detail took me a moment. Events move from "upcoming" to "past" on their own, and a baked file does not know what day it is. So the index stores dates, and the tools decide upcoming or past in the browser against the visitor's clock. An event that ended yesterday shows as past even if I have not rebuilt the site since.

Step 2: Register the tools only when the browser supports them

Most visitors use a browser without WebMCP, and I wanted them to see zero difference. The entry point checks for document.modelContext and returns if it is missing.

Add it to src/lib/webmcp/register-tools.ts:

export async function registerWebMcpTools(): Promise<void> {
  const context = document.modelContext;
  if (context === undefined) return;

  try {
    await registerContentTools(context);
    await registerTalksPageTool(context);
  } catch (error: unknown) {
    // A registration failure must never break the page for the human visitor.
    console.warn("WebMCP tool registration failed", error);
  }
}

Then load it from a component with no markup, src/components/WebMcpTools.astro, and add that component to the base layout:

<script>
  import { registerWebMcpTools } from "../lib/webmcp/register-tools";

  void registerWebMcpTools();
</script>

For types I used the webmcp-types package, pinned to 0.1.10, and referenced it from src/env.d.ts. That gives you WebMCP.ModelContext and the registerTool signature without writing your own copy of the API.

Step 3: Write descriptions for a model, and check every input

A tool description is a prompt. The agent reads it to decide whether to call the tool and what to pass. I wrote mine the way I would brief a colleague, including the defaults and the order of results:

description:
  "List the conferences and events where Salih Güler speaks or runs workshops. 'upcoming' (the default) lists events that have not ended yet, soonest first; 'past' lists finished events, most recent first; 'all' lists both.",

get_site_overview returns the exact tag, category and topic values the other tools accept, and its description tells the agent to call it first when it is unsure. That one line saves a lot of failed filter calls.

The spec does not promise that the browser validates input against your schema. So every execute function checks its input again before using it:

const query = optionalString(input.query);
if (query === undefined) throw new Error("query must be a non-empty string");

The search and filter logic lives in src/lib/webmcp/queries.ts as pure functions, which made it easy to test without a browser. There are 12 tests for it, covering search ranking, filters, the upcoming and past split, post lookup and the speaker kit.

Step 4: Add a speaker kit

The first version answered questions about my content. Then I thought about who actually looks me up. Most of the time it is an event organizer deciding whether to invite me, and they want a bio, the topics I cover, proof that I can give a talk, and a way to reach me. Before, an agent had to stitch that together from four tool calls and the About page.

So the index got a speaker block, built from the same src/config/site.ts that renders my About and Contact pages:

speaker: {
  role: input.speaker.role,
  bio: input.speaker.bioShort,
  longBio: [...input.speaker.bioLong],
  focusAreas: [...input.speaker.focusAreas],
  aboutUrl: absolute("/about/"),
  contactUrl: absolute("/contact/"),
  profiles: input.speaker.socials.map((social) => ({
    label: social.label,
    url: social.href,
  })),
},

And src/lib/webmcp/queries.ts got a speakerKit function that combines it with the talks and events. It counts how many talks I have given per topic, so the agent sees what I talk about most:

const topicCounts = new Map<string, { topic: string; talks: number; order: number }>();
for (const talk of index.talks) {
  for (const topic of talk.topics) {
    const key = normalize(topic);
    if (key.length === 0) continue;
    const entry = topicCounts.get(key);
    if (entry) entry.talks += 1;
    else topicCounts.set(key, { topic, talks: 1, order: topicCounts.size });
  }
}

The function returns the topics sorted by talk count, my five most recent talks with slides and recordings, the next five events I am booked for, and the contact routes. My site lists no email address, so the kit says that directly and points to the profiles on the contact page. An agent should not invent an address because the field looked empty.

Registering it looks like the other tools. The description names the situations where an agent should pick it:

await context.registerTool({
  name: "get_speaker_kit",
  title: "Speaker kit",
  description:
    "Get what an event organizer needs to invite Salih Güler as a speaker: his role and bio, focus areas, the topics he has spoken on with talk counts, his most recent talks with slide and recording URLs, the events he is already booked for, and how to contact him. Use this when someone wants to invite him, check his availability, or write a speaker introduction.",
  inputSchema: { type: "object", properties: {} },
  annotations: readOnly,
  execute: async (_input, { signal }) => speakerKit(await loadIndex(signal), today()),
});

Adding the speaker block changed the index shape, so I bumped its version from 1 to 2.

Step 5: Tell the humans too

The tools are invisible to a person reading the site. If someone finds this post and opens salih.dev, nothing on the page says what to ask. So the About page has a new section, "Use this site with an AI agent", with example prompts and the console check from the "Try it yourself" section below.

The About page also has a Markdown version for agents, and I did not want the two to drift apart. Both now render from one small module, src/lib/webmcp/visitor-guide.ts:

export const AGENT_GUIDE = {
  heading: "Use this site with an AI agent",
  promptsLead: "Some questions to try:",
  prompts: [
    "Where is Salih speaking next, and what has he talked about before?",
    "Find Salih's posts about AWS Amplify and summarize the newest one.",
    "Which of Salih's talks have a recording?",
    "Get Salih's speaker kit so I can invite him to our meetup.",
  ],
  // intro text, the Chrome flag, and the console call are here too
} as const;

about.astro maps over it for the HTML, and the Markdown serializer builds the same section from it.

Try it yourself

You can call the tools on salih.dev today. You need Chrome 150 or newer.

From the Chrome console

Open chrome://flags/#enable-webmcp-testing, set WebMCP for testing to Enabled, and relaunch Chrome.
Open salih.dev, then open DevTools and go to the Console.
List the tools and call one:

const tools = await document.modelContext.getTools();
tools.map((tool) => tool.name);

const kit = tools.find((tool) => tool.name === "get_speaker_kit");
await document.modelContext.executeTool(kit, {});

const search = tools.find((tool) => tool.name === "search_site");
await document.modelContext.executeTool(search, { query: "agents" });

You should see seven tools on most pages and eight on /talks/. If document.modelContext is undefined, the flag is not on yet. Some Chrome builds expect the input as a JSON string, so if executeTool complains, pass JSON.stringify({ query: "agents" }) instead.

On the Talks page, run show_talks_on_page with { filter: "All talks" } or one of the topic labels and watch the filter buttons on the page change.

With the MCP Inspector

If you want to see the calls before you hand them to an agent, use the MCP Inspector. It is the reference tool for testing MCP servers, and it can start Chrome DevTools MCP for you with the same flags as above:

npx @modelcontextprotocol/inspector \
  npx chrome-devtools-mcp@latest \
  --categoryExperimentalWebmcp \
  --chromeArg=--enable-features=WebMCP

It prints a URL with a one-time token, so open that URL rather than typing localhost:6274 yourself. Turn on the switch next to the server to connect, then switch to Tools. You are now doing by hand what Claude Code and Codex did on their own:

Run new_page with https://salih.dev/talks/ as the url. Chrome opens the page, and the result lists its page ID.
Run list_webmcp_tools with that pageId. You get all eight tools with their descriptions and input schemas, exactly as an agent receives them.
Run execute_webmcp_tool with the pageId, a toolName and the input as a JSON string, for example get_speaker_kit and {}.

Step 2 is the useful one when you write your own tools. You read each description the way the model reads it, flattened into one long block with its schema, so a description that only makes sense next to your page is easy to spot. The Protocol tab on the right shows the raw JSON-RPC for every call if you need to see exactly what was sent.

Every tool in the list has a small warning triangle. That is the Inspector's schema portability check on Chrome DevTools MCP's own schemas, not on my tools, and the calls work anyway.

From Claude Code, Codex or Kiro CLI

Claude Code, Codex and Kiro CLI run in a terminal, not in a browser tab, so they cannot see document.modelContext on their own. The bridge is Chrome DevTools MCP, Google's MCP server that gives a coding agent a real Chrome. It has an experimental WebMCP category with two tools: list_webmcp_tools lists what a page registers, and execute_webmcp_tool calls one of them with JSON input.

The category is off by default. You need two flags: --categoryExperimentalWebmcp turns on the two tools, and --chromeArg=--enable-features=WebMCP turns on WebMCP in the Chrome that the server starts. That Chrome uses its own profile, so the flag you set in chrome://flags does not carry over.

For Claude Code:

claude mcp add chrome-devtools --scope user -- \
  npx chrome-devtools-mcp@latest \
  --categoryExperimentalWebmcp \
  --chromeArg=--enable-features=WebMCP

For Codex:

codex mcp add chrome-devtools -- \
  npx chrome-devtools-mcp@latest \
  --categoryExperimentalWebmcp \
  --chromeArg=--enable-features=WebMCP

If you prefer editing ~/.codex/config.toml directly, this is the same server:

[mcp_servers.chrome-devtools]
command = "npx"
args = [
  "chrome-devtools-mcp@latest",
  "--categoryExperimentalWebmcp",
  "--chromeArg=--enable-features=WebMCP",
]

For Kiro CLI:

kiro-cli mcp add --name chrome-devtools --scope global \
  --command npx \
  --args '["chrome-devtools-mcp@latest","--categoryExperimentalWebmcp","--chromeArg=--enable-features=WebMCP"]'

That writes the server to ~/.kiro/settings/mcp.json. Use --scope workspace instead if you only want it in one project, in that project's .kiro/settings/mcp.json.

Restart the agent and ask it something about the site. I gave Codex this prompt:

Open https://salih.dev/ in the browser. Use the page's WebMCP tools to answer:
where is Salih speaking next, and which topics has he given talks on?
Then say which WebMCP tools you called. Do not read the page HTML.

It called list_webmcp_tools, then execute_webmcp_tool three times with get_site_overview, list_events and list_talks. The answer had CityJS Athens on 21 to 23 October as my next event, the two events after it, and the topics from both talks. It did not read the page HTML once.

I gave Codex a speaker question instead, and it went straight to get_speaker_kit after listing the tools. That one call was enough for my bio, focus areas and contact routes. It also repeated the kit's note that the site has no email address, which is the line I added so an agent would not make one up. One small lesson from that run: I asked for "three focus areas", the kit has four, and Codex merged two of them to match my number. The agent trusted my prompt over the data.

With Kiro CLI I asked which talks I have given and whether any of them has a recording. It opened the page, called list_webmcp_tools, and then made a single execute_webmcp_tool call with list_talks. The answer had both talks with their events and dates, and it said neither has a recording because videoUrl is empty for both. Kiro CLI asks before it runs each tool, so every one of those calls went through an approval prompt first.

Two things to know before you try this:

Chrome DevTools MCP can read and change anything in the browser it controls. The server prints that warning on start, and it is right. Use it on sites you trust, and keep it away from tabs with accounts you care about.
The site cannot see who is calling its tools or ask the visitor for permission. Your agent's own approval prompts are the only check, so read what it wants to call before you allow it. My tools only read, so it does not matter much here. It would matter on a site with a checkout tool.

Chrome's Debug WebMCP tools with AI agents page shows the same setup from the author's side: asking your coding agent to check that your own tools register and that their schemas are clear enough for a model.

With other agents

If your agent runs inside a browser that supports WebMCP, ask it one of the questions from my About page, for example "Where is Salih speaking next, and what has he talked about before?", and check which tools it calls.

An agent without a browser still gets the same answers. Point it at llms.txt. It lists the tools and links /api/webmcp-index.json, the data the tools read.

Resources

7 Tips to Make Your AI Agent More Predictable

Salih Guler — Tue, 11 Aug 2026 10:20:35 +0000

After months of building with AI coding tools, I found the difference between generated code that works and generated code that ships comes down to how you communicate with the AI. I have been sharing these lessons in a talk called "It's Dangerous to Code Alone! Take This: Developer's AI Survival Guide" and people keep asking me to write them down. How big is the gap? An MIT study across 100,000+ developers found that AI agents boosted code written by ~180%, while code that actually shipped to production rose by only ~30%.

To demonstrate these tips, I built a link-sharing platform so my teammates can share resources without juggling multiple QR codes. I generated the frontend with Codex GPT 5.6 Sol and Figma MCP, and I am adding an AWS Blocks backend to swap out local mocks with real cloud infrastructure. You can find all the prompts in this repository.

All of these tips are applicable to greenfield projects as well. I can't promise you it is going to have the 42 effect :)

#1 Talk to AI in Clear Prompts

Each model reacts to prompts differently. The clearer you get, the faster you achieve your goal.

You also need to remember that now we don't only have models, we also have effort levels. If you are not mindful about which model you are running with which effort level, you will have a hard time getting the results you want.

Here are some general rules I follow (you can check the BUILD_PROMPT.md and the AWS Blocks skill in the repo for the full picture):

Zero-Shot

Describe what you want. Works for simple, well-defined tasks.

Here is my frontend build prompt. One sentence, clear outcome:

Build "Some Useful Links" — a LinkTree-style web application using
Next.js with SSR enabled. The complete visual design specification
is in `DESIGN_SPEC.md` and reference screenshots are in the
`design-previews/` folder. Implement the design pixel-perfectly.

And for the backend migration to AWS Blocks:

Replace the local JSON mock services in src/lib/services/local/ with
AWS Blocks implementations. The service registry (index.ts) is the
only file that should change in the existing codebase. Frontend must
not be modified.

Both are zero-shot: one clear task, no ambiguity.

Few-Shot

Show examples. Input, output. Input, output. The model picks up the shape. Research shows the format matters more than whether the examples are perfectly correct.

In my BUILD_PROMPT.md, I use this for the service registry pattern. I show the AI what an implementation swap looks like:

// src/lib/services/index.ts
import { LocalAnalyticsStore } from './local/analytics-store.local';
import { LocalLinkStore } from './local/link-store.local';
import { LocalVisitTracker } from './local/visit-tracker.local';

// SWAP POINT: Replace these with cloud implementations
export const analyticsStore = new LocalAnalyticsStore();
export const linkStore = new LocalLinkStore();
export const visitTracker = new LocalVisitTracker();

When I ask the AI to build the AWS Blocks backend, it sees this pattern and knows the target: create a BlocksAnalyticsStore, BlocksLinkStore, and BlocksVisitTracker that implement the same interfaces, then swap them in index.ts. I do not need to explain the concept of dependency injection. The example IS the explanation.

Chain-of-Thought

Force the model to reason step by step before acting. For debugging, architecture decisions, or anything multi-step, this cuts logical errors significantly.

I use this when asking the AI to plan the AWS Blocks migration:

Before writing any code, analyze the existing service interfaces in
src/lib/services/interfaces/. For each interface method, determine:
1. Which AWS Blocks building block maps to it (DistributedTable, KVStore, FileBucket, etc.)
2. What the key schema should be to support the query patterns
3. Whether the method needs authentication (check if the frontend
   calls it from an admin route or a public route)

Write your analysis as a numbered plan. I will review it before you
start implementing.

The AI produces a plan I can review before it writes a single line of code. Without this step, it would just start building and often pick the wrong storage pattern for a given query.

#2 Set Absolute Boundaries

Use words like MUST, NEVER, ALWAYS, and STRICTLY FORBIDDEN. Avoid weak phrasing like "Please try to," "It is preferred," or "Usually we do."

Here is a comparison from my project. The frontend BUILD_PROMPT.md sets boundaries like this:

All backend infrastructure must be local mocks — no cloud dependencies.
The mocks must be documented clearly enough that another AI agent or
developer can swap them for any cloud provider without restructuring.

And the AWS Blocks skill sets boundaries for the backend side:

Backend lives in `aws-blocks/index.ts`. Frontend imports from
'aws-blocks' (workspace package). The `client.js` is auto-generated
— never edit it.

Both are direct, absolute, and leave no room for interpretation.

Prioritize negative boundaries (Guardrails)

Telling the AI what NOT to do is often more effective than listing everything it should do.

Frontend (AGENTS.md):

- Do not add cloud SDKs, deployment configuration, external persistence,
  or source-controlled credentials unless the task explicitly requires them.
- Import services from `@/lib/services`; components and route handlers
  must not import `src/lib/services/local/*` directly.
- Keep unrelated refactors and generated-file churn out of focused changes.

Backend (AWS Blocks skill):

- Adding to an existing project? Scaffold into a temp dir, copy only
  `aws-blocks/` folder, then manually merge workspace config, scripts,
  and dependencies. The scaffolder overwrites root package.json,
  tsconfig.json, vite.config.ts, .gitignore.
- Never edit index.cdk.ts, index.handler.ts, or client.js — these are
  auto-generated.

#3 Give Your AI Persistent Context

You need to steer the agent in the correct direction. AI tools have dedicated files for this purpose:

AGENTS.md
CLAUDE.md
Kiro steering files (.kiro/steering/)
Kiro skills (.kiro/skills/)

Some of these are loaded every session (steering files), giving the AI persistent rules. Others are loaded on demand (skills), giving the AI specialized knowledge only when it needs it. Both keep your context window lean.

Always-loaded: Steering files

For the frontend, I have an AGENTS.md at the root that covers the full Next.js application:

# AGENTS.md

## Project Overview
Some Useful Links is a local-first, multi-page link-sharing application
built with Next.js App Router, React, strict TypeScript, and Tailwind CSS.

## Commands
npm install
npm run dev
npm run validate:links
npm run lint
npm run build

## Architecture
- src/app: App Router pages, layouts, route handlers
- src/components: UI grouped by admin, analytics, layout, links, share
- src/lib/services/interfaces: Backend-neutral service contracts
- src/lib/services/local: Local JSON-backed implementations
- src/lib/services/index.ts: The only provider registration and swap point

I also have two Kiro steering files that enforce cross-cutting rules regardless of the task:

TypeScript rules (.kiro/steering/typescript.md) — enforces strict typing and build validation:

# TypeScript Project Instructions

## Workflows & Validation
- Pre-completion Check: Before completing any task or reporting success,
  you MUST run `npm run build` in the terminal.
- Do not consider a task finished if the build command returns errors. Fix
  the errors first.

## Coding Conventions
- Strict typing is enforced. You are strictly forbidden from using the
  `any` type.
- Always define and apply the exact, correct types and interfaces for all
  variables, function parameters, and return values.
- You are STRICTLY FORBIDDEN from using @ts-ignore.
  If unavoidable, use @ts-expect-error with a detailed comment.

Agent behavior rules (.kiro/steering/agent.md) — controls what the AI can and cannot do on its own:

# Agent Behavior Rules

## File and Folder Boundaries
- DO NOT create any new Markdown files unless explicitly instructed by
  the user.
- STRICTLY FORBIDDEN to auto-generate changelogs or documentation.
- You MUST update the existing README.md if your changes alter the
  project's public API or architecture.

## Technology Boundaries
- You MUST ALWAYS use the Strands Agents library with TypeScript for any
  agent development.
- You are STRICTLY REQUIRED to use Claude Haiku 4.5 from Amazon Bedrock
  for all agent models.
- You MUST ALWAYS use React and Vite with TypeScript for web development.
- NEVER write or generate unit tests unless the user explicitly commands
  it.

## Security Boundaries
- NEVER commit or hardcode sensitive information (client secrets, API
  keys, client IDs, resource IDs).

## Git Boundaries
- Commits MUST stay under 150 lines of source code.
- Every commit: single-sentence summary, blank line, detailed explanation
  (max 20 lines).
- You MUST append `(Kiro)` to the author name using:
  git commit --author="[Git Username] (Kiro) <[User Email]>"

These prevent the common annoyances: AI generating unwanted test files, committing giant diffs, sneaking any types past the compiler, or littering the repo with markdown files nobody asked for.

On-demand: Skills

Steering files are always loaded. But what about capabilities that are only needed sometimes? You do not want to load everything upfront because that wastes context.

A Skill is a reusable, discoverable capability. The AI loads it only when it becomes relevant to the current task. The most important part of a Skill is the name and description. That is how the AI decides whether to use it.

My AWS Blocks skill activates with this frontmatter:

---
name: building-aws-blocks-apps
description: "Builds fullstack TypeScript applications on AWS using"
  @aws-blocks/blocks. Use when working with any Building Block
  (KVStore, DistributedTable, Agent, AuthBasic...), ApiNamespace,
  BlocksStack, or the create-blocks-app CLI.
---

The main SKILL.md is the overview: decision guides, project structure, quick start. Detailed reference lives in separate files:

.kiro/skills/aws-blocks-development/
├── SKILL.md                    # Overview + decision guide (under 200 lines)
├── CORE-ARCHITECTURE.md        # Scope, ApiNamespace, JSON-RPC, CORS
├── TROUBLESHOOTING.md          # Common errors and fixes
└── blocks/
    ├── auth-basic.md           # AuthBasic patterns
    ├── distributed-table.md    # DistributedTable patterns
    ├── api-namespace.md        # ApiNamespace deep dive
    └── ... (20+ block files)

When the AI needs to implement authentication, it loads blocks/auth-basic.md. When it needs to set up a database, it loads blocks/distributed-table.md. It does not carry all 122 KB of reference material in every conversation.

Keep it lean

Keep the root file under 200 lines. My AGENTS.md is 127 lines. The AWS Blocks SKILL.md is the overview (under 200 lines), with detailed reference files loaded on demand.

Use the "Router Pattern": a root file that points to detailed references when needed. The AWS Blocks skill does exactly this with its block reference table.

Separate context from instructions

Project Context tells the AI where it is:

"This is a Next.js 14 App Router project using Tailwind CSS."

Actionable Rules tell the AI what to do:

"Import services from @/lib/services; components must not import src/lib/services/local/* directly."

Keep these separate. Context helps the AI orient itself. Rules constrain its behavior.

#4 Manage Your Context Window

Your AI sees everything in a stack:

System instructions + steering files
Full conversation history (every message)
Tool output (files, terminal, search results)
Your current request

Performance degrades at 25% capacity, not 100%. You do not have the full context window available. The degradation starts much earlier than you think.

Context rot

Long sessions lead to the model "forgetting" earlier decisions, fixing one thing and breaking two others. Hallucinations increase as context fills up and your original constraints stop being followed.

I have seen this firsthand. On the frontend side, I asked my AI to follow the service registry pattern from my AGENTS.md. After 15 turns of unrelated work, it started importing directly from src/lib/services/local/, exactly what I told it not to do.

On the backend side, I had a session where I was building multiple API methods with AWS Blocks. After building the analytics endpoints, I asked it to add authentication. It generated a whole custom auth system instead of using the AuthBasic block that was in the skill file. The context was too full for it to reference back.

Fighting context rot

Start fresh sessions for each new task
Keep steering files under 200 lines
Summarize progress in a file the AI can re-read, do not rely on conversation history
Keep interactions to 5–7 turns per task max

#5 Follow a Spec-Driven Development Process

Vibe coding skips everything we know about building software: planning, analysis, design, testing, maintenance. All of it gone.

Vibe coding works for prototyping and tiny fixes. But for anything beyond that, you need structure.

Spec-Driven Development (SDD) is a methodology where detailed, unambiguous requirements are written and agreed upon before any actual coding begins. The spec is the contract between you and your AI.

Frontend spec (from `BUILD_PROMPT.md`)

<task>
Build "Some Useful Links" — a LinkTree-style web application using Next.js
with SSR enabled. The complete visual design specification is in
`DESIGN_SPEC.md` and reference screenshots are in the `design-previews/`
folder.

All backend infrastructure must be local mocks — no cloud dependencies. The
mocks must be documented clearly enough that another AI agent or developer
can swap them for any cloud provider without restructuring.
</task>

<architecture>
1. Framework: Next.js (App Router) with Server-Side Rendering enabled
2. Styling: Tailwind CSS with a custom theme from the design spec
3. Backend: Local mocks only — no cloud services, no external APIs
</architecture>

Backend spec (from `MIGRATING_TO_CLOUD_PROMPT.md`)

<task>
Replace the local JSON mock services in `src/lib/services/local/` with AWS
Blocks implementations. The existing service interfaces in
`src/lib/services/interfaces/` are the contract. The service registry
(`src/lib/services/index.ts`) is the only file that should change in the
existing codebase.

The frontend, routing, components, and design must remain untouched.
</task>

<architecture>
1. Backend runtime: AWS Blocks (`aws-blocks/index.ts`)
2. API layer: ApiNamespace with methods that mirror the existing service
   interface contracts
3. Auth: AuthBasic for admin routes (analytics dashboard, page management)
4. Data — Link pages: DistributedTable (stores page configurations and
   link entries)
5. Data — Analytics: DistributedTable (stores daily aggregate snapshots
   per page slug and date)
6. Data — Visit events: DistributedTable (stores raw page-view, link-click,
   and share events)
7. Hosting: Blocks Hosting for the Next.js frontend
</architecture>

<acceptance_criteria>
- [ ] All existing frontend functionality works unchanged
- [ ] `npm run dev` starts both frontend and AWS Blocks local server on
      port 3000
- [ ] Admin routes require AuthBasic login
- [ ] Click tracking persists events to DistributedTable
- [ ] `npm run build` completes without TypeScript errors
- [ ] `npm run deploy` deploys the full stack to AWS
</acceptance_criteria>

The AI knows exactly what to build, what the constraints are, and what "done" looks like. No ambiguity on either side.

Writing good specs

Start with Goals and Non-Goals: what are you building? What are you explicitly NOT building?
Define your tech stack and project structure
Add executable commands so the AI knows how to build and run things
Write clear acceptance criteria so everyone knows when the work is done
Set your boundaries: what should the AI always do? What should it ask you first?

#6 Use MCP to Extend AI Beyond Its Knowledge

Model Context Protocol (MCP) is an open standard for connecting AI to the outside world. With MCP, your AI can:

Connect to data sources (local files, databases, APIs)
Run tools (search engines, calculators, linters)
Follow workflows and specialized prompts
Access knowledge that did not exist when it was trained

Right now there is an MCP server for almost everything: GitHub, Slack, databases, documentation, cloud services.

In my project, I used this in two places:

Frontend: I connected Figma MCP so the AI could reference my actual design system when generating components. Instead of describing colors and spacing in text, it pulled the tokens directly from the Figma file.

Backend: AWS Blocks is a new framework. The AI does not know its API surface from training data. Instead of pasting documentation into the chat (wasting context), I added an MCP server that gives the AI access to the AWS Blocks docs and API references on demand. It queries what it needs, when it needs it.

The result: zero hallucinated API calls. The AI uses new ApiNamespace(scope, 'api', (context) => ({...})) because it can look up the actual signature, instead of guessing something like createApi(...).

#7 Know When to Vibe Code and When to Spec

Some tasks deserve a spec. Others work fine as a quick conversation with the AI. Knowing which approach to use is what saves you time.

Use vibe coding when:

Prototyping something
Making smaller changes and tiny fixes
Learning syntax and a new technology
Automating one-off tasks

Use Spec-Driven Development when:

Building production software
Working in a team
Designing complex architecture
Working on brownfield projects (like adding AWS Blocks to an existing Next.js app)

In my project, I vibe coded the initial design exploration with Figma MCP. But the moment I started building the actual app and the backend migration, I switched to specs. The frontend BUILD_PROMPT.md and the backend AWS Blocks skill together gave the AI everything it needed to produce consistent, predictable results.

Wrapping Up

I am currently finishing the AWS Blocks backend for the link-sharing project and deploying it. I will write up that process in the next post.

You can find the full project, including the BUILD_PROMPT.md, AGENTS.md, MIGRATING_TO_CLOUD_PROMPT.md, and the AWS Blocks skill files in this repository.

Building an Agent Friendly Personal Website with Specs

Salih Guler — Wed, 22 Jul 2026 14:42:11 +0000

If you visit salih.dev right now, you'll notice it redirects somewhere else. That's been bugging me for months. I wanted a proper site where I could list my talks, link my blog posts, and make everything discoverable for both search engines and AI agents. But between conferences and content creation, I never had a full day to sit down and build one from scratch.

So I changed the question. Instead of "when will I have time for this?" I asked: "what can I get done in one iteration?"

A few days ago, after dropping my son off at school, I walked into a nearby cafe with my laptop and started planning. One hour later, I had a working personal website with 19 imported blog posts, conference listings, agent readiness, and a responsive design.

Here's how.

📺 This post accompanies the YouTube video where I walk through the whole process live. The source code is on GitHub.

Step 1: Get a design reference

I wanted a minimalistic black and white design, text-heavy, light mode first. I opened my AI assistant and described what I needed:

A map on the left showing my current city (so people can see where I'm based)
Blog posts with header images on the right
Upcoming and past conference sections
Social links, an About page, a Blog subpage

The point is to produce a visual reference you can hand to the coding assistant later.

The first result looked close enough. I downloaded it and moved on.

Step 2: Write the specification

This is the part that made everything else productive. Before touching any code, I wrote a spec.md that defined the project's purpose, rules, goals, and non-goals.

Here's the actual file from the repository:

# salih.dev Personal Website Building

The purpose of this document is to build a text-heavy personal website
that will eventually live at the salih.dev address.

# Rules
- You MUST use Astro to build this website.
- You MUST use TypeScript as the language.
- You MUST create the content using Astro's markdown support.
- You SHOULD NOT write tests for it.
- You MUST commit your iterations and changes with logical commit messages.
- You MUST use images/reference-image-for-design.png as the design reference.
  For changes, always ask for approval.
- For each task, you MUST come up with a plan describing what you are going to
  do and ask for approval with clear acceptance criteria.

# Goals
- The website has a responsive design.
- The website is SEO optimized.
- The website is AEO optimized.
- The website considers the following for agent readiness:
  - Discoverability — robots.txt, Sitemap, Link response headers, DNS-AID
  - Content Accessibility — Markdown content negotiation
  - Bot Access Control — AI bot rules in robots.txt, Content Signals, Web Bot Auth
  - Protocol Discovery — MCP Server Card, Agent Skills, WebMCP, API Catalog,
    OAuth discovery
  - Commerce — x402, MPP, UCP, ACP
- The website's markdown support handles:
  - All text types
  - Links
  - Code (with syntax highlighting)
  - Image embedding
  - Video embedding from YouTube
  - And anything else that blog posts typically require
- The website is fully functional locally.

# Non-Goals
- Deployment to a hosting service.

A few things worth noting about this spec:

Strong language matters. When you talk to an AI coding assistant, you need to be specific. "You MUST use Astro" is different from "maybe we could try Astro?" Soft language gives the AI room to substitute its own preferences. Capital letters, bold text, and strong framing ("MUST", "SHOULD NOT") keep the assistant on track.

Opinionated tech choices up front. Astro with TypeScript. No debate, no "evaluate alternatives" phase. I chose Astro because it has excellent markdown support for text-heavy sites and ships zero JavaScript by default. That decision was made before writing the spec.

No tests. One-hour budget. Tests come later when the site is live and I'm iterating on it.

I stay in the driver's seat. The spec requires the assistant to plan before building, with clear acceptance criteria, and ask for my approval. Even in an hour of AI-assisted coding, I'm responsible for what gets built. We're software engineers. Whatever we build is our responsibility.

Agent Readiness

Agent readiness is a first-class goal. Not an afterthought. The spec calls out specific categories — discoverability, content accessibility, protocol discovery — that resulted in endpoints most personal websites don't have.

The implementation breaks into five categories. Here's what each one produced:

1. Discoverability

The basics: a robots.txt, a sitemap.xml, an RSS feed, and a llms.txt file.

The llms.txt file is the interesting one. It's a machine-readable summary of the site: who I am, what pages exist, what each blog post is about (with one-line descriptions), and what content-use policies apply. It's generated dynamically from the site's actual content, so adding a blog post automatically adds it to llms.txt. No manual syncing.

# Salih Güler

> Salih Güler is a Senior Developer Advocate at AWS focused on frontend
> and mobile app development, developer experience, and serverless architecture.

Use canonical HTML URLs for citations. Request any content page with
`Accept: text/markdown`, or follow its advertised `.md` alternate.

## Core pages
- [Home](https://salih.dev/): Profile, current location, conferences, and latest posts
- [About](https://salih.dev/about/): Biography and areas of work
- [Blog](https://salih.dev/blog/): Complete post index
- [Full corpus](https://salih.dev/llms-full.txt): Combined public Markdown content

## Content use
- Search indexing: allowed
- AI-assisted answers and user-directed retrieval: allowed
- Model training: declined

2. Content accessibility (markdown negotiation)

Every HTML page on the site has a markdown alternate. The middleware checks the Accept header on incoming requests. If a client sends Accept: text/markdown and prefers it over text/html, the server responds with the markdown version directly. No scraping, no HTML parsing.

Each HTML response also includes Link headers advertising the markdown alternate, the canonical HTML URL, and the API catalog:

Link: <https://salih.dev/about/>; rel="canonical"; type="text/html"
Link: <https://salih.dev/about.md>; rel="alternate"; type="text/markdown"
Link: <https://salih.dev/api/catalog.json>; rel="service-desc"; type="application/json"

An agent that sees those headers knows exactly where to get structured content without guessing.

3. Bot access control

The robots.txt distinguishes between search/retrieval bots and training crawlers:

# User-directed retrieval bots: allowed
User-agent: OAI-SearchBot
User-agent: ChatGPT-User
User-agent: PerplexityBot
User-agent: Claude-User
Allow: /

# Training crawlers: declined
User-agent: GPTBot
User-agent: CCBot
User-agent: Google-Extended
User-agent: anthropic-ai
User-agent: ClaudeBot
Disallow: /

Every response also includes a Content-Signal header: search=yes, ai-input=yes, ai-train=no. This tells bots the policy per-page, not just at the robots.txt level.

4. Protocol discovery

The site serves several .well-known endpoints that agents can check:

/.well-known/agent-readiness.json — A manifest listing the site's policy (search: yes, AI input: yes, training: no), available representations (HTML, markdown, llms.txt, llms-full.txt), and a full capability inventory with status for each.
/.well-known/skills/index.json — Declares a read-only skill that tells agents how to access markdown content on the site.
/.well-known/webmcp.json — Responds honestly that no browser tools or transactional actions are available (important: agents check this and knowing the answer is "nothing" prevents unnecessary probing).
/api/catalog.json — A catalog of all available documents and protocol endpoints.
/api/openapi.json — An OpenAPI spec describing the site's API surface.

For capabilities that aren't implemented (OAuth, DNS-AID, commerce protocols), the site still serves the endpoints with a structured "unavailable" response and a reason. An agent checking /.well-known/mcp/server-card.json gets back a clear "no MCP transport is operated by this site" instead of a 404 that leaves it guessing.

5. Commerce (intentionally empty)

The spec listed commerce protocols (x402, MPP, UCP, ACP). For a personal blog, none of them apply. But the capability registry explicitly marks them as unavailable with a note. This is the right approach: declare what you don't support so agents stop looking for it.

Why this matters

Most personal websites serve HTML and hope for the best. If an AI agent wants to cite your blog post, it has to scrape the page, parse the DOM, guess at the main content vs. navigation, and hope the result is coherent.

With agent readiness:

An agent can request Accept: text/markdown and get clean content directly
It can read llms.txt to understand the full site in seconds
It can check agent-readiness.json to understand what protocols the site supports
It respects your content-use preferences (search yes, training no) because you stated them in a machine-readable way

All of this came from putting "agent readiness" in the spec with the specific categories spelled out. The AI assistant knew what endpoints to build because the spec told it exactly what was needed.

Before feeding this to the coding assistant, I ran it through an AI tool to fix grammar issues. My English isn't perfect (not a native speaker), and that's fine. The spec doesn't need to be literary. It needs to be clear.

Step 3: Plan and implement

With the design image and spec.md ready, I opened VS Code with GPT 5.6 Sol with Amazon Bedrock as the AI coding assistant.

The assistant entered planning mode first. It read the spec, asked clarifying questions: Do you want editable placeholders? What aesthetic direction? What information should be pre-filled? As I answered, the plan took shape. If I didn't know an answer to something, I could click the info button to understand what the option meant.

Once planning finished, I got a markdown file with implementation details, a summary, and technical decisions. It looked like the spec but with more depth — the assistant had pulled in information about agent-readiness standards, Astro best practices, and the specific endpoints needed.

I clicked "Implement the plan" and the assistant started building.

This doesn't mean I walked away. I watched the output, refreshed the local dev server, and course-corrected when needed. At one point, the assistant was building things in a way that made sense for it but not for me. Taking a close look at each iteration is part of the process.

After the implementation pass, I refreshed the page and saw: the correct city on the map, my social icons (including Bluesky), the blog section ready for content, the About page with my bio. No email shown because I chose not to share it. Everything pulling from the configuration.

Step 4: Import existing blog posts

My articles were scattered across dev.to and Medium. Copying them manually was out of the question with 19 posts. I told the assistant: "bring in my blog posts from dev.to."

The assistant wrote an import script (scripts/import-dev.mjs) that:

Hits the dev.to API with my username
Fetches each article's full content
Transforms the markdown (fixes broken links, converts {% youtube %} liquid tags to a custom remark directive format)
Writes each post as an Astro content collection entry with proper frontmatter (title, description, date, category, tags, hero image, AI summary)

Each article requires reviewed metadata (a category and an AI summary) that I provide in a map inside the script. If an article doesn't have its metadata, the script throws. This forces me to review each import rather than blindly dumping content.

npm run import:dev

For Medium, it wrote a second script (scripts/import-medium.mjs) that fetches my RSS feed, parses the HTML body, strips Medium's tracking pixels and footer boilerplate, converts HTML to markdown with Turndown, extracts hero images, and handles duplicate detection. If an article already exists (because I published it on both platforms), it merges the source link rather than creating a duplicate.

npm run import:medium

19 posts imported in seconds.

After the import, I checked the blog listing — header images rendered, detail pages showed code highlighting with syntax colors, and YouTube videos embedded properly using the custom remark plugin. That YouTube support I called out in the spec? It produced a directive syntax:

::youtube{id="dQw4w9WgXcQ" title="My video"}

This renders as a responsive iframe embed. It worked because the requirement was explicit in the spec.

Step 5: Polish

With everything imported, I asked "what's left?" Two things:

A mobile layout fix — some elements weren't sizing correctly on smaller screens
A CSS patch for the map component so it doesn't overflow when the viewport is too large or too small

Both were quick fixes. The assistant handled them in one pass.

What we built

Everything you see was done in under an hour with one file (the spec), one image (the design reference), and one AI coding assistant (GPT 5.6 Sol in VS Code). We took an idea and turned it into a product.

The site includes:

Blog posts rendering from markdown (syntax highlighting, YouTube embeds, GFM tables, images)
Conference listings (upcoming and past) from a config file
Agent readiness endpoints: llms.txt, llms-full.txt, .well-known/agent-readiness.json, WebMCP manifest, MCP server card, agent skills, OpenAPI catalog, content negotiation middleware
RSS feed, sitemap, SEO meta tags, Open Graph
Categories and tags with their own listing pages
Responsive design, mobile-friendly
Import scripts for dev.to and Medium with duplicate detection

Open source and what's next

The full source is on GitHub: github.com/salihgueler/salih-dev

Clone it, run npm install && npm run dev, and you'll have a local version in seconds. Swap out my content in src/config/site.ts and src/content/blog/ for yours and you're done. You can use any hosting service to put it live.

I'll be publishing a follow-up on deploying with AWS. Stay tuned for that.

If you have questions, drop them in the video comments or find me on social media with @salihgueler handle.

Building a Geography Game with a Custom Building Block with AWS Blocks

Salih Guler — Wed, 01 Jul 2026 18:55:29 +0000

AWS Blocks handles authentication, databases, file storage, AI agents and more out of the box. But what do you do when you need a service it doesn't cover? You write your own block.

In this post, you'll build a custom Building Block that wraps Google Maps and wire it into a playable geography guessing game called BlocksExplorer . You'll see the full conditional-export pattern that makes a block work offline in local dev and switch to Google Maps after deployment, with zero code changes in your consumer.

As of the publish date of this post AWS Blocks is on Developer Preview. The features and the solution might change. For recent version make sure you check the source code of the project and the official documentation.

What we're building

BlocksExplorer shows you a photo of a landmark. You click a map to guess where it is. The closer your guess, the more points you earn. A leaderboard tracks each player's single best session across 5 rounds.

The map and geocoding features come from a custom block that wraps Google Maps. During local dev, the block serves a bundled offline SVG map. No internet connection required. After deployment, that same block hands the frontend a Google Maps API key and the browser renders a full interactive map.

Requirements

Node.js 20+
npm 10+
AWS Blocks CLI (npm create @aws-blocks/blocks-app@latest)
For deployment: AWS CLI configured, CDK bootstrapped, a Google Maps JavaScript API key

The 4-export pattern

Every Building Block in AWS Blocks uses conditional exports in package.json to load different code depending on where it runs:

Export condition	Runs in	Purpose
`default`	Local dev server	In-memory fake, no AWS or API keys needed
`aws-runtime`	Lambda runtime	Production code (SDK calls, env vars)
`cdk`	CDK synthesis	Emits CloudFormation resources or wires config
`browser`	Frontend bundle	Types or client-side helpers

Your consumer code never changes. The local dev server doesn't set any special condition, so default kicks in and loads the mock. CDK synth passes --conditions=cdk, and the Lambda bundler resolves aws-runtime. The frontend (Vite) resolves the browser condition.

Building the LocationMap block

Create a custom-blocks/location-map/ directory in your project with these files:

types.ts

The shared interface that all implementations conform to. The MapDescriptor union type tells the frontend whether to render the offline SVG or load Google Maps:

export interface Coordinates {
  lat: number;
  lng: number;
}

export interface LocationMapConfig {
  mapStyle?: string;
  indexName?: string;
}

export interface GeocoderResult {
  coordinates: Coordinates;
  label: string;
  placeId: string;
}

export type MapDescriptor =
  | { offline: true }
  | { offline: false; googleMapsApiKey: string };

export interface LocationMapService {
  reverseGeocode(coords: Coordinates): Promise<GeocoderResult | null>;
  getMapDescriptor(): Promise<MapDescriptor>;
}

export declare class LocationMap implements LocationMapService {
  reverseGeocode(coords: Coordinates): Promise<GeocoderResult | null>;
  getMapDescriptor(): Promise<MapDescriptor>;
}

The declare class at the bottom emits no JavaScript. It exists so TypeScript can type-check import { LocationMap } without loading a runtime file. The concrete implementations live in mock.ts and aws.ts.

geocode.ts (shared logic)

Both mock and deployed implementations need reverse geocoding. Since this game uses a fixed location set, we can share one function between both exports with no external API calls:

import type { Coordinates, GeocoderResult } from "./types";

const FIXTURE_PLACES = [
  { name: "Shibuya Crossing", coordinates: { lat: 35.6595, lng: 139.7004 }, country: "Japan", city: "Tokyo" },
  { name: "Taj Mahal", coordinates: { lat: 27.1751, lng: 78.0421 }, country: "India", city: "Agra" },
  { name: "Brandenburg Gate", coordinates: { lat: 52.5163, lng: 13.3777 }, country: "Germany", city: "Berlin" },
  // ... 7 more locations
];

function haversineDistance(a: Coordinates, b: Coordinates): number {
  const R = 6371;
  const dLat = ((b.lat - a.lat) * Math.PI) / 180;
  const dLng = ((b.lng - a.lng) * Math.PI) / 180;
  const x =
    Math.sin(dLat / 2) ** 2 +
    Math.cos((a.lat * Math.PI) / 180) *
      Math.cos((b.lat * Math.PI) / 180) *
      Math.sin(dLng / 2) ** 2;
  return R * 2 * Math.atan2(Math.sqrt(x), Math.sqrt(1 - x));
}

export function reverseGeocodeFixture(coords: Coordinates): GeocoderResult {
  let nearest = FIXTURE_PLACES[0];
  let minDist = Infinity;
  for (const place of FIXTURE_PLACES) {
    const dist = haversineDistance(coords, place.coordinates);
    if (dist < minDist) {
      minDist = dist;
      nearest = place;
    }
  }
  return {
    coordinates: nearest.coordinates,
    label: `${nearest.name}, ${nearest.city}, ${nearest.country}`,
    placeId: `fixture-${nearest.name.toLowerCase().replace(/\s+/g, "-")}`,
  };
}

This finds the nearest known place via haversine distance. Both mock.ts and aws.ts import it.

mock.ts (local development)

The mock runs during npm run dev. It returns { offline: true } to signal the frontend to use the bundled SVG map. No API keys, no network, works completely offline:

import type { Coordinates, GeocoderResult, MapDescriptor } from "./types";
import { reverseGeocodeFixture } from "./geocode";

export class LocationMap {
  async reverseGeocode(coords: Coordinates): Promise<GeocoderResult | null> {
    return reverseGeocodeFixture(coords);
  }

  getMapDescriptor(): Promise<MapDescriptor> {
    return Promise.resolve({ offline: true });
  }
}

Same class name, same method signatures as the deployed version. The only difference is what getMapDescriptor() returns.

aws.ts (deployed Lambda)

The production implementation reads the Google Maps API key from the Lambda environment and hands it to the frontend. If no key is configured, it gracefully falls back to the offline SVG:

import type { Coordinates, GeocoderResult, MapDescriptor } from "./types";
import { reverseGeocodeFixture } from "./geocode";

export class LocationMap {
  async reverseGeocode(coords: Coordinates): Promise<GeocoderResult | null> {
    return reverseGeocodeFixture(coords);
  }

  async getMapDescriptor(): Promise<MapDescriptor> {
    const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
    if (!googleMapsApiKey) {
      return { offline: true };
    }
    return { offline: false, googleMapsApiKey };
  }
}

The GOOGLE_MAPS_API_KEY env var is injected by the CDK construct at deploy time.

cdk.ts (infrastructure wiring)

Google Maps is an external provider, so there's no AWS resource to provision. The CDK construct's only job is to wire the API key into the Lambda environment:

import { Construct } from "constructs";
import type { Function as LambdaFunction } from "aws-cdk-lib/aws-lambda";

export { LocationMap } from "./mock";

export interface LocationMapCdkProps {
  googleMapsApiKey?: string;
}

export class LocationMapCdk extends Construct {
  private readonly googleMapsApiKey: string;

  constructor(scope: Construct, id: string, props?: LocationMapCdkProps) {
    super(scope, id);
    this.googleMapsApiKey = props?.googleMapsApiKey ?? "";
  }

  configureBackend(handler: LambdaFunction): void {
    handler.addEnvironment("GOOGLE_MAPS_API_KEY", this.googleMapsApiKey);
  }
}

Two things to note here:

The export { LocationMap } from "./mock" re-export exists because CDK synth imports aws-blocks/index.ts (which instantiates new LocationMap()). The lightweight mock satisfies that import without pulling in production dependencies.
configureBackend is a pattern for blocks that need to inject config into the Lambda handler. Call it after creating the stack's handler.

browser.ts (types for the frontend)

The browser export provides only types. No runtime code ships to the frontend from this package:

export type { Coordinates, GeocoderResult, LocationMapConfig } from "./types";

package.json (wiring it together)

{
  "name": "@blocks-explorer/location-map",
  "version": "0.1.0",
  "type": "module",
  "exports": {
    ".": {
      "browser": "./browser.ts",
      "cdk": "./cdk.ts",
      "aws-runtime": "./aws.ts",
      "types": "./types.ts",
      "default": "./mock.ts"
    },
    "./cdk": "./cdk.ts"
  },
  "dependencies": {
    "@googlemaps/js-api-loader": "^2.1.1",
    "aws-cdk-lib": "2.260.0",
    "constructs": "^10.6.0"
  },
  "devDependencies": {
    "@types/google.maps": "^3.65.2"
  }
}

The "./cdk" sub-export lets index.cdk.ts import the CDK construct directly (from "@blocks-explorer/location-map/cdk") without triggering the mock class on the main export path.

Wiring the block into the CDK stack

In aws-blocks/index.cdk.ts, instantiate the construct and call configureBackend:

import { LocationMapCdk } from "@blocks-explorer/location-map/cdk";

// ... after BlocksStack.create() ...

const locationMap = new LocationMapCdk(blocksStack, "LocationMap", {
  googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY,
});
locationMap.configureBackend(blocksStack.handler);

The GOOGLE_MAPS_API_KEY comes from .env.production (never committed to git). The npm run deploy script loads it into the process env before CDK synth runs.

The game backend

The backend combines AuthBasic (player accounts with week-long sessions), DistributedTable (session state and leaderboard), and the custom LocationMap (geocoding and map config):

import {
  Scope,
  ApiNamespace,
  DistributedTable,
  DistributedTableErrors,
  AuthBasic,
  isBlocksError,
} from "@aws-blocks/blocks";
import { z } from "zod";
import { LocationMap } from "@blocks-explorer/location-map";

const scope = new Scope("be");
const maps = new LocationMap();

const auth = new AuthBasic(scope, "auth", {
  sessionDuration: 86400 * 7,
  passwordPolicy: { minLength: 6 },
});

Two DistributedTables back the game. One for active sessions, one for the leaderboard:

const sessions = new DistributedTable(scope, "sessions", {
  schema: sessionSchema,
  key: { partitionKey: "sessionId" },
});

const leaderboard = new DistributedTable(scope, "lb", {
  schema: z.object({
    pk: z.string(),
    sk: z.string(),
    username: z.string(),
    points: z.number(),
    guesses: z.number(),
    achievedAt: z.number(),
  }),
  key: { partitionKey: "pk", sortKey: "sk" },
});

The API uses the new ApiNamespace(scope, "api", ...) constructor. It takes a scope, a name, and a factory function that receives the request context. The getMapConfig method exposes the block's map descriptor to the frontend:

export const api = new ApiNamespace(scope, "api", (context) => ({
  async getMapConfig() {
    const descriptor = await maps.getMapDescriptor();
    return {
      isOffline: descriptor.offline,
      googleMapsApiKey: descriptor.offline ? null : descriptor.googleMapsApiKey,
      attribution: descriptor.offline ? "Offline SVG Map" : "© Google",
    };
  },

  async startSession() {
    const user = await auth.requireAuth(context);
    const rounds = pickSessionRounds();
    // ... create session, store server-side, return first round
  },

  async submitGuess(sessionId: string, guessLat: number, guessLng: number) {
    const user = await auth.requireAuth(context);
    // ... validate session, score the guess, advance round pointer
    const placeInfo = await maps.reverseGeocode({ lat: round.lat, lng: round.lng });
    // ... return result with label from the block
  },

  async getLeaderboard() { /* ... */ },
}));

The frontend calls api.getMapConfig() on load and renders either the offline SVG or an interactive Google Map based on the response.

Error handling

The session architecture needs protection against duplicate submissions. What happens if a player's browser retries a failed request, or they double-click the submit button? The answer is optimistic locking via ifFieldEquals:

try {
  await sessions.put(updatedSession, {
    ifFieldEquals: { currentRound: index },
  });
} catch (e) {
  if (isBlocksError(e, DistributedTableErrors.ConditionalCheckFailed)) {
    throw new Error("That round was already submitted");
  }
  throw e;
}

You catch it with isBlocksError(e, DistributedTableErrors.ConditionalCheckFailed), a type-safe error matcher from the blocks SDK. This pattern gives you atomic compare-and-swap semantics without any external locking infrastructure.

The offline map: local dev without internet

The custom block pattern pays off visually in the map. The LocationMap block controls what the player sees on screen:

Environment	Map rendering	Source
`npm run dev`	Bundled SVG with pan and zoom	`public/world-map.svg` (zero network)
Deployed	Google Maps JavaScript API	Full vector tiles, street-level zoom

The frontend calls api.getMapConfig() on mount and picks the right renderer:

Offline mode: fetches /world-map.svg (served by Vite from public/), renders it inline, and converts clicks to coordinates using equirectangular projection math:

// SVG viewBox is "0 0 360 180", trivial coordinate conversion
const x = ((e.clientX - rect.left) / rect.width) * 360;
const y = ((e.clientY - rect.top) / rect.height) * 180;
const lng = x - 180;
const lat = 90 - y;

Online mode: initializes Google Maps via @googlemaps/js-api-loader using the API key from getMapConfig().

The SVG map lives at public/world-map.svg, 177 countries rendered in an equirectangular projection. It works without internet because Vite serves the file directly from the public/ folder during npm run dev, the same way it serves your index.html. The component supports scroll-to-zoom (up to 8×) and click-and-drag panning, so players can zoom into a region for more precise pin placement. Markers scale inversely with zoom so they stay readable at any level. No tile server, no CDN, no external dependencies. You can develop this game on a plane.

The 4-export pattern goes deeper than the server. It flows all the way through to the user experience. The mock.ts export signals "offline", the backend exposes that signal via getMapConfig(), and the frontend adapts. Same getMapDescriptor() method call, completely different rendering, but with the same interaction model (click to guess, zoom to refine).

Running it

npm install
npm run dev

The offline SVG map renders instantly. No environment variables, no API keys, no .env file needed for local development.

Deploying to AWS

Create a .env.production file with your Google Maps JavaScript API key (restrict it by HTTP referrer in the Google Cloud console):

echo "GOOGLE_MAPS_API_KEY=AIza..." > .env.production

Then deploy:

npm run deploy

AWS Blocks provisions everything your app needs: the DynamoDB tables for sessions and the leaderboard, the auth backend, and your custom block's env var injection. Same code you wrote for local dev, now running on AWS.

Once deployed, the game looks and plays the same, but now you're on Google Maps with full zoom, satellite imagery, and Street View integration. You can see the difference in the map: the deployed version renders crisp vector tiles at every zoom level with labels and terrain. The offline SVG served its purpose during development (zero-config and no credentials needed) but now the aws.ts export takes over.

Cleaning up

npm run destroy

This removes the CloudFormation stack including the DynamoDB tables, Lambda functions, and API Gateway.

What you've learned

Building a custom block follows one pattern:

Define your types and shared logic (types.ts, geocode.ts)
Write the mock (fixture data, offline signals)
Write the AWS implementation (reads env vars, calls external APIs)
Write the CDK construct (provisions resources or injects config)
Wire the conditional exports in package.json

But the deeper insight: custom blocks can wrap any provider, not only AWS services. Google Maps, Stripe, Twilio, your internal APIs. The CDK construct's job might be as simple as injecting an API key into the Lambda environment. And the mock enables a fully offline local development experience: the offline SVG map, the fixture geocoding data, the local auth. All of it works without a network connection. When you deploy, the same code uses real services.

The full source code is on GitHub: blocks-explorer. If you want to try the custom block in your own project, copy the custom-blocks/location-map/ directory into your workspace, add it to your package.json workspaces, and swap in your own Google Maps API key.

Building a World Cup Bracket Picker with AWS Blocks

Salih Guler — Thu, 18 Jun 2026 07:28:45 +0000

AWS just launched AWS Blocks, an open-source TypeScript framework that gives you backend capabilities on AWS without learning infrastructure tools. Everything runs locally without an AWS account. When you're ready, deploy the same code to AWS with zero changes.

In this post, I'll build a full-stack World Cup bracket picker with it. The app lets users:

Pick 1st, 2nd, and 3rd place in each of the 12 groups
Predict knockout round winners all the way to the final
Chat with an AI agent that knows every team's roster and FIFA ranking
See other users' picks appear in real time
Automatically sync real match results on an hourly schedule
Compete on a leaderboard once real results come in

The full source code is on GitHub. The mock branch has the frontend-only starting point with prompts if you want to build along.

Prerequisites

Node.js 22 or higher
An IDE (Kiro is preferred)
Ollama (optional, for running the AI agent locally)

Getting ready

Clone the repository and checkout the mock branch. This gives you a React 19 + Vite + Tailwind frontend with all the UI components already built, but no backend.

git clone https://github.com/salihgueler/worldcup-bracket-picker.git
cd worldcup-bracket-picker
git checkout mock
npm install
npm run dev

Open http://localhost:3000 to see the UI shell. Nothing works yet because there's no backend.

Next, add AWS Blocks to the project:

npm create @aws-blocks/blocks-app@latest .

This scaffolds an aws-blocks/ folder with a dev server, CDK deployment config, and a sample todo app. We'll replace the sample code with our own. Run npm run dev again and you'll see both the Vite frontend on port 3000 and the Blocks backend on port 3001.

Authentication

AWS Blocks offers different authentication types: basic username/password, Cognito User Pools, and OIDC/OAuth2 with external providers like Google or GitHub. For this app, we'll use basic auth. It stores credentials in a database and issues JWT tokens for session management.

import { Scope, AuthBasic } from "@aws-blocks/blocks";

const scope = new Scope("wc");

const auth = new AuthBasic(scope, "auth", {
  passwordPolicy: { minLength: 8, requireDigits: true },
});

export const authApi = auth.createApi();

Scope defines the resource boundary for the app. All blocks attach to it. AuthBasic creates the auth system with a password policy. auth.createApi() exports a state-machine API that the frontend Authenticator widget hooks into.

You can configure session duration, cross-domain cookies for sandbox mode, email code delivery, and more. For now, the defaults work fine.

On the frontend, open AuthGate.tsx and wire up the Authenticator widget:

import { useEffect, useRef, type ReactNode } from "react";
import { authApi } from "aws-blocks";
import { Authenticator } from "@aws-blocks/blocks/ui";
import { useAuth } from "../hooks/useAuth";

export function AuthGate({ children }: { children: ReactNode }) {
  const { user, loading } = useAuth();
  const mountRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (loading || user || !mountRef.current) return;
    const host = mountRef.current;
    host.innerHTML = "";
    host.appendChild(Authenticator(authApi));
    return () => {
      host.innerHTML = "";
    };
  }, [loading, user]);

  if (loading) return <div className="loading">Loading...</div>;
  if (!user) return <div ref={mountRef} />;
  return <>{children}</>;
}

The Authenticator is a framework-agnostic DOM element. It renders sign-up/sign-in forms and is tied directly to authApi. When auth state changes, it updates automatically. The useAuth hook listens for those changes:

import { useState, useEffect, useCallback } from "react";
import { authApi } from "aws-blocks";
import { onAuthChange, broadcastAuthChange } from "@aws-blocks/blocks/ui";

export interface AuthUser {
  userId: string;
  username: string;
}

export function useAuth() {
  const [user, setUser] = useState<AuthUser | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const unsubscribe = onAuthChange(authApi, (u) => {
      setUser(u ? { userId: u.userId, username: u.username } : null);
      setLoading(false);
    });
    return unsubscribe;
  }, []);

  const signOut = useCallback(async () => {
    const next = await authApi.setAuthState({ action: "signOut" });
    broadcastAuthChange(next.user ?? null);
  }, []);

  return { user, loading, signOut };
}

onAuthChange subscribes to auth state changes across the same window and across tabs. It fires immediately with the current user, then on every sign-in or sign-out.

Data

Blocks gives you three storage options: NoSQL tables (DistributedTable), Postgres (Database), and key-value (KVStore). We'll use DistributedTable for structured data with indexes and KVStore for simple flags.

The scaffolder generates a sample todos table. Here's what a DistributedTable looks like:

const todoSchema = z.object({
  userId: z.string(),
  todoId: z.string(),
  title: z.string(),
  completed: z.boolean(),
  priority: z.number(),
  version: z.number(),
  createdAt: z.number(),
});

const todos = new DistributedTable(scope, "todos", {
  schema: todoSchema,
  key: { partitionKey: "userId", sortKey: "todoId" },
  indexes: {
    byPriority: { partitionKey: "userId", sortKey: "priority" },
    byTitle: { partitionKey: "userId", sortKey: "title" },
  },
});

One Zod schema gives you runtime validation, TypeScript types, and the database shape in a single definition. The partitionKey determines how items are distributed across storage. The sortKey orders items within a partition. Indexes let you query by different sort orders without scanning the entire table.

Remove the todos code and add the match table for our World Cup data:

const matchSchema = z.object({
  matchId: z.string(),
  matchType: z.string(),
  stage: z.string(),
  team1Id: z.string(),
  team2Id: z.string(),
  scheduledDate: z.string(),
  result: z.string().optional(),
  score: z.string().optional(),
});

const matches = new DistributedTable(scope, "matches", {
  schema: matchSchema,
  key: { partitionKey: "matchType", sortKey: "matchId" },
  indexes: {
    byStage: { partitionKey: "stage", sortKey: "matchId" },
  },
});

For simple per-user state like "has this user locked their bracket?", KVStore is easier than a full table:

const lockStore = new KVStore<boolean>(scope, "bracket-lock");

CRUD operations are straightforward:

// Upsert (insert or update)
await matches.put({ ...match, result, score });

// Batch write
await matches.putBatch(items);

// Delete
await matches.delete({ matchType: "MATCH", matchId });

// Query by index
const groupMatches = await Array.fromAsync(
  matches.query({
    index: "byStage",
    where: { stage: { equals: "group" } },
  })
);

The frontend calls these through ApiNamespace methods. Types flow end-to-end from the Zod schema to the frontend function call with no code generation step.

Realtime

Blocks supports WebSocket pub/sub through the Realtime block. In our app, users see other people's bracket picks appear live as they're made.

First, create the picks table and a Realtime block:

const picks = new DistributedTable(scope, "picks", {
  schema: pickSchema,
  key: { partitionKey: "oddsType", sortKey: "oddsId" },
  indexes: {
    byUser: { partitionKey: "userId", sortKey: "matchId" },
    byMatch: { partitionKey: "matchId", sortKey: "userId" },
  },
});

const PICKS_CHANNEL = "all";
const rt = new Realtime(scope, "rt", {
  namespaces: {
    picks: Realtime.namespace(
      z.object({
        userId: z.string(),
        username: z.string(),
        matchId: z.string(),
        predictedWinner: z.string(),
      }),
    ),
  },
});

When a user makes a pick, publish it to the channel:

await rt.publish("picks", PICKS_CHANNEL, {
  userId: user.userId,
  username: user.username,
  matchId,
  predictedWinner,
});

On the frontend, subscribe to the channel and render events as they arrive:

const sub = channel.subscribe((msg: PickEvent) => {
  setEvents((prev) => [msg, ...prev].slice(0, MAX_EVENTS));
});

What this gives you:

One Zod schema defines the database shape, TypeScript types, and runtime validation. Defined once.
makePick does auth, a database write, and a realtime broadcast in three lines. No API Gateway config, no DynamoDB setup, no WebSocket server.
The same code runs locally with automatic mocks and deploys to AWS with zero config.
The realtime payload type flows straight from the schema into your subscribe handler with full type safety.

Agents

My favorite feature of Blocks is the Agent block. You define an AI agent with tools that have direct access to your data layer. Locally it runs with Ollama (or a canned mock if Ollama isn't available). On AWS it runs on Amazon Bedrock.

const predictor = new Agent(scope, "predictor", {
  model: {
    deployed: BedrockModels.BALANCED,
    local: OllamaModels.SMALL,
  },
  systemPrompt: [
    "You are the official AI predictor for FIFA World Cup 2026.",
    "You help fans understand the teams and forecast match outcomes.",
    "Always ground your answers in real data by calling your tools:",
    "- lookupTeam to fetch a team's group, FIFA ranking, and confederation",
    "- getTeamSquad to inspect a team's player roster",
    "- getMatchConsensus to see how the community has picked a match",
    "- getUserBracket to review the current user's predictions",
    "- getMatchResult to fetch the actual outcome of a played match",
  ].join("\n"),
  toolContextSchema: z.object({ userId: z.string() }),
  tools: (tool) => ({
    lookupTeam: tool({
      description: "Look up a team's details by id or name",
      parameters: z.object({
        teamId: z.string().describe("Team id (e.g. 'BRA') or full name"),
      }),
      handler: async ({ input }) => {
        const direct = await teams.get({ type: "TEAM", teamId: input.teamId });
        if (direct) return direct;
        // Fallback: case-insensitive name search
        const all = await Array.fromAsync(
          teams.query({ where: { type: { equals: "TEAM" } } })
        );
        const needle = input.teamId.trim().toLowerCase();
        return all.find(
          (t) => t.name.toLowerCase().includes(needle) ||
                 t.teamId.toLowerCase() === needle
        ) ?? { error: `No team found matching "${input.teamId}"` };
      },
    }),
    // getTeamSquad, getMatchConsensus, getUserBracket, getMatchResult...
  }),
});

The tools callback pattern gives each tool typed input derived from its Zod parameters schema. The toolContextSchema passes the authenticated user's ID into tools so they can scope queries to the caller, without the model seeing it.

To expose the agent via your API:

export const api = new ApiNamespace(scope, "api", (context) => ({
  async chatWithPredictor(message: string) {
    const user = await auth.requireAuth(context);
    let conversationId = await predictorConversations.get(user.username);
    if (!conversationId) {
      conversationId = await predictor.createConversationId(user.username);
      await predictorConversations.put(user.username, conversationId);
    }
    const result = await predictor.stream(message, {
      conversationId,
      userId: user.username,
      context: { userId: user.username },
    });
    return { reply: (await result.complete()).text ?? "" };
  },
}));

From the frontend, one function call:

const { reply } = await api.chatWithPredictor(message);

To run the agent locally with a real LLM, install Ollama and pull a model:

ollama serve
ollama pull llama3.1:8b

If Ollama isn't running, Blocks falls back to a canned provider that returns keyword-based mock responses. Zero config needed either way.

Scheduled tasks

AWS Blocks lets you write cloud functions that trigger on a schedule. For our app, an hourly job checks for new match results from a public API, updates the database, and refreshes the leaderboard:

new CronJob(scope, "results-sync", {
  schedule: "rate(1 hour)",
  description: "Check for finished matches and refresh the leaderboard.",
  handler: async (event) => {
    console.log(`[results-sync] triggered at ${event.scheduledTime}`);
    const summary = await syncMatchResultsFromFeed();
    const standings = await refreshLeaderboard();
    console.log(
      `[results-sync] done — checked ${summary.checked}, ` +
      `updated ${summary.updated}; leaderboard has ${standings.length} entries`
    );
  },
});

The handler fetches results from openfootball's World Cup JSON feed, matches them against our fixtures, writes scores to the database, and recomputes standings. Locally, the job runs synchronously in-process when triggered. On AWS, it becomes an EventBridge Scheduler + Lambda.

Running the app

npm run dev

Open http://localhost:3000. Sign up with a username and password. On first login, ensureSeeded() populates the database with all 48 teams, their 26-player rosters, and 88 group-stage matches. Start picking your bracket.

Mock data persists in .bb-data/ across dev server restarts. To reset everything: rm -rf .bb-data.

Deploying to AWS

When you're ready to go live:

npm run sandbox          # Ephemeral backend on AWS (2-3 minutes)
npm run deploy           # Production with S3 + CloudFront hosting
npm run sandbox:destroy  # Tear down when done

No AWS experience required. The same code you tested locally runs on DynamoDB, Lambda, API Gateway, AppSync, and CloudFront without changes.

Conclusion

We built a full-stack World Cup bracket picker with authentication, structured data, realtime updates, an AI agent, and scheduled background jobs. Every block ran locally with zero AWS credentials. The source code is on GitHub (full implementation on main, frontend-only starting point on mock).

To get started with AWS Blocks:

Building Serverless APIs with TDD and AI-Powered Spec Generation

Salih Guler — Thu, 16 Apr 2026 14:44:03 +0000

Test-Driven Development has been around for decades, but most teams still struggle to adopt it consistently. The biggest friction point? Writing specs and tests takes time, especially when you're dealing with the ambiguity of greenfield projects. You're not always sure what the requirements should be, what edge cases to cover, or how to structure your tests before you write the code.

This gets more complicated with serverless architectures. You're juggling Lambda functions, API Gateway configurations, database tables, and event-driven workflows. Traditional TDD assumes you're working in a monolithic environment where you can stub out dependencies easily. In serverless, your "dependencies" are managed AWS services with their own quirks, quotas, and failure modes.

What if you could use AI to generate comprehensive specifications from high-level requirements, then use those specs to drive your test creation and implementation? This is how spec-driven development with AI assistants changes how TDD works in practice.

The Problem with Traditional TDD in Serverless

Classic TDD follows a simple loop: write a failing test, write code to pass the test, refactor. This works when you know exactly what you're building. But in real projects, requirements are often vague: "Build an API that handles user registrations" doesn't tell you what fields are required, what validation rules apply, what error responses look like, or how you'll handle concurrent registrations.

You end up spending hours in planning meetings, writing detailed specification documents, or (more commonly) skipping specs entirely and letting the code become the specification. All three approaches have problems:

Planning meetings slow down development and documentation gradually becomes obsolete
Skipping specs means inconsistent implementations and missing edge cases
Code-as-specification makes onboarding painful and refactoring risky

Serverless adds another layer of complexity. You need to test that your Lambda function works, that API Gateway routes requests correctly, that DynamoDB handles your access patterns, that IAM permissions are configured properly, and that everything scales under load. Unit tests with mocks only get you so far. You need integration tests in the cloud to catch configuration issues, but those are slow and expensive to run constantly.

Spec-Driven Development: The Missing Layer

Spec-driven development sits between requirements and tests. You start with a formal specification that describes exactly what your system should do, including success cases, error conditions, data formats, and constraints. This spec becomes the contract that your code must fulfill.

The difference from traditional documentation is that specs are executable. You can generate tests from specs, validate implementations against specs, and use specs to generate API documentation or client SDKs automatically. OpenAPI is the most common example, but specs can be more detailed and include business logic constraints that OpenAPI doesn't capture.

Here's where AI comes in. Instead of manually writing specifications, you can use AI to generate comprehensive specs from natural language requirements. An AI assistant trained on API design patterns, AWS best practices, and your existing codebase can produce detailed specs that cover edge cases you might not think of.

Building a User Registration API with Specs

We'll create a Lambda-backed API for user registration.

Step 1: Generate the Specification with AI

Use an AI assistant (we will be using Kiro) to generate a formal specification from these requirements. Here's a prompt that works:

Given the following requirements for a serverless API endpoint, generate a comprehensive specification that includes:

1. OpenAPI schema with all request/response formats
2. Validation rules with specific regex patterns and constraints
3. Error scenarios with HTTP status codes and error formats
4. Concurrency handling strategy
5. Security considerations
6. DynamoDB table design for the data model

Requirements: Build a user registration endpoint that:
- Accepts email, password, and optional full name
- Validates email format and password strength
- Prevents duplicate registrations
- Returns a user ID on success
- Handles concurrent requests safely
- Logs failed attempts for security monitoring

Format the output as a structured JSON specification that can drive test generation.

This spec captures things you might not have specified in the original requirements: password regex pattern, exact error messages, the concurrency strategy using DynamoDB conditional writes, and a field for tracking registration attempts (useful for rate limiting).

# User Registration API Specification

## OpenAPI Schema

openapi: 3.0.3
info:
  title: User Registration API
  version: 1.0.0
paths:
  /register:
    post:
      operationId: registerUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Email already registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RegisterRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
        fullName:
          type: string
    RegisterResponse:
      type: object
      required: [userId, email, createdAt]
      properties:
        userId:
          type: string
          format: uuid
        email:
          type: string
        createdAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string
        fields:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              reason:
                type: string

## Validation Rules

### Email

| Rule ID | Constraint | Details |
|---------|-----------|---------|
| EMAIL_FORMAT | Regex pattern | `^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$` |
| EMAIL_LENGTH | Max length | 254 characters |
| — | Transform | Lowercase before storage and uniqueness check |

### Password

| Rule ID | Constraint | Details |
|---------|-----------|---------|
| PWD_MIN_LENGTH | Min length | 8 characters |
| PWD_MAX_LENGTH | Max length | 128 characters |
| PWD_UPPERCASE | Pattern | At least one uppercase letter |
| PWD_LOWERCASE | Pattern | At least one lowercase letter |
| PWD_DIGIT | Pattern | At least one digit |
| PWD_SPECIAL | Pattern | At least one special character |

Full pattern: `^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=\[\]{}|;:',.<>?/` `` `~])[A-Za-z\d!@#$%^&*()_+\-=\[\]{}|;:',.<>?/` `` `~]{8,128}$`

### Full Name (optional)

| Rule ID | Constraint | Details |
|---------|-----------|---------|
| NAME_FORMAT | Regex pattern | `^[\p{L}\s'.\-]{1,100}$` |
| NAME_LENGTH | Max length | 100 characters |

## Error Scenarios

| ID | HTTP Status | Code | Message | Trigger |
|----|------------|------|---------|---------|
| MISSING_EMAIL | 400 | VALIDATION_ERROR | Email is required | Missing email field |
| INVALID_EMAIL | 400 | VALIDATION_ERROR | Invalid email format | Email fails pattern |
| MISSING_PASSWORD | 400 | VALIDATION_ERROR | Password is required | Missing password field |
| WEAK_PASSWORD | 400 | VALIDATION_ERROR | Password does not meet strength requirements | Password fails strength rules |
| INVALID_NAME | 400 | VALIDATION_ERROR | Full name contains invalid characters | fullName fails pattern |
| INVALID_JSON | 400 | INVALID_REQUEST | Request body must be valid JSON | Malformed or non-JSON body |
| DUPLICATE_EMAIL | 409 | CONFLICT | An account with this email already exists | ConditionalCheckFailedException from DynamoDB |
| INTERNAL_ERROR | 500 | INTERNAL_ERROR | An unexpected error occurred | Unhandled exception or DynamoDB service error |

## Concurrency Handling

**Strategy:** DynamoDB conditional writes

- **Operation:** `PutItem` with `ConditionExpression: attribute_not_exists(pk)`
- **Partition key:** `USER#<normalized_email>` — the email itself is the uniqueness key
- **Behavior:** If two concurrent requests register the same email, exactly one succeeds (201) and the other receives a 409 (`ConditionalCheckFailedException`)
- **Retry policy:** No retry on `ConditionalCheckFailedException`; map directly to 409
- **Idempotency:** Not idempotent by design — repeated calls with the same email return 409 after first success

## Security Considerations

### Password Handling

- **Algorithm:** bcrypt, cost factor 12
- **Storage:** Store only the bcrypt hash, never plaintext
- **Input sanitization:** Reject null bytes in password input

### Rate Limiting

| Scope | Limit | Implementation |
|-------|-------|---------------|
| Per source IP | 10 requests/minute | API Gateway throttling |
| Global | 1000 requests/minute | API Gateway throttling |

### Failed Attempt Logging

| Event | Logged Data | Destination |
|-------|------------|-------------|
| DUPLICATE_EMAIL | Hashed email, source IP | CloudWatch Logs (structured JSON) |
| VALIDATION_ERROR | Error type, source IP | CloudWatch Logs (structured JSON) |
| INTERNAL_ERROR | Full error, correlation ID | CloudWatch Logs (structured JSON) |

- **Retention:** 90 days
- **Alerting:** CloudWatch alarm on >50 failed registrations per 5 minutes from same IP

### Transport & Headers

- HTTPS only (enforced at API Gateway)
- Max request body size: 10KB
- Response headers:
  - `Strict-Transport-Security: max-age=31536000; includeSubDomains`
  - `Content-Type: application/json`
  - `X-Content-Type-Options: nosniff`

## DynamoDB Table Design

**Table name:** `Users`
**Capacity mode:** PAY_PER_REQUEST
**Point-in-time recovery:** Enabled
**Encryption:** AWS_OWNED_KMS

### Key Schema

| Attribute | Type | Key | Format | Description |
|-----------|------|-----|--------|-------------|
| pk | S | HASH | `USER#<normalized_email>` | Partition key for uniqueness enforcement |

### Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| pk | S | `USER#user@example.com` |
| userId | S | UUIDv4 |
| email | S | Original email (lowercased) |
| passwordHash | S | bcrypt hash |
| fullName | S | Optional, omitted if not provided |
| createdAt | S | ISO 8601 timestamp |
| updatedAt | S | ISO 8601 timestamp |

### Global Secondary Index

| Index Name | Partition Key | Projection | Purpose |
|-----------|--------------|------------|---------|
| userId-index | userId (S) | ALL | Lookup user by UUID for downstream APIs |

## Test Matrix

### Happy Path

- Valid email + strong password → 201 with userId
- Valid email + strong password + fullName → 201 with userId
- Email with subaddressing (`user+tag@example.com`) → 201

### Validation Errors

- Missing email → 400 VALIDATION_ERROR
- Missing password → 400 VALIDATION_ERROR
- Invalid email format → 400 VALIDATION_ERROR
- Password too short → 400 VALIDATION_ERROR
- Password missing uppercase → 400 VALIDATION_ERROR
- Password missing lowercase → 400 VALIDATION_ERROR
- Password missing digit → 400 VALIDATION_ERROR
- Password missing special char → 400 VALIDATION_ERROR
- fullName with invalid chars → 400 VALIDATION_ERROR
- Empty request body → 400 INVALID_REQUEST
- Non-JSON body → 400 INVALID_REQUEST

### Duplicate Handling

- Register same email twice → first 201, second 409
- Register same email different case → 409 (normalization)

### Concurrency

- Two simultaneous registrations same email → exactly one 201, one 409
- Two simultaneous registrations different emails → both 201

### Security

- Password not returned in response body
- Password stored as bcrypt hash in DynamoDB
- Oversized request body → rejected
- Null bytes in password → rejected

This will create a logical structure like the following:

Step 2: Generate Tests from the Specification

Now use the spec to generate comprehensive tests. You can write Generate tests from the specs. Once they are generated run the tests, you should see tests are failing and indicating why are they failing as well:

Test Suites: 5 failed, 5 total
Tests:       21 failed, 1 passed, 22 total
Snapshots:   0 total
Time:        1.541 s, estimated 2 s
Ran all test suites.
 - Completed in 2.530s

> As expected — 21 of 22 tests fail with 501 (the stub's "Not implemented" 
response). The one passing test is "password not returned in response body" 
which trivially passes since the stub doesn't return any user data.

Summary:

| Suite | Tests | Failing |
|---|---|---|
| Happy Path | 3 | 3 |
| Validation Errors | 11 | 11 |
| Duplicate Handling | 2 | 2 |
| Concurrency | 2 | 2 |
| Security | 4 | 3 |
| Total | 22 | 21 |

Ready for the red → green cycle. Want me to start implementing the handler to make these pass?

These tests are comprehensive. They cover the happy path, all error scenarios from the spec, and even a concurrency test that sends two simultaneous requests.

Step 3: Implement to Pass the Tests

Now write the Lambda function to make these tests pass. It depends on you to either write them or allow AI to write it for you. Let's ask AI to write it:

> Implement everything needed to cover the specs.
... a few moments after implementation 

> All 22 tests green. Here's what was implemented:

- src/repository.ts — UserRepository interface with putUserIfNotExists contract, plus a setter/getter for dependency injection

- src/handler.ts — full handler with JSON parsing, body size check, email/password/name validation, bcrypt hashing, email normalization, and conditional put for duplicate prevention

- tests/helpers.ts — updated with an InMemoryUserRepository that mimics DynamoDB's conditional write behavior, beforeEach reset for test isolation, and getDynamoDBMock() for the bcrypt storage assertion

The real DynamoDB implementation can be swapped in later by calling setRepository() with a DynamoDB-backed class that uses attribute_not_exists(pk) on PutItem.

The implementation follows the spec exactly. The validation logic uses the regex patterns from the spec. Error responses match the error formats from the spec. e.g. you can see below, the concurrency handling uses DynamoDB conditional writes as specified:

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';
import type { UserRecord, UserRepository } from './repository';

export class DynamoDBUserRepository implements UserRepository {
  private readonly client: DynamoDBDocumentClient;
  private readonly tableName: string;

  constructor(tableName: string) {
    this.tableName = tableName;
    this.client = DynamoDBDocumentClient.from(new DynamoDBClient({}));
  }

  async putUserIfNotExists(user: UserRecord): Promise<boolean> {
    try {
      await this.client.send(
        new PutCommand({
          TableName: this.tableName,
          Item: user,
          ConditionExpression: 'attribute_not_exists(pk)',
        })
      );
      return true;
    } catch (err: unknown) {
      if (
        err instanceof Error &&
        err.name === 'ConditionalCheckFailedException'
      ) {
        return false;
      }
      throw err;
    }
  }
}

Deploy and Test in the Cloud

To deploy and test in the cloud, we will be asking to deploy the app with CDK. It will create the project and allows us to deploy to the cloud through CDK's CLI tools. Ask it to deploy the code and run tests on cloud.

> Everything is deployed and tested. Here's the summary:

Stack deployed: ServerlessTddStack in us-east-1
- API Gateway: 
https://62lf8w8qnk.execute-api.us-east-1.amazonaws.com/prod/register
- Lambda: Node 20, 256MB, esbuild-bundled
- DynamoDB: Users table with pk (HASH) + userId-index GSI, PAY_PER_REQUEST, 
PITR enabled

Test results:
- 22 unit tests ✅ (in-memory mock)
- 5 integration tests ✅ (live API)

Files added:
- src/dynamodb-repository.ts — real DynamoDB repo with conditional writes
- src/lambda.ts — Lambda entry point wiring the DynamoDB repo
- infra/stack.ts — CDK stack definition
- infra/app.ts — CDK app entry
- cdk.json — CDK config
- tests/integration.test.ts — live API tests
- jest.integration.config.js — integration test config

Commands:
- npm test — run unit tests
- 
API_ENDPOINT=https://62lf8w8qnk.execute-api.us-east-1.amazonaws.com/prod/register npm run test:integration
— run integration tests
- npm run destroy — tear down the stack

Testing in the cloud catches issues that local tests miss: IAM permission problems, DynamoDB throughput limits, API Gateway timeout configurations, and cold start behavior.

Handling Spec Evolution

Specs aren't static. Requirements change. When they do, regenerate the spec with AI, diff it against the current version, and update tests accordingly.

Update spec to give user an option to add a profile picture URL.

When you run the diff, you get a clear picture of what changed.

> Now I'll update the spec with the profile picture URL field across all 
relevant sections.
I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  57, 57:         fullName:
  58, 58:           type: string
+     59:         profilePictureUrl:
+     60:           type: string
+     61:           format: uri
  59, 62:     RegisterResponse:

Updating: docs/user-registration-spec.md
 - Completed in 0.1s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  116, 116: ### Full Name (optional)
  117, 117: 
  118, 118: | Rule ID | Constraint | Details |
  119, 119: |---------|-----------|---------|
  120, 120: | NAME_FORMAT | Regex pattern | `^[\p{L}\s'.\-]{1,100}$` |
  121, 121: | NAME_LENGTH | Max length | 100 characters |
+      122: 
+      123: ### Profile Picture URL (optional)
+      124: 
+      125: | Rule ID | Constraint | Details |
+      126: |---------|-----------|---------|
+      127: | PIC_URL_FORMAT | Regex pattern | `^https://[^\s]{1,2048}$` |
+      128: | PIC_URL_LENGTH | Max length | 2048 characters |
+      129: | PIC_URL_SCHEME | Scheme | Must be HTTPS only |

Updating: docs/user-registration-spec.md
 - Completed in 0.1s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  139, 139: | INVALID_NAME | 400 | VALIDATION_ERROR | Full name contains invalid characters | fullName fails pattern |
- 140     : | INVALID_JSON | 400 | INVALID_REQUEST | Request body must be valid JSON | Malformed or non-JSON body |
+      140: | INVALID_PROFILE_PIC_URL | 400 | VALIDATION_ERROR | Profile picture URL must be a valid HTTPS URL | profilePictureUrl fails pattern |
+      141: | INVALID_JSON | 400 | INVALID_REQUEST | Request body must be valid JSON | Malformed or non-JSON body |

Updating: docs/user-registration-spec.md
 - Completed in 0.1s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  211, 211: | fullName | S | Optional, omitted if not provided |
+      212: | profilePictureUrl | S | Optional, omitted if not provided |
  212, 213: | createdAt | S | ISO 8601 timestamp |

Updating: docs/user-registration-spec.md
 - Completed in 0.2s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  227, 227: - Valid email + strong password + fullName → 201 with userId
+      228: - Valid email + strong password + profilePictureUrl → 201 with userId
  228, 229: - Email with subaddressing (`user+tag@example.com`) → 201

Updating: docs/user-registration-spec.md
 - Completed in 0.1s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  241, 241: - fullName with invalid chars → 400 VALIDATION_ERROR
+      242: - profilePictureUrl with HTTP scheme → 400 VALIDATION_ERROR
+      243: - profilePictureUrl with invalid format → 400 VALIDATION_ERROR
  242, 244: - Empty request body → 400 INVALID_REQUEST

Updating: docs/user-registration-spec.md

According to your changes, you can add new test cases for added scenarios, remove obsolete tests, and update tests for changed behavior. This keeps your test suite and implementation synchronized with requirements.

Tradeoffs and When to Use a Different Approach

This mixture of AI and spec-driven approach works well for APIs with complex validation, multiple error conditions, and strict contracts (like public APIs or microservices with many consumers). It's less useful for experimental features where requirements are genuinely unknown.

If you're building a prototype to test a hypothesis, traditional TDD with minimal specs is faster. Write a few high-level tests, implement quickly, and iterate. Once the concept proves valuable, then formalize it with specs.

For workflows with complex business logic but simple I/O contracts, consider property-based testing instead. Tools like fast-check generate random inputs to find edge cases your specs might miss. Combine property tests with spec-driven tests for comprehensive coverage.

For systems with heavy external dependencies (third-party APIs, legacy services), mocks are unavoidable. But keep mocked tests separate from integration tests. Run mocked tests frequently during development for fast feedback. Run cloud integration tests before merging to catch configuration drift.

Making This Practical

To adopt spec-driven development in your team:

Start with one API or service, not the whole system
Use AI to generate initial specs, then review and refine them
Store specs in version control alongside code
Generate tests from specs, but also write additional tests for edge cases you discover
Make spec generation part of your development workflow, not a one-time task
Review spec diffs in pull requests just like code diffs

The goal is to make specifications a living part of your codebase, not documentation that falls out of date.

Cleaning Up Resources

When you're done experimenting, delete the CloudFormation stack:


cdk destroy

This removes the API Gateway, Lambda function, and DynamoDB table. Check the AWS Console to confirm no orphaned resources remain.

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.

DEV Community: Salih Guler

Making my personal website callable for AI agents with WebMCP

What is WebMCP?

The tools I added

Step 1: Bake an index at build time

Step 2: Register the tools only when the browser supports them

Step 3: Write descriptions for a model, and check every input

Step 4: Add a speaker kit

Step 5: Tell the humans too

Try it yourself

From the Chrome console

With the MCP Inspector

From Claude Code, Codex or Kiro CLI

With other agents

Resources

7 Tips to Make Your AI Agent More Predictable

#1 Talk to AI in Clear Prompts

Zero-Shot

Few-Shot

Chain-of-Thought

#2 Set Absolute Boundaries

Prioritize negative boundaries (Guardrails)

#3 Give Your AI Persistent Context

Always-loaded: Steering files

On-demand: Skills

Keep it lean

Separate context from instructions

#4 Manage Your Context Window

Context rot

Fighting context rot

#5 Follow a Spec-Driven Development Process

Frontend spec (from BUILD_PROMPT.md)

Backend spec (from MIGRATING_TO_CLOUD_PROMPT.md)

Writing good specs

#6 Use MCP to Extend AI Beyond Its Knowledge

#7 Know When to Vibe Code and When to Spec

Use vibe coding when:

Use Spec-Driven Development when:

Wrapping Up

Building an Agent Friendly Personal Website with Specs

Step 1: Get a design reference

Step 2: Write the specification

Agent Readiness

1. Discoverability

2. Content accessibility (markdown negotiation)

3. Bot access control

4. Protocol discovery

5. Commerce (intentionally empty)

Why this matters

Step 3: Plan and implement

Step 4: Import existing blog posts

Step 5: Polish

What we built

Open source and what's next

Building a Geography Game with a Custom Building Block with AWS Blocks

What we're building

Requirements

The 4-export pattern

Building the LocationMap block

types.ts

geocode.ts (shared logic)

mock.ts (local development)

aws.ts (deployed Lambda)

cdk.ts (infrastructure wiring)

browser.ts (types for the frontend)

package.json (wiring it together)

Wiring the block into the CDK stack

The game backend

Error handling

The offline map: local dev without internet

Running it

Deploying to AWS

Cleaning up

What you've learned

Building a World Cup Bracket Picker with AWS Blocks

Prerequisites

Getting ready

Authentication

Data

Realtime

Frontend spec (from `BUILD_PROMPT.md`)

Backend spec (from `MIGRATING_TO_CLOUD_PROMPT.md`)