Codebase tour

This page walks through each app in the order a request travels: the API that records everything, the generated client that types it, the web app and the CLI that call it, and the runner that executes runs. Read it before your first change in an area you have not touched.

API (apps/api)Copy Anchor Link

FastAPI with synchronous SQLAlchemy 2 sessions on PostgreSQL. Endpoints are plain def functions, so FastAPI runs them in its threadpool.

Entry and wiringCopy Anchor Link

The other routers mounted by main_api.py (agent_endpoints, session_endpoints, project_endpoints, user_endpoints, dashboard_endpoints, websocket_endpoints) are the legacy pre-company API. They stay mounted but are unsupported and left out of the API reference; do not extend them.

Layers of the company domainCopy Anchor Link

The shape of a typical mutation:

@router.patch("/tasks/{task_ref}", response_model=TaskOut)
def update_task(task_ref: str, body: TaskUpdate, ctx: CompanyContext = Depends(get_company_context)):
    """Update a task; only fields present in the body are changed. ..."""
    task = _find_task(ctx, task_ref)                 # 404 outside this company
    actor = services.run_actor(ctx, body.run_id)     # agent attribution, if any
    values = body.model_dump(exclude_unset=True, exclude={"run_id"})
    changes = audit.diff(task, values)               # apply and collect {field: [old, new]}
    if changes:
        label = f"{services.task_key(ctx, task)} {task.title}"
        verb = "moved" if set(changes) <= {"status", "sort_order"} else "updated"
        audit.record(ctx, verb, "task", task.id, label, changes, **_actor_kwargs(actor))
        ctx.db.commit()
        audit.publish(ctx, "task", "updated", task.id)   # after commit, never before
    return _task_out(ctx, task)

ConventionsCopy Anchor Link

• Errors have one shape: {"error": {"code": "NOT_FOUND", "message": "...", "details": {}}}. Use an upper-case code that clients can branch on (RUN_LEASE_LOST, ALREADY_DECIDED, ORG_CYCLE).
• Money is integer cents. A budget of 0 means no limit.
• Times are timezone-aware UTC. Compare with aware(...) when a value may come from SQLite in tests.
• Non-members get 404. Never return 403 for a company the caller cannot see.
• The API records; runners execute. Do not add code that runs agents or calls a model from the API. See Architecture.
• Migrations for every model change, additive by default. See Database.
• Regenerate the client after any API change: bun run --cwd libs/api-client generate.

API client (libs/api-client)Copy Anchor Link

@sat/api-client is the single typed boundary between the API and every TypeScript consumer.

Regenerate with bun run --cwd libs/api-client generate. CI type-checks the web app, CLI and docs against the committed types, so a stale client fails the build.

Web app (apps/web)Copy Anchor Link

React 19 function components, React Router 8, SWR for server state, zustand for UI state, Tailwind 4 with tokens, components from @yarlisai/ui.

ConventionsCopy Anchor Link

• Server data only through the SWR hooks in lib/hooks.ts. Do not fetch ad hoc in components. A new resource gets a hook with a [resource, companyId, ...] key, and an entry in AFFECTS in lib/live.ts so live events refresh it.
• UI state in zustand, not in SWR or component trees that need it globally.
• Visual values only from tokens in src/index.css (bg-background, text-muted-foreground, var(--status-...)). No raw colours in components.
• One status vocabulary. Labels and order come from @sat/api-client (TASK_STATUSES, PRIORITIES, ...); colours from statusColor.
• Every screen answers three questions: what is happening, does it need me, what do I do about it.

CLI (apps/cli)Copy Anchor Link

Bun and commander. sat covers the control plane, the runner and the scheduler.

Conventions: every command supports --json; errors map to stable exit codes; anything an agent might call through sat adds run_id from SAT_RUN_ID so writes are attributed to the agent. Regenerate the CLI reference after changing commands: bun run --cwd apps/cli docs (CI runs docs:check).

Runner (apps/cli/src/runner)Copy Anchor Link

Tests in apps/cli/test run the runner and scheduler against in-memory fakes. See How runs work and Custom runner for the protocol.

Docs (apps/docs)Copy Anchor Link

Next.js with Fumadocs. MDX pages in content/docs, the generated API reference from libs/api-client/openapi.json (lib/openapi.ts, lib/source.ts), and a link checker in scripts/check-links.ts. See Writing docs.

RelatedCopy Anchor Link