docs: add an architecture reference page and embed the platform diagrams - #661
docs: add an architecture reference page and embed the platform diagrams#661hongyi-chen wants to merge 3 commits into
Conversation
Adds a Cloudflare-style Architecture section under the Platform topic with six pages, each pairing a reference diagram with numbered prose: overview, stack overview, cloud agent run lifecycle (with a Warp-hosted sequence view), self-hosted execution flow (with its sequence view), Warp Factories work-item flow, and data security and boundaries (Warp-hosted primary, self-hosted variant). Embeds the diagrams on the pages readers already visit: - Deployment patterns: deployment models comparison, plus a refreshed Warp-hosted architecture figure (replaces the stale export in place). - Self-hosting overview: refreshed self-hosted execution figure (replaces customer-dedicated-saas.png in place) with flow links. - Self-hosting security and networking: network egress diagram. - Factories: the work-item flow diagram on How factories work, and the self-hosted data boundaries diagram on Infrastructure and security. - Enterprise architecture and deployment: fills the system-architecture diagram TODO with the stack overview and adds the deployment models figure to the model-selection section. All internal links and anchors verified against the current factories IA (automations, factory dashboard); site builds cleanly. Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds a new architecture reference section with platform, lifecycle, self-hosted, factories, and data-boundary diagrams, and embeds those diagrams into related existing docs. The structure and sidebar updates are generally coherent, but one security-sensitive retention statement needs tightening before merge.
Concerns
- The new data-boundaries page says Warp does not persistently store source code while the same section explains that transcripts and artifacts persist and can include code context; that distinction needs to be explicit for security reviewers.
- No approved or repository spec context was available for this PR, so there were no spec commitments to validate against.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
|
||
| ## The data classes | ||
|
|
||
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store your source code or train on it. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Either way, code context the agent puts into prompts and transcripts still transits Warp. |
There was a problem hiding this comment.
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store your source code or train on it. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Either way, code context the agent puts into prompts and transcripts still transits Warp. | |
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store repository clones or train on your code. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Code context the agent puts into prompts, transcripts, or artifacts still transits Warp and may persist as run data. |
![warp-factories[bot]](https://avatars.githubusercontent.com/in/2278701?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
Adds a six-page architecture reference suite and embeds the new diagrams across seven existing pages; CI (build, link-check, CodeQL) is green, the internal link/anchor audit is clean, and I visually verified all pages render correctly and legibly on the live Vercel preview. One factual inconsistency between prose and diagram is independently confirmed and should block merge; a design-invariant mismatch and a scope question are flagged for the author's judgment.
Concerns
- The "Run data" bullet on
data-security-boundaries.mdxsays the customer-owned bucket is used "instead" of Warp's store, but both accompanying diagrams (and the page's own "With self-hosted execution" section) state the bucket holds an "exported copy" while "Warp still retains the primary run record." See inline comment for a suggested fix. - Three of the six new pages (
stack-overview.mdx,factories-work-item-flow.mdx,data-security-boundaries.mdx) present numbered prose lists next to diagrams that carry no numeric markers at all — verified both from the source PNGs and by loading the live preview. This contradicts the PR description's claim that "each pairing a diagram with numbered prose that matches the numbers in the figure," andsrc/sidebar.ts's own new code comment ("each page pairs a numbered diagram with matching numbered prose sections"). Readers can't map a list item to a diagram element on these three pages.
Verdict
Checks: build pass, tests n/a (no test suite), CI green, visual proof present (verified via live Vercel preview at all three affected pages plus sidebar structure)
Found: 1 critical, 1 important, 1 suggestion/question (non-blocking, for author judgment), 0 nits
Recommendation: Request changes — the data-retention contradiction is an unambiguous fix; the diagram/prose numbering mismatch needs either updated diagrams or a list-format change. The internal-architecture-detail question does not block merge on its own.
|
|
||
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store your source code or train on it. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Either way, code context the agent puts into prompts and transcripts still transits Warp. | ||
| 2. **Prompts and context** - The agent's model calls route through Warp's inference routing to LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements: providers don't retain or train on the traffic, except for provider-specific models the ZDR terms don't cover. | ||
| 3. **Run data** - Transcripts, artifacts, run metadata, and costs persist in Warp's stores, encrypted at rest and access-controlled by your team's roles. Enterprise teams can keep the supported classes — transcripts, artifacts, and run attachments — in a customer-owned Amazon S3 or Google Cloud Storage bucket instead; configuration and other control-plane state stay with Warp. |
There was a problem hiding this comment.
🚨 [CRITICAL] This says the customer-owned bucket is used "instead" of Warp's store, but both diagrams on this page (warp-hosted-data-boundaries.png and data-security-boundaries.png) label it "Optional customer-owned export" and state "An additional copy of run data writes to your bucket. Warp still retains the primary run record." The "With self-hosted execution" section below (line 24) agrees with the diagrams ("exported copy"), so only this bullet is wrong. This misstates a data-retention boundary that security reviewers rely on.
| 3. **Run data** - Transcripts, artifacts, run metadata, and costs persist in Warp's stores, encrypted at rest and access-controlled by your team's roles. Enterprise teams can keep the supported classes — transcripts, artifacts, and run attachments — in a customer-owned Amazon S3 or Google Cloud Storage bucket instead; configuration and other control-plane state stay with Warp. | |
| 3. **Run data** - Transcripts, artifacts, run metadata, and costs persist in Warp's stores, encrypted at rest and access-controlled by your team's roles. Enterprise teams can also export the supported classes — transcripts, artifacts, and run attachments — to a customer-owned Amazon S3 or Google Cloud Storage bucket; Warp retains the primary run record, and configuration and other control-plane state stay with Warp. |
|
|
||
| ## The data classes | ||
|
|
||
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store your source code or train on it. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Either way, code context the agent puts into prompts and transcripts still transits Warp. |
There was a problem hiding this comment.
warp-hosted-data-boundaries.png above — confirmed on the live preview. The PR description states every page "pairs a diagram with numbered prose that matches the numbers in the figure," and src/sidebar.ts's new comment makes the same claim. Either add numbered callouts to the diagram or change this to a bulleted list.
|
|
||
| ## Components | ||
|
|
||
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the Warp Factories control room, and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. |
There was a problem hiding this comment.
data-security-boundaries.mdx: this "Components" list is numbered 1–7, but warp-stack-overview.png has no numeric markers anywhere — confirmed on the live preview. This contradicts the PR description and src/sidebar.ts's new comment, both of which claim numbered diagrams matching numbered prose across the suite.
|
|
||
| ## How a factory runs | ||
|
|
||
| 1. **Work sources** - Work items arrive from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), from local coding agents through the [Factory MCP](/factories/factory-mcp/), or from direct runs and schedules. |
There was a problem hiding this comment.
factories-work-item-flow.png has no numeric markers — confirmed on the live preview. Please reconcile all three affected pages (this one, stack-overview.mdx, data-security-boundaries.mdx) the same way, either by adding diagram callouts or dropping the numbering.
|
|
||
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the Warp Factories control room, and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. | ||
| 2. **APIs** - The control plane's entry points: a GraphQL API used by Warp's own clients, the REST [Agent API and SDKs](/reference/api-and-sdk/) for programmatic use, a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. | ||
| 3. **Control plane services** - The coordination layer. Agent orchestration owns run workflows and state; triggers evaluate [schedules](/platform/triggers/scheduled-agents/) and automations; identity and configuration manage teams, [secrets](/platform/secrets/), [environments](/platform/environments/), and [runners](/platform/runners/); inference routing brokers every model call; observability keeps run records and shared sessions; and the codebase index powers [Codebase Context](/agents/capabilities/codebase-context/) retrieval. |
There was a problem hiding this comment.
💡 [SUGGESTION] This enumerates internal control-plane services (orchestration, identity/config, inference routing, observability, codebase index) in detail. AGENTS.md's "Document the user-visible model, not our architecture" guidance normally caps internal-component detail at one actionable sentence. This may be an intentional exception for this security/evaluation-focused suite (index.mdx states the pages exist to "answer security questions"), matching the precedent already set by the enterprise architecture-and-deployment.mdx page — flagging so a maintainer can confirm this is the intended scope rather than drift.
The stack overview described a previous revision of the diagram: it listed a GraphQL API, a data-stores layer (relational database, vector index, cache), and the codebase index, none of which appear in the current figure, and used the retired 'control room' name. Rewrote the components list to match the figure: three public entry points, control plane services including run data storage (with the optional customer-owned export), and external systems including compute providers. Data security and boundaries: customer-owned storage is an additional export copy, not a replacement — reworded to match the embedded figure. Tightened the cross-reference sentences added on deployment patterns, self-hosting, factories, and the enterprise page: removed restated benefits and doubled links, one purposeful link per pointer. Co-Authored-By: Warp <agent@warp.dev>
Per review feedback that six new pages was too much new IA surface: merge the architecture suite into one /platform/architecture/ page with anchored sections (stack overview, run lifecycle + sequence, self-hosted flow + sequence, factories work-item flow, data boundaries + self-hosted variant). The page keeps every diagram and numbered walkthrough; the per-page intros, duplicate related-pages lists, and the index page go away. Sidebar: the six-entry Architecture group becomes a single entry in Deployment & hosting. All cross-references on existing pages now point at section anchors. No redirects needed - the sub-pages were never published. Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
changed the title
1 participant
Adds an architecture reference page and embeds the new platform diagrams across the docs, replacing stale visuals where they existed.
New: Architecture page (Platform → Deployment & hosting)
One page at
/platform/architecture/with anchored sections, each pairing a diagram with a numbered walkthrough:Embeds on existing pages
cloud-agents-infra.png) replaced in place with the current Warp-hosted architecture render.customer-dedicated-saas.pngreplaced in place with the current self-hosted execution render, plus a link to the numbered flow reference.Notes
/factories/automations/,/factories/factory-dashboard/).npm run buildpasses; the sidebar gains a single "Architecture" entry in the Deployment & hosting group.Co-Authored-By: Warp agent@warp.dev