AWS Builder Center

AWS Service Detective: A Complete Architecture & Code Walkthrough

AWS Service Detective Game - A step-by-step guide of how I built this app last week for the builder challenge.

Cloud Data Engineer
This tutorial breaks down exactly how AWS Service Detective Game works — from the static HTML game a browser loads, through the serverless agent that writes new mysteries every day, to the feedback loop that adjusts difficulty based on how you play. Every code snippet below is pulled directly from the deployed project, not simplified for the tutorial.
By the end, you'll understand not just what each piece does, but why it's built the way it is — including a few decisions that only make sense once you've seen what happens without them.



1. Architecture at a glance


The system has three independent loops that only talk to each other through S3:
Loop
Trigger
What it does
Generation
EventBridge Scheduler, once daily
Agent picks a service + difficulty, asks Bedrock to write clues, saves the result
Play
A visitor opens the site
Static HTML fetches today's JSON challenge and runs the game client-side
Feedback
A mystery ends (solved or not)
Browser POSTs the outcome; tomorrow's generation run reads it to adjust difficulty
No server is ever "on." Between scheduled runs, nothing is executing — the site is flat files in S3, and the two Lambda functions only spend money when they're actually invoked.



2. The frontend

 aws-service-detective.html  is a single self-contained file — HTML, CSS, and JavaScript in one document, no build step, no framework. That's a deliberate choice: it means "deploying an update" is just  aws s3 cp .

2.1 How it finds today's mystery

On page load, before the player does anything, the script fetches the challenge JSON that the agent wrote to the same S3 bucket the site lives in:
fetch('data/todays-challenge.json', { cache: 'no-cache' })
.then(res => {
if(!res.ok) throw new Error('No mystery file yet');
return res.json();
})
.then(payload => {
const valid = payload && payload.service && Array.isArray(payload.clues)
&& payload.clues.length === 3 && payload.explanation && payload.difficulty;
if(!valid) throw new Error('Malformed mystery payload');

mystery = payload;
dailyTile.disabled = false;
})
.catch(() => {
dailyDesc.textContent = "Today's mystery isn't ready yet — check back after the daily generator runs.";
dailyTile.disabled = true;
});

Two things worth noticing here:
  • It validates the shape of the data, not just that the fetch succeeded. If the agent ever writes something malformed (a bug, a truncated Bedrock response, a partial S3 write), the frontend fails gracefully — the tile just stays disabled with an honest message — instead of throwing a JavaScript error mid-game.
  • The  .catch()  covers the very first day, before the schedule has ever fired. There's no challenge file yet, and that's an expected, handled state, not an error condition.

2.2 The guessing loop

Once a player opens the mystery, the client keeps a tiny state machine:
const mysteryState = { clueIndex: 0, solved: false, revealed: false };

Each wrong guess reveals the next clue and re-renders:
function submitMysteryGuess(){
if(mysteryState.solved || mysteryState.revealed) return;
const guess = mysteryInputEl.value;
if(!guess.trim()) return;

if(normalizeGuess(guess) === normalizeGuess(mystery.service)){
finishMystery(true);
return;
}

if(mysteryState.clueIndex < 2){
mysteryState.clueIndex += 1;
renderMysteryClues();
mysteryFeedbackEl.textContent = 'Not quite — clue ' + (mysteryState.clueIndex+1) + ' revealed.';
} else {
finishMystery(false);
}
}

Guesses are normalized before comparison so "s3", "S3", and "Amazon S3" all match:
function normalizeGuess(s){
return s.toLowerCase().trim()
.replace(/^aws\s+/, '').replace(/^amazon\s+/, '')
.replace(/[^a-z0-9 ]/g, '');
}


2.3 Reporting the result back

This is the piece that turns a static quiz into part of an adaptive system. When a mystery ends — solved or given up on — the client posts the outcome to an API endpoint before showing the explanation:
function finishMystery(didSolve){
mysteryState.solved = didSolve;
...
const cluesUsed = didSolve ? (mysteryState.clueIndex + 1) : 3;
postMysteryResult(didSolve, cluesUsed);
...
}

function postMysteryResult(solved, cluesUsed){
if(!API_ENDPOINT || API_ENDPOINT.indexOf("PLACEHOLDER") !== -1) return;
if(!mystery || !mystery.date) return;
fetch(API_ENDPOINT, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
date: mystery.date,
difficulty: mystery.difficulty,
solved: solved,
cluesUsed: cluesUsed
})
}).catch(() => { /* non-blocking — gameplay doesn't depend on this succeeding */ });
}

Notice the  .catch(() => {})  with no handling at all. That's intentional: this network call is a side effect, not a dependency. If it fails — the API is down, the player is offline, anything — the game itself must keep working exactly as if nothing happened. Never let a "nice to have" telemetry call block or break the core experience.



3. Infrastructure as code

Everything AWS-side is defined in  cfn-template.yaml  — one template, one  aws cloudformation deploy , the whole stack. Let's walk it resource by resource, grouped by the job each group does.

3.1 The static site itself

WebsiteBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Ref BucketName
PublicAccessBlockConfiguration:
BlockPublicAcls: false
IgnorePublicAcls: false
BlockPublicPolicy: false
RestrictPublicBuckets: false
WebsiteConfiguration:
IndexDocument: !Ref IndexDocument
ErrorDocument: !Ref IndexDocument

WebsiteBucketPolicy:
Type: AWS::S3::BucketPolicy
Properties:
Bucket: !Ref WebsiteBucket
PolicyDocument:
Statement:
- Sid: PublicReadGetObject
Effect: Allow
Principal: '*'
Action: s3:GetObject
Resource: !Sub 'arn:aws:s3:::${WebsiteBucket}/*'

One bucket does double duty as both the website host and the agent's data store —  todays-challenge.json ,  history.json ,  performance.json , and dated archives all live under a  data/  prefix in the same bucket. That's why the bucket policy grants public  GetObject  on everything: the game's JavaScript needs to read  data/*  just like it reads the HTML.

3.2 The agent's execution role — and why it has four Bedrock ARNs

ChallengeAgentExecutionRole:
Type: AWS::IAM::Role
Properties:
Policies:
- PolicyName: InvokeBedrockAndWriteChallenge
PolicyDocument:
Statement:
- Sid: InvokeBedrockInferenceProfile
Effect: Allow
Action: bedrock:InvokeModel
Resource:
- !Sub 'arn:aws:bedrock:${AWS::Region}:${AWS::AccountId}:inference-profile/${BedrockModelId}'
- !Sub 'arn:aws:bedrock:us-east-1::foundation-model/${BedrockBaseModelId}'
- !Sub 'arn:aws:bedrock:us-east-2::foundation-model/${BedrockBaseModelId}'
- !Sub 'arn:aws:bedrock:us-west-2::foundation-model/${BedrockBaseModelId}'
- Sid: ReadWriteChallengeData
Effect: Allow
Action: [s3:GetObject, s3:PutObject]
Resource: !Sub 'arn:aws:s3:::${WebsiteBucket}/data/*'

This looks over-provisioned at first glance — why four ARNs for one model? Because  claude-sonnet-4-6  can only be invoked through a cross-region inference profile, not its bare model ID. A profile like  us.anthropic.claude-sonnet-4-6  can route the actual request to the underlying foundation model in any of several US regions, so the IAM role needs  InvokeModel  rights on the profile and on the foundation model in each region it might land in. Grant only the profile ARN and you'll get an  AccessDeniedException  the first time AWS routes your request somewhere you didn't anticipate.

3.3 The Lambda function — and the packaging detail that matters

ChallengeAgentFunction:
Type: AWS::Lambda::Function
Properties:
Runtime: python3.12
Handler: lambda_function.handler
Role: !GetAtt ChallengeAgentExecutionRole.Arn
Timeout: 60
Environment:
Variables:
BUCKET_NAME: !Ref WebsiteBucket
OBJECT_KEY: data/todays-challenge.json
HISTORY_KEY: data/history.json
PERFORMANCE_KEY: data/performance.json
MODEL_ID: !Ref BedrockModelId
LOOKBACK_DAYS: '5'
Code: lambda_function.py

That last line —  Code: lambda_function.py  — is a local file path, not an S3 location. CloudFormation can't deploy a local file directly; this only works because deployment goes through  aws cloudformation package  first, which zips the file, uploads it to a staging bucket, and rewrites this property to a real  S3Bucket / S3Key  pair before  deploy  ever runs. You can see the result of that rewrite in  packaged-template.yaml :
Code:
S3Bucket: detective-artifacts-1787370476
S3Key: 09c1e18dcd2396c28f09142df9a54e7c

The reason this two-step process exists at all: CloudFormation's inline code option ( ZipFile:  directly in the template) has a hard 4KB limit. This function's code — with validation logic, history-reading, and a Bedrock tool schema — is well over 8KB. Past that size, packaging isn't optional.

3.4 The schedule

DailyChallengeSchedule:
Type: AWS::Scheduler::Schedule
Properties:
ScheduleExpression: !Ref DailyScheduleExpression # cron(0 6 * * ? *)
Target:
Arn: !GetAtt ChallengeAgentFunction.Arn
RoleArn: !GetAtt SchedulerExecutionRole.Arn

EventBridge Scheduler needs its own IAM role — separate from the Lambda's own execution role — because the caller (the scheduler service) and the function (the Lambda) have different trust relationships.  SchedulerExecutionRole  only grants one permission:  lambda:InvokeFunction  on this specific function ARN. It can't do anything else, which limits the blast radius if that role were ever misused.

3.5 Alerting

AgentErrorAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
Namespace: AWS/Lambda
MetricName: Errors
Dimensions:
- Name: FunctionName
Value: !Ref ChallengeAgentFunction
Statistic: Sum
Period: 86400 # 24 hours, not the usual 60-300 seconds
EvaluationPeriods: 1
Threshold: 1
TreatMissingData: notBreaching

Two settings here are non-default on purpose.  Period: 86400  (24 hours) matches the fact that this function only runs once a day — a normal 5-minute alarm window would almost always show zero invocations and tell you nothing.  TreatMissingData: notBreaching  matters for the same reason: on a day where the schedule simply hasn't fired yet, there's no metric data at all, and the alarm shouldn't interpret silence as failure.

3.6 The feedback API

ResultApi:
Type: AWS::ApiGatewayV2::Api
Properties:
ProtocolType: HTTP
CorsConfiguration:
AllowOrigins: ['*']
AllowMethods: ['POST', 'OPTIONS']
AllowHeaders: ['Content-Type']

ResultApiRoute:
Type: AWS::ApiGatewayV2::Route
Properties:
RouteKey: 'POST /result'
Target: !Sub 'integrations/${ResultApiIntegration}'

This is an HTTP API, not a REST API — API Gateway's newer, cheaper, simpler variant, appropriate here because there's exactly one route and no need for request validators, usage plans, or the rest of REST API's feature set. The  CorsConfiguration  block is what lets a browser on the S3 website domain successfully call an API Gateway domain — without it, the browser's own same-origin policy would silently block the request before it ever reached Lambda.



4. The daily agent

 lambda_function.py  is the heart of the project. Its docstring states the workflow directly:
wake up -> check recent challenges -> choose service -> choose difficulty
-> generate 3 clues (Bedrock) -> validate -> save challenge -> go back to sleep

Let's walk through each step as it appears in  handler() :
def handler(event, context):
today = datetime.date.today().isoformat()

history = _load_history()
recent = _recent_services(history)
performance = _load_performance()

difficulty = _choose_difficulty(performance)
service = _choose_service(difficulty, recent)

mystery = _generate_clues(service, difficulty)
_validate(service, mystery)

challenge = {
"date": today, "service": service, "difficulty": difficulty,
"clues": mystery["clues"], "explanation": mystery["explanation"],
}

_save(challenge, history)

return {"statusCode": 200, "date": today, "service": service, "difficulty": difficulty}


4.1 The most important design decision in the whole project

Notice that  service  and  difficulty  are chosen before Bedrock is ever called. The model never picks which AWS service the mystery is about — it only writes creative text (clues and an explanation) for a service the code already selected.
SERVICE_POOL = {
"easy": ["Amazon S3", "Amazon EC2", "AWS Lambda", ...],
"medium": ["AWS CloudFormation", "Amazon SQS", ...],
"hard": ["AWS Direct Connect", "Amazon Comprehend", ...],
}

This is a trust-boundary decision, not a technical limitation. LLMs are excellent at generating plausible, well-written text — and exactly as capable of confidently inventing a service name that doesn't exist, or misspelling a real one. By keeping the facts in a curated, hand-verified pool and reserving Bedrock's role for language, the system's correctness no longer depends on the model's memory of the AWS service catalog. It only depends on the model's ability to write three good sentences about a service you already told it, which is a much easier bar to guarantee and, importantly, to validate afterward.

4.2 Avoiding repeats: the history check

def _recent_services(history):
cutoff = datetime.date.today() - datetime.timedelta(days=LOOKBACK_DAYS)
recent = set()
for e in history.get("entries", []):
if datetime.date.fromisoformat(e["date"]) >= cutoff:
recent.add(e["service"])
return recent

def _choose_service(difficulty, recent):
pool = [s for s in SERVICE_POOL[difficulty] if s not in recent]
if not pool:
pool = SERVICE_POOL[difficulty] # tier exhausted — allow repeats rather than fail
return random.choice(pool)

 history.json  keeps a rolling log of which service ran on which day.  _choose_service  filters the difficulty's pool down to services not seen in the last  LOOKBACK_DAYS  (5, by default) — but if that filter would leave an empty list (every service in a 10-item pool played within 5 days), it falls back to the full pool rather than throwing an error. A slightly-too-soon repeat is a better failure mode than the daily mystery not generating at all.

4.3 The adaptive difficulty rule

def _choose_difficulty(performance_entries):
if not performance_entries:
return "easy"

last = performance_entries[-1]
idx = TIERS.index(last["difficulty"]) if last.get("difficulty") in TIERS else 0

if not last.get("solved"):
return TIERS[max(0, idx - 1)]

last_three = performance_entries[-3:]
if len(last_three) == 3 and all(
e.get("solved") and e.get("cluesUsed") == 1 for e in last_three
):
return TIERS[min(len(TIERS) - 1, idx + 1)]

return TIERS[idx]

Read top to bottom, this is a strict priority order:
  1. No history at all → start at Easy. Cold-start default.
  1. Yesterday went unsolved through all 3 clues → step down a tier immediately. This check runs first and overrides everything else — one bad day is enough to ease off, regardless of any earlier streak.
  1. The last three mysteries were each solved on the very first clue → step up a tier. This requires three data points, not just one, so a single lucky guess doesn't overcorrect the difficulty.
  1. Anything else (solved, but not on a 3-in-a-row first-clue streak) → hold the current tier.
 TIERS[max(0, idx - 1)]  and  TIERS[min(len(TIERS) - 1, idx + 1)]  are the clamps —  ["easy", "medium", "hard"]  can't step below index 0 or above index 2, so the difficulty never goes out of bounds no matter how long a win or loss streak runs.

4.4 Getting structured output from Bedrock

TOOL_SCHEMA = {
"name": "submit_mystery",
"input_schema": {
"type": "object",
"properties": {
"clues": {"type": "array", "items": {"type": "string"}, "minItems": 3, "maxItems": 3},
"explanation": {"type": "string"},
},
"required": ["clues", "explanation"]
}
}

response = bedrock.invoke_model(
modelId=MODEL_ID,
body=json.dumps({
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 1000,
"tools": [TOOL_SCHEMA],
"tool_choice": {"type": "tool", "name": "submit_mystery"},
"messages": [{"role": "user", "content": prompt}],
}),
)

payload = json.loads(response["body"].read())
for block in payload.get("content", []):
if block.get("type") == "tool_use" and block.get("name") == "submit_mystery":
return block["input"]

This uses tool-use (function calling) rather than asking the model to "return JSON" in plain prose. The difference matters in practice: a text-based JSON request occasionally comes back wrapped in a markdown code fence, or with a sentence of preamble before the  { , which then needs regex or string-stripping to recover.  tool_choice: {"type": "tool", ...}  forces the model to respond through the structured tool-call mechanism instead, so  block["input"]  is already a parsed dict matching the schema — no text-parsing fragility at all.

4.5 Validating what comes back

def _validate(service, mystery):
clues = mystery.get("clues", [])
if len(clues) != 3 or any(not c or not c.strip() for c in clues):
raise ValueError("Clues missing or malformed")

bare_name = service.lower().replace("aws ", "").replace("amazon ", "")
for c in clues[:2]:
if bare_name in c.lower():
raise ValueError(f"Service name leaked early: {c}")

if not mystery.get("explanation", "").strip():
raise ValueError("Missing explanation")

Even with tool-use guaranteeing the shape (three strings, one explanation string), nothing guarantees the content is good. This check catches the two failure modes that actually matter for gameplay: empty/missing text, and the model accidentally giving away the answer in clue 1 or 2 (checked as a simple substring match against the service name with "AWS"/"Amazon" stripped off). If validation raises, the Lambda invocation fails loudly — which is exactly what the CloudWatch alarm from section 3.5 is watching for.

4.6 Saving state for tomorrow

def _save(challenge, history):
today = challenge["date"]
s3.put_object(Bucket=BUCKET, Key=CHALLENGE_KEY, Body=json.dumps(challenge), ...)
s3.put_object(Bucket=BUCKET, Key=f"{ARCHIVE_PREFIX}{today}.json", Body=json.dumps(challenge), ...)

history.setdefault("entries", []).append({
"date": today, "service": challenge["service"], "difficulty": challenge["difficulty"]
})
history["entries"] = history["entries"][-HISTORY_MAX:]
s3.put_object(Bucket=BUCKET, Key=HISTORY_KEY, Body=json.dumps(history), ...)

Three writes, three different jobs:  todays-challenge.json  is the current mystery the frontend reads;  archive/<date>.json  is a permanent dated copy (useful for a future "past mysteries" feature, or just an audit trail);  history.json  is the rolling dedup log, trimmed to the last  HISTORY_MAX  entries so it never grows unbounded.



5. Closing the loop

 record_result.py  is intentionally the smallest piece of the system — one job, done defensively.
def handler(event, context):
method = event.get("requestContext", {}).get("http", {}).get("method", "")
if method == "OPTIONS":
return _response(200, {"ok": True})

payload = json.loads(event.get("body") or "{}")

date = payload.get("date")
difficulty = payload.get("difficulty")
solved = payload.get("solved")
clues_used = payload.get("cluesUsed")

valid = (
isinstance(date, str) and date
and difficulty in ("easy", "medium", "hard")
and isinstance(solved, bool)
and clues_used in (1, 2, 3)
)
if not valid:
return _response(400, {"error": "missing or invalid fields"})

A few things worth calling out:
  • The  OPTIONS  branch is handled explicitly, before anything else. Browsers send a CORS "preflight"  OPTIONS  request before the real  POST , and it carries no body — trying to parse JSON out of it first would throw before ever reaching the CORS logic.
  • Every field is type- and range-checked, not just "present."  clues_used in (1, 2, 3)  rejects  0 ,  4 ,  "1"  (a string), or anything else a buggy or malicious client might send — because this data feeds directly into next-day's difficulty decision, garbage here would silently corrupt the agent's judgment for days.
The write itself de-duplicates by date, which matters because network retries happen:
entries = [e for e in entries if e.get("date") != date]
entries.append({"date": date, "difficulty": difficulty, "solved": solved, "cluesUsed": clues_used})
entries = entries[-MAX_ENTRIES:]

If the browser's  fetch()  succeeds on the server side but the response is lost in transit (flaky wifi, a closed tab), a naive retry would double-count that day's result. Filtering out any existing entry for the same date before appending makes a second POST for the same day idempotent — the second write simply replaces the first, rather than adding a duplicate.



6. Deploying the website

aws s3 mb s3://my-deploy-artifacts-bucket

aws cloudformation package \
--template-file cfn-template.yaml \
--s3-bucket my-deploy-artifacts-bucket \
--output-template-file packaged-template.yaml

# Deploy the actual stack
aws cloudformation deploy \
--template-file packaged-template.yaml \
--stack-name aws-service-detective \
--parameter-overrides \
BucketName=my-unique-bucket-name \
BedrockModelId=us.anthropic.claude-sonnet-4-6 \
BedrockBaseModelId=anthropic.claude-sonnet-4-6 \
AlertEmail=you@example.com \
--capabilities CAPABILITY_IAM

aws s3 cp aws-service-detective.html s3://my-unique-bucket-name/aws-service-detective.html \
--content-type text/html --cache-control no-cache

 package  and  deploy  are two distinct steps because they solve two different problems:  package  gets your local code into S3 where CloudFormation can reference it;  deploy  applies the template against your account. Running  deploy  alone, pointed at a template that still has local  Code: lambda_function.py  paths, fails outright — CloudFormation has no way to read your laptop's filesystem.
One easy-to-miss step: any time you change a parameter's default in the template,  deploy  won't pick it up automatically on an existing stack — it reuses whatever value was last set unless you pass it again explicitly in  --parameter-overrides . Worth keeping every parameter you care about in one script or Makefile target, rather than relying on memory for which ones changed since the last deploy.



7. A day in this game

Tracing one full 24-hour cycle end to end, with the actual data shapes involved:
06:00 UTC — EventBridge Scheduler fires. Invokes  ChallengeAgentFunction  with an empty event payload — this Lambda doesn't need any input, everything it needs comes from S3 and its own environment variables.
Inside the Lambda:
_load_history() -> {"entries": [{"date": "2026-08-21", "service": "AWS Glue", "difficulty": "medium"}, ...]}
_load_performance() -> {"entries": [{"date": "2026-08-21", "difficulty": "medium", "solved": true, "cluesUsed": 1}, ...]}
_choose_difficulty() -> "medium" (held steady — not 3-in-a-row on clue 1 yet)
_choose_service() -> "Amazon ECS" (medium tier, not used in last 5 days)
_generate_clues() -> Bedrock tool-use call, returns {clues: [...], explanation: "..."}
_validate() -> passes
_save() -> writes 3 objects to S3

That final  _save()  call is what produced the actual output we captured from a real invoke:
{"statusCode": 200, "date": "2026-08-22", "service": "Amazon ECS", "difficulty": "medium"}

Any time after 06:00 — a player opens the site. Browser fetches  data/todays-challenge.json , gets the Amazon ECS mystery, plays through it.
The moment the mystery ends. Browser POSTs  {"date": "2026-08-22", "difficulty": "medium", "solved": true, "cluesUsed": 1}  to the API Gateway endpoint.  record_result.py  validates it, de-dupes by date, appends it to  performance.json .
06:00 UTC the next day. The cycle repeats — except now  _load_performance()  sees this new entry as the most recent one. If the last three entries (today's and the two before it) were all  solved: true, cluesUsed: 1 , tomorrow's mystery steps up to Hard.



8. Troubleshooting reference

A few failure modes that look alarming but have simple, known causes:
Symptom
Cause
Fix
ValidationException: ... on-demand throughput isn't supported
Bare model ID used instead of an inference profile
Use us.anthropic.claude-sonnet-4-6, not anthropic.claude-sonnet-4-6
AccessDeniedException on InvokeModel, resource matches your policy exactly
IAM propagation lag right after a policy update
Wait 30–60 seconds and retry
ResourceNotFoundException: Model use case details have not been submitted
One-time Anthropic use-case form not yet filled out for this AWS account
Bedrock console → Model catalog → select the model → submit the form
AccessDeniedException mentioning aws-marketplace:Subscribe
Model is Marketplace-fulfilled and needs a one-time subscription trigger
Invoke the model once from the Bedrock console Playground as an admin
Deploy runs, but the Lambda still uses an old parameter value
deploy doesn't apply new template defaults to existing stacks unless the parameter is passed explicitly
Always pass every parameter you care about in --parameter-overrides
Unable to upload artifact ... refers to a file that does not exist
record_result.py or lambda_function.py isn't in the same directory as the template
Confirm all source files are saved locally before running package
"Today's mystery isn't ready yet" never goes away
The schedule hasn't fired since deploy, or the Lambda errored
Manually invoke: aws lambda invoke --function-name <name> out.json && cat out.json


That's the complete system — three loops, four AWS compute resources, one S3 bucket doing double duty as both a website and a database, and a handful of hard-won lessons about what "serverless" actually means in practice: nothing running, and nothing simple about getting there the first time.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article