Repository navigation
Add architecture sheets for every module and the whole system - #426
Conversation
Fifteen HTML drawings under docs/architecture: one for each deployable module and run-unit image, the library dependency matrix, the Kafka topic matrix, the review flow, the work item flow and the system overview. Each sheet is data in sheets/*.mjs; build.mjs renders the pages, and can also write standalone SVG files with --svg. The sheets were drawn from the code at 0e6fbde. They record where the code differs from the older documents: the gateway publishes to cs.repository-integration and not cs.integration, four topics have one side missing, and the orchestrator deletes rows in the review worker schema. The root README links to the series from its Docs table.
code-spire-beaver
left a comment
There was a problem hiding this comment.
Reviewed 9a161f5 against 0e6fbde. The sheets, generator, Kafka topic/dependency matrices and committed HTML were reviewed against the pinned source. The security boundary is overstated in the new documentation; a second, lower-severity finding corrects how proxy observations affect run outcomes. CI is green; no builds or tests were run locally.
Findings: 1 MEDIUM, 1 LOW. Reviewed head 9a161f5a41 as @code-spire-beaver.
code-spire-beaver
left a comment
There was a problem hiding this comment.
❌ CHANGES REQUESTED
Review of PR #426 at 9a161f5 (base 0e6fbde).
Changes requested: security/M-1 overstates the run unit's network isolation. code-quality/L-1 corrects proxy failure-classification wording. Two inline threads contain the scenarios, pinned-source evidence and fixes.
Per-lens result:
- Security: one documentation finding; examined credential/network boundaries, static HTML escaping and the local-only generator. Semgrep OSS, CodeQL and gitleaks pass.
- Correctness: one LOW finding; checked all sheet sources and the generator, compared Kafka topic ownership and direct Gradle dependencies to source, and checked local HTML navigation. No missing local links or invalid numeric SVG tokens. Manually viewed committed sheets 12 and 13 in Chromium.
- Rules: root CLAUDE.md; matching documentation-maintenance, blog-material-capture, no-synthetic-data, no-local-builds and pr-review-labels rules applied. seo-react was consulted for index.html but its SPA-specific requirements do not apply to these local static documents. The Java/TS/Python clean-code limits do not match .mjs files. No nested CLAUDE.md or applicable review-state file; prescribed agent-memory locations unavailable.
- QA/CI: run 43737697580 attempt 1 is successful at this exact head. Dashboard: 127 files / 1,342 tests passed, typecheck and bundle succeeded. Java fast tests passed (most unchanged test tasks FROM-CACHE; spire-arch:test executed); service tests and packaging passed. Java logs do not print a reliable aggregate test count. Other reported checks pass; kind/invariants and merge jobs were skipped.
Residual limits: CI does not establish correctness of the architecture prose or regenerate these new sheets. No local builds, tests or linters were run; the repository was not modified. Visual inspection sampled the two dense sheets, not every viewport on every sheet.
Agent findings: 0 resolved, 2 open. CI: 11/14 checks passing. Head 9a161f5a41, reviewed by @code-spire-beaver.
Open findings:
- [security/M-1] MEDIUM — #426 (comment)
- [code-quality/L-1] LOW — #426 (comment)
Sheets 08, 09 and 15 said the egress proxy is the only way out of a run unit. DockerRunRuntime.hostConfigFor puts only the agent on the internal network, and only when egress proxies it. The init container and the publisher stay on the default bridge, and with egress off the agent has a direct route. The sheets now scope the claim and say what the egress log does not cover. Sheet 07 said a 401 or a refused path fails the run. The model proxy log only names the cause of a run whose agent already failed (RunLauncher.agentFailure). A finished run is not rewritten, and a 403 keeps the adapter's cause.
code-spire-beaver
left a comment
There was a problem hiding this comment.
Follow-up at 628b51b: both previous findings are fixed in the sheet sources and regenerated HTML. Reviewed the complete documentation-only delta against the unchanged runtime code and existing tests; no new findings. CI run 43746965674 attempt 1 passed on this head.
Findings: none. Reviewed head 628b51bf6b as @code-spire-beaver.
code-spire-beaver
left a comment
There was a problem hiding this comment.
✅ APPROVED
Follow-up review at 628b51b, base 0e6fbde.
Both prior findings verified and resolved: security/M-1 and code-quality/L-1. No new findings in the one-commit delta from 9a161f5.
Security: the new text scopes the isolated network to proxied agent/model traffic and explicitly excludes init/publisher traffic and egress-off agents.
Correctness: proxy observations now classify failed agent outcomes, preserving successful runs and the adapter's cause for 403; compared with RunLauncher/ModelProxyResults and existing tests.
Rules: the prior root CLAUDE.md and applicable documentation-maintenance, blog-material-capture, no-synthetic-data, no-local-builds and pr-review-labels context is unchanged. No new rule violations; no runtime code, dependencies, generator, CSS or tests changed.
QA: reviewed all five changed sheet sources and all six changed HTML documents (including the index); the committed HTML incorporates the corrections. CI run 43746965674, attempt 1, passed on this exact head: 127 dashboard test files / 1,342 tests, typecheck/build, Java fast tests, service tests and packaging. Security scans pass. Manifest invariants/kind and merge jobs are skipped.
No local builds, tests or linters were run. CI does not independently verify architectural prose; the prose was checked against the pinned source. Repository files remain unchanged.
Agent findings: 2 resolved, 0 open. CI: 11/14 checks passing. Head 628b51bf6b, reviewed by @code-spire-beaver.
The heading said two modes; the table lists report, enforce and off.
What
Fifteen HTML drawings under
docs/architecture/. Opendocs/architecture/index.htmlin a browser.spire-gateway,spire-orchestrator,spire-review-worker,spire-run-workerspire-publisher,spire-model-proxy,spire-egress-proxy, the two agent imagesspire-uiEach page has one drawing and short text: what the module is responsible for, what goes in and out, and the coupling to watch.
How it is built
Each sheet is data in
docs/architecture/sheets/NN-name.mjs.node docs/architecture/build.mjsrenders the pages.--svgalso writes one standalone SVG for each sheet; no SVG is committed. The script has no dependencies.The root
README.mdgets one row in its Docs table.What the code showed
The sheets were drawn from the code at
0e6fbde3, and they record where it differs from the older documents:cs.repository-integration,cs.work-integrationandcs.registry-integration.README.mdanddocs/factory/ARCHITECTURE.mdstill namecs.integration. This PR does not change those lines.cs.integrationhas a reader and no writer.cs.work-events,cs.repository-activityandcs.work-dlqhave a writer and no reader.ReviewProjectionin the orchestrator deletes rows in theworkerschema. It is the one direct database link between two services.Checks
No code changed, so no test covers this. Each drawing was rendered in headless Chrome and looked at. Sheets 12 and 13 were not looked at again after their last layout fix.