Skip to content

Add architecture sheets for every module and the whole system - #426

Merged
artyomsv merged 3 commits into
masterfrom
chore/design
Nov 15, 2026
Merged

artyomsv merged 3 commits into
masterfrom
chore/design

Conversation

@artyomsv

Copy link
Copy Markdown
Owner

What

Fifteen HTML drawings under docs/architecture/. Open docs/architecture/index.html in a browser.

Sheets Subject
01 to 04 spire-gateway, spire-orchestrator, spire-review-worker, spire-run-worker
05 The run unit: the five small images together
06 to 09 spire-publisher, spire-model-proxy, spire-egress-proxy, the two agent images
10 spire-ui
11 The libraries: which module needs which
12 The message bus: all 21 Kafka topics, writers and readers
13, 14 How a review travels. How a work item is built.
15 The whole system

Each 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.mjs renders the pages. --svg also writes one standalone SVG for each sheet; no SVG is committed. The script has no dependencies.

The root README.md gets 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:

  • The gateway publishes to cs.repository-integration, cs.work-integration and cs.registry-integration. README.md and docs/factory/ARCHITECTURE.md still name cs.integration. This PR does not change those lines.
  • cs.integration has a reader and no writer. cs.work-events, cs.repository-activity and cs.work-dlq have a writer and no reader.
  • ReviewProjection in the orchestrator deletes rows in the worker schema. 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.

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.
@artyomsv artyomsv added the review: requested the code waits for a reviewer label Nov 15, 2026

@code-spire-beaver code-spire-beaver left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 code-spire-beaver left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❌ 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:

@code-spire-beaver code-spire-beaver added review: changes-requested Agent review verdict: changes requested and removed review: requested the code waits for a reviewer labels Nov 15, 2026
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.
@artyomsv artyomsv added review: requested the code waits for a reviewer and removed review: changes-requested Agent review verdict: changes requested labels Nov 15, 2026

@code-spire-beaver code-spire-beaver left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 code-spire-beaver left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ 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.

@code-spire-beaver code-spire-beaver added review: approved Agent review verdict: approved and removed review: requested the code waits for a reviewer labels Nov 15, 2026
The heading said two modes; the table lists report, enforce and off.
@artyomsv artyomsv added review: requested the code waits for a reviewer and removed review: approved Agent review verdict: approved labels Nov 15, 2026
@artyomsv
artyomsv enabled auto-merge November 15, 2026 19:12
@artyomsv
artyomsv disabled auto-merge November 15, 2026 19:12
@artyomsv
artyomsv merged commit 6f06a07 into master Nov 15, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review: requested the code waits for a reviewer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants