Runbook Relay

A voice runbook companion that helps IT technicians resume interrupted troubleshooting and hand over verified progress with clear next steps.

Comment

Inspiration

An interrupted troubleshooting session leaves a deceptively simple question: what has actually been checked? Chat history can contain suggestions, assumptions, and observations together. A person taking over needs a reliable record of the difference.

Runbook Relay explores that problem through a fictional meeting-room laptop that connects to Wi-Fi but cannot reach an internal service. The goal is to help a junior technician continue a runbook and prepare a useful handoff without turning an assistant's suggestion into established evidence.

What it does

Runbook Relay is a simulated Alexa+ web experience. A technician can ask what to check next, inspect the source runbook step, and report an observation through text or optional browser speech.

Each reported result becomes a review card. The technician can edit, confirm, or reject it. Until confirmation, the saved check stays unknown. The interface keeps confirmed results, pending proposals, and the versioned source instructions visible.

Pause the incident, refresh the page, and resume: the confirmed evidence remains available. A Markdown handoff includes recorded observations, failed checks, pending-review counts, and checks that remain unknown. It can be edited and downloaded. A DNS failure remains an observation to investigate; the application does not declare it the root cause.

How it was built

The interface uses React, TypeScript, and Vite. A Node.js and Express API owns incident state and validates requests with Zod.

The AWS implementation uses Amazon Bedrock's Converse API with the Nova Lite APAC inference profile, through AWS SDK for JavaScript v3. The assistant can request five application tools: read the runbook, read the incident, propose a result, summarize saved progress, and request a handoff. Tool use is bounded, source IDs are validated, and a model request cannot confirm a check.

The main handoff endpoint generates its Markdown deterministically from saved records. Bedrock provides interpretation and runbook guidance; it does not invent the handoff's evidence. DynamoDB conditional writes check incident revisions to prevent stale updates. Private browser session tokens restrict access to each incident, while AWS credentials remain on the server.

Deployment code packages the application for Node.js 24 on AWS Lambda, provisions its resources with CloudFormation, and serves the interface and API from one HTTPS origin. A separate, visibly labeled local demo mode uses scripted guidance and a durable JSON file. Bedrock failures never silently switch to demo mode.

Challenges and engineering lessons

The central challenge was preserving the difference between a proposed outcome and a confirmed observation across chat, reloads, and handoffs. Staging model actions until a valid response, then requiring a separate confirmation endpoint, made that boundary testable.

Integration also required selecting an available inference profile, matching the serverless adapter's Node.js requirement, and adjusting the artifact-upload endpoint for this environment. The friction log records these details without presenting environment restrictions as AWS service defects.

Verification and next steps

Fourteen backend tests cover confirmation, rejection, duplicate requests, concurrency, ownership, persistence, bounded tool use, and failure rollback. Two browser tests cover the complete local workflow and mobile layout. Eleven live checks also passed against the hosted Lambda application using its real Bedrock and DynamoDB integrations, including proposal/confirmation separation, duplicate confirmations, access denial, stale revisions, pause/resume, and an honest handoff.

The prototype uses one synthetic runbook. It executes no diagnostics and has no native Alexa device integration. Speech depends on browser support. Next steps include more runbooks, organization identity, and evaluation with technicians using consented, non-sensitive scenarios.

Built With

Share this project:

Updates