Architecture

Connections

Every moving part of HomeMate, in plain language. No database, no external services — one agent, eight tools and your own household data.

Model connection

Credentials not set

Region: not set

Model: —

Credentials are read server-side only, inside the agent run handler. Nothing about AWS ever reaches the browser — the page above shows the region and model id only, and never the bearer token.

Missing: —. Copy .env.example to .env, fill it in and restart. Until then every local feature — tasks, routines, planning, conflicts and approvals — keeps working in Local Test Mode.

Request path

User
 ↓
HomeMate UI
 ↓
Strands Agent
 ↓
HomeMate Tools
 ↓
Household State
 ↓
Local Household Data

Model path

Strands Agent
 ↓
Amazon Bedrock
 ↓
Claude Model

Human in the loop

Agent decides action
 ↓
Is approval required?
 ├── No → execute
 └── Yes
       ↓
   Ask human
       ↓
   Approve / Reject
       ↓
   Continue / Cancel

The eight custom Strands tools

get_tasks

Reads the current household tasks, filtered by window or category.

create_task

Adds a new task with priority, effort, category and due date.

complete_task

Marks a task done and records who completed it.

reschedule_task

Moves a task to a new date; refuses and asks for approval when the move is risky.

create_routine

Adds a recurring household routine and computes its next due date.

create_weekly_plan

Builds a Monday–Sunday plan from real tasks and routines.

check_conflicts

Finds overloaded days, clashes and overdue work.

request_approval

Pauses the run with a Strands interrupt until the human decides.

How a run actually works

When you press Run, the browser hands its household state to a server function. The server builds a real Strands Agent with a Bedrock model provider and the eight tools bound to that state, then invokes it once.

The agent — not the app — decides which tools to call and in what order. Every tool call and result is logged to the timeline as it happens; nothing is invented for effect.

If a tool calls request_approval, Strands raises an interrupt. The run pauses, a snapshot is taken, and the approval appears in the Approvals page. Your decision is fed back into the same conversation so the agent continues exactly where it stopped.

The mutated household state travels back with the result and the browser persists it, so the agent and the human always work on the same records.

Safety, cost and privacy

The agent never runs on page load, on a timer, or on render — only when you ask.
Each run has a conservative tool-call ceiling and a wall-clock timeout.
The Run button is disabled while a run is active, so no duplicate submissions.
Failed model requests are surfaced, not silently retried.
Only a compact summary of your household is sent to the model.
Household data lives in your browser's storage. There is no database and no account.
AWS credentials are server-only environment variables, never VITE_ prefixed.