Architecture

SAT is a control plane for an AI agent company. The API is the system of record: it stores companies, agents, goals, tasks, runs, approvals, routines and the audit log, and it enforces budgets. It does not run agents and never calls a model. Starting work only queues a run. A runner, such as sat runner from apps/cli or any client that follows the runner protocol, claims queued runs, executes them with an agent CLI, and reports back.

The diagrams follow the C4 model: context, containers, components, deployment. They are drawn as flowcharts with C4-style boxes so they render everywhere.

System contextCopy Anchor Link

Who uses SAT and what it talks to.

ContainersCopy Anchor Link

The deployable pieces. The runner is part of the sat CLI and runs on your machines, not in Google Cloud.

Components of the APICopy Anchor Link

The agent-company domain lives in apps/api/company. Authentication lives in apps/api/api/auth_endpoints.py, services/auth_service.py and services/api_keys.py.

DeploymentCopy Anchor Link

SAT ships as two deployable parts: a static web build (apps/web/dist) and an API container image (apps/api/Dockerfile). Anything that serves static files and runs one container next to a PostgreSQL 16 database can host it. The reference shape, which this documentation assumes where it names Google Cloud services, is Firebase Hosting for the web app, Cloud Run for the API and Cloud SQL for PostgreSQL for the database.

To run it yourself:

• Database. Create a PostgreSQL 16 database and a user for the API. The API applies its own migrations at startup. See Database.
• API. Deploy the image to Cloud Run (or any container host) with DATABASE_URL, JWT_SECRET_KEY, APP_ENV, ENVIRONMENT, ALLOWED_ORIGINS and WEB_APP_URL set, secrets coming from your secret store, and at most one instance while EVENTS_BACKEND=memory. See Configuration.
• Web app. Build apps/web with VITE_EVENTS_ORIGIN set to the API's direct URL and serve apps/web/dist, rewriting /api/** and /health to the API.

The hosted Yarlis environments are deployed by the Yarlis release system; Yarlis staff: see the internal SAT runbook on the staff portal (portal.yarlis.com/docs).

Data modelCopy Anchor Link

All tables live in one PostgreSQL database. Every company-scoped table has a company_id foreign key, and every query filters on it. Money columns are integer cents; a budget of 0 means no limit. Primary keys are UUIDs.

Notes on the model:

• Unique constraints. company_members (company_id, user_id) and tasks (company_id, number). A task key such as NF-12 is companies.task_prefix plus tasks.number; it is computed, not stored.
• Shared tables. agents and projects predate the company model. Their older columns (agents.type, agents.session_id, projects.tech_stack, and others) are still present and agents.type is still NOT NULL, so the API copies role into it. company_id is nullable on both tables for the same reason.
• Approvals also reference requested_by_agent_id, requested_by_user_id and decided_by_user_id.
• Runs carry transcript as a JSON array of {ts, role, text} entries in the same row. Long runs grow that row; see Limits.
• Legacy tables created by migration 001 and not used by the company domain: sessions, session_logs, agent_tasks, deployments, system_metrics, system_health_checks.

See Database for migrations.

Request flowCopy Anchor Link

A typical write, assigning a task to Grace in the NoteFlow company:

1. Authentication. get_current_user reads the Bearer token. A token starting with sat_live_ or sat_test_ is looked up as an API key by its SHA-256; anything else is decoded as an HS256 JWT.
2. Authorization. get_company_context loads the caller's company_members row for the company in the path. No row means 404 NOT_FOUND.
3. Write and audit. The router changes rows and calls audit.record, which adds an audit_events row in the same transaction.
4. Commit, then publish. After COMMIT, audit.publish sends {"type": "<entity>.<verb>", "id": ...} on the company channel, so a subscriber that refetches never sees the old row.
5. Invalidate. The web app maps each event type to the SWR caches it makes stale and refetches them (apps/web/src/lib/live.ts). The runner uses run.created and agent.updated to try a claim, and run.updated with status: cancelled to stop a run.

Design decisionsCopy Anchor Link

The API records; runners executeCopy Anchor Link

The API never runs an agent, holds a model key or makes outbound calls to an LLM. It queues runs and accepts reports. Execution happens in sat runner on machines you control, with the agent CLIs and credentials already installed there.

• Why. Agent work needs a filesystem, git, long-running processes and model credentials. Keeping those out of the API keeps the API stateless apart from the database, cheap to run on one small Cloud Run instance, and free of customer model keys.
• Consequence. Nothing happens unless a runner is running. A run stays queued until a runner that serves its agent's adapter claims it.
• Safety. Claims are atomic (FOR UPDATE SKIP LOCKED plus a status = 'queued' guard on the update), so two runners never execute the same run. Leases (runner_id, heartbeat_at, RUN_LEASE_SECONDS) fail runs whose runner disappeared, so an agent is never stuck behind a dead run.

Events are invalidations, not dataCopy Anchor Link

Each SSE message carries only the event type, the entity id and a few scalar hints (for example status and agent_id on run.updated). Clients refetch the data they display.

• Why. Clients never apply partial state, so they cannot drift from the database. A missed event costs one stale view until the next event or refetch, not corrupted state.
• Consequence. Events are not a durable log. There is no replay, no event id and no Last-Event-ID support. Use the activity log (GET /activity) for history.

In-memory event bus by defaultCopy Anchor Link

InMemoryBus delivers events to subscribers in the same process only. Each subscriber gets an asyncio.Queue with room for 1,000 events.

• Why. One Cloud Run instance needs no extra infrastructure, and SAT does not require Redis.
• Consequence. The API must run as exactly one instance. A second instance would split SSE clients across two buses. Deploy with --max-instances 1, and do not split traffic between two revisions. To run more instances, set EVENTS_BACKEND=redis; see Scaling.

Membership is the only boundaryCopy Anchor Link

Every company path is resolved through the caller's membership. Non-members get 404, not 403, so company ids cannot be probed. See Security.

Crons are evaluated outside the APICopy Anchor Link

Routines and agent heartbeats store a cron expression, but the API never evaluates it. sat scheduler does, and calls the same endpoints a person would. See Scheduler.

RelatedCopy Anchor Link