Repository navigation
docs: architecture map with a numbered diagram - #1
Conversation
Add docs/architecture.md: the components, the trust and data boundaries, the path one request or run takes through the system as numbered steps that match the arrows on docs/architecture.svg, and a table of what is proven and where the evidence lives. The README gains an Architecture section that shows the diagram and links the page. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Expand the canvas and nested regions, enlarge text areas, align the main flow, and move external services below AWS. Route edges orthogonally with separate service ports; place badges, labels, and notes clear of borders and other objects. Simplify the ECR connection and separate the logs label from the engine-loop note. Preserve every label and fact with no cuts or Markdown edits. The supplied renderer is unchanged. Three sighted render rounds, the geometry gate, content comparisons, and edge-intersection checks pass. Co-Authored-By: Codex astra <noreply@openai.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bb9c48f98f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 5. **Worker → Anthropic API.** The `capstan.model` built-in calls the model. The server brackets each call with `ReserveAICall` and `FinishAICall`, prices the usage into `ai_call`, and enforces `CAPSTAN_DAILY_CAP_USD` (default 2.00, counted on the America/Toronto day). | ||
| 6. **Worker → AgentOps Gate.** The `capstan.gate.decide` built-in posts the proposed action to the gate's `POST /decisions` with `X-API-Key` and an `Idempotency-Key`. | ||
| 7. **Server → AgentOps Gate (polling).** When the gate answers `REQUIRE_APPROVAL`, the `approvals` loop polls `GET /approvals/{id}` outside any transaction, backing off from 15 s to 5 min, and appends `ApprovalResolved` when a human decides. A waiting run holds no task, no lease and no worker. Humans can also resolve through `ResolveApproval` on the client API. | ||
| 8. **Server → Amazon CloudWatch.** Logs go to `/capstan/server` (7 days). A Lambda publishes `Capstan/Service RunningTaskCount`; the alarms `capstan-http-5xx-rate` and `capstan-no-running-task` notify the `capstan-alerts` SNS topic. A $10 monthly budget caps the account. |
There was a problem hiding this comment.
For an AWS deployment that continues running after reaching $10, this promises a hard spending limit that does not exist. infra/lib/budget.ts configures only email notifications at 50%, 90%, and 100%, with no budget action to stop resources; docs/runbook.md also explicitly calls it “not a hard spending cap.” Calling it a cap may cause operators to rely on protection that will not prevent further charges.
Useful? React with 👍 / 👎.
| ## Boundaries | ||
|
|
||
| - **Trust.** Every RPC and `/metrics` needs a Bearer key that the server checks against SHA-256 hashes in `CAPSTAN_API_KEY_HASHES`. `/healthz`, `/readyz` and the viewer's static files are open. The sandbox exists for replay determinism, not as a security boundary: workers run trusted code. Payloads are opaque to the server and visible to any key holder. | ||
| - **Secrets.** The worker holds the Capstan key, `ANTHROPIC_API_KEY` and the gate key. The server holds the database URL, the key hashes and the gate key for polling. On AWS these live in four Secrets Manager entries read at task start. |
There was a problem hiding this comment.
In the documented AWS topology, the worker runs outside AWS, so its Capstan, Anthropic, and Gate credentials do not live in Secrets Manager or get read at task startup. infra/lib/service.ts injects only the database URL, API-key hashes, and optional server Gate key into the task; the fourth secret created by infra/lib/data.ts is the database credential used to construct the URL, not a worker credential or task injection. This boundary description should distinguish external worker configuration from the four AWS secret resources.
Useful? React with 👍 / 👎.
docs: architecture map with a numbered diagram
1 participant
Adds a reference-architecture drawing and a walkthrough for this repository.
docs/architecture.svg: boxed regions, component icons and numbered arrows, rendered from a JSON spec and checked by a geometry gate (text fits its box with slack for wider fonts; nothing touches or crosses anything else).docs/architecture.md: the numbered path arrow by arrow, the component table, the trust and data boundaries, what is proven and where the evidence lives, and the identifiers the code relies on. Every claim comes from this repository's own README, ADRs and code, and the page says what is not claimed.Two commits: the map, then the geometry pass.