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.
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:
- No history at all → start at Easy. Cold-start default.
- 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.
- 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.
- 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
OPTIONSbranch is handled explicitly, before anything else. Browsers send a CORS "preflight"OPTIONSrequest before the realPOST, 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)rejects0,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 stackaws 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.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article