Architecture

Active path

flowchart LR
  browser[React and Vite] --> cf[CloudFront]
  cf --> frontend[Private S3 frontend]
  browser --> api[API Gateway HTTP API]
  api --> lambda[Lambda and FastAPI]
  subgraph crdb[CockroachDB Cloud]
    state[Durable learner state]
    dvi[DVI vector index]
  end
  lambda --> state
  lambda --> dvi
  lambda --> mcp[Managed MCP read-only]
  lambda --> llm[OpenRouter chat and embeddings]
  lambda --> artifacts[Private versioned S3]
  browser --> whisper[Client Whisper Worker]

Authority

Area	System of record	Rule
Learner state	CockroachDB Cloud	Events and projections are transactional.
Similarity retrieval	DVI	Retrieval is filtered and does not replace memory state.
Context retrieval	Managed MCP	The application uses read-only allowlisted operations.
Inference	OpenRouter	Output is parsed and validated before use.
Passport artifact	Versioned S3	The manifest records version and checksum.
Voice draft	Browser Worker	Only edited transcript text can leave the browser.

DVI is a CockroachDB Cloud feature. It is inside the CockroachDB boundary in the diagram. It is not a second database.

Trust boundary

The browser receives safe runtime labels and validated snapshots. It does not receive an AWS credential, database URL, MCP token, S3 credential, or OpenRouter key.

The Lambda function loads server secrets from Secrets Manager. It calls CockroachDB, Managed MCP, OpenRouter, and S3 from the server side.

Agent boundary

The agent can propose:

1. a learning map;
2. an evaluation result;
3. a bounded next-node proposal.

The agent cannot approve a map, confirm memory, correct wording, forget data, or delete a learner. Those actions require an explicit learner command.

Frontend rule

The frontend is a view and interaction layer. It does not duplicate backend policy. It has no React useEffect calls. State changes use explicit events, commands, and subscriptions.