Architecture

Architecture

The television renders and never decides. The edge authenticates and answers Ring within its five-second budget. The agents do the reasoning. The family reaches everything through one server that checks, on every call, that she still allows them.

The shape of it

flowchart LR
    subgraph clients["Clients"]
        tv["Television<br/>Vega, Fire OS, browser"]
        ringapi["Ring Partner API"]
        app["Family app<br/>S3 + CloudFront"]
    end

    subgraph edge["Edge"]
        channels["Television channels<br/>IoT Core MQTT, or<br/>API Gateway WebSocket"]
        http["API Gateway HTTP<br/>Ring webhook, pairing"]
    end

    subgraph agentplane["Agent plane"]
        bus["EventBridge"]
        fns["Door, card-action,<br/>narrator Lambdas"]
        core["AgentCore Runtime<br/>Strands graphs"]
        egress["egress.ts"]
    end

    subgraph server["Wick server, App Runner"]
        mcp["MCP, OAuth 2.1,<br/>family API, assistant"]
        guardian["Guardian"]
    end

    subgraph memory["Memory"]
        ddb[("DynamoDB")]
        s3[("S3")]
        secrets["Secrets Manager"]
    end

    tv <--> channels
    ringapi --> http
    channels --> bus
    http --> bus
    bus --> fns
    fns --> core
    fns --> egress
    egress --> channels
    fns --> memory
    app --> mcp
    mcp --> guardian
    mcp --> memory

Loading

What happens when the doorbell rings

1. Ring posts a signed webhook to API Gateway. It is verified with an HMAC and made idempotent.
2. The event goes on the EventBridge bus wick, carrying a correlationId that follows it all the way to the television and back.
3. The door agent puts a card on her television straight away, in about two seconds, then fetches the picture.
4. A Strands graph in AgentCore Runtime describes the picture in one sentence with Amazon Nova Lite. If the model is unsure, the sentence is left out. Silence beats a wrong description.
5. The picture and the sentence follow on the same card. The only way a card leaves the cloud is egress.ts, which sends it down whichever channel her television is on.
6. She presses one of at most three buttons. Ask Sarah to look shows Sarah the same picture, and only then.

The television

Vega OS app	React Native for Vega, in apps/tv-vega. A headless service shows the door over other apps with a system toast, media controls make a platform pause count as a natural break, and w3cmedia plays the films and the door's live view.
Fire OS	The same source through four small adapters, in apps/tv-fireos. An Android foreground service handles the door, and her film is Android's MediaSession, so "Alexa, pause" goes through the same rules.
Browser television	apps/ops-console runs the same cards and break rules in a browser tab. It is built from the Vega app's own source, so the two cannot drift, and it reaches home the same way: IoT Core first, the WebSocket behind it.
Two channels	MQTT over AWS IoT Core, and an API Gateway WebSocket as the fallback. Both are tried every time the app starts. Both have a heartbeat, and the screen says plainly when Wick cannot reach home.

The agent plane

Agent	Trigger	Does	Model
Door	A Ring event, or a demo home's stand-in ring	The card, then picture and sentence; roster match by schedule; Ask Sarah to look	Nova Lite
Narrator	Every Sunday	Counts the week, compares it with the household's own baseline, writes prose from those numbers	Claude Sonnet 4.5
Tell	An unusual day	Asks "Shall I tell Sarah?"; only Tell makes it readable	none
Visit	Door sightings of a regular visitor	Asks "Is this right?"; only her Yes confirms	none
Reach	Her press on "Ask Sarah to ring you?"	Asks one person, then the next after three minutes	none
Family assistant	A family member's question	A Strands agent that calls Wick's own MCP tools with the member's own token and asks before every write	Claude Sonnet 4.5
Visit errand	arrange_visit	One Step Functions execution that runs for days: reminds her, waits for the doorbell, tells the member	none
Sunday brief	Every Sunday, one SQS message per home	A Strands Graph: analyst, writer, check, suggester	Claude Sonnet 4.5

A Bedrock Guardrail (denied topics, PII, contextual grounding against the counted facts) checks the assistant and the brief. No model runs inside a tool.

The Wick server

One container on App Runner. It holds the MCP endpoint, its own OAuth 2.1 authorization server, the family app's API, the assistant and the Guardian. It is stateless: each request gets a server for the person its token names.

• MCP 2025-11-25 over Streamable HTTP.
• Dynamic client registration, PKCE, and tokens bound to this server (RFC 8707). Amazon Cognito decides who someone is.
• Every tool declares an output schema, and a write sent twice acts once.
• Every tool runs inside gated: the household comes from the token and her allowance is checked on every call.

Data

One DynamoDB table named wick holds everything. A household's rows share a partition, which is what makes withdrawal one clean sweep. Door pictures and readings live in S3 with one-day lifecycle rules enforced by the bucket itself, and each household's Ring tokens are a secret of their own.

Where things live in the repository

apps/tv-vega           Vega OS app: cards, player, natural-break engine, headless services
apps/tv-fireos         The same app on Fire OS
apps/sim-alexa         The family app, a simulated Alexa+ surface
apps/ops-console       Her television in a browser tab
services/edge-ring     Ring webhook receiver
services/edge-device   The television's channels: IoT Core and WebSocket
services/mcp-server    MCP server, OAuth, accounts and the family app's API
services/agent         Agents, Strands graphs, the live-view bridge
services/policy        The Guardian
packages/contracts     Types and rules shared by every part
packages/vega-calm-ui  Accessible 10-foot components, also on npm
packages/strands-agentcore-session   AgentCore Memory session storage for Strands TS
addon-package          The Alexa+ add-on manifest
infra                  Terraform

The complete design, with the reasoning behind each choice, is the technical document.