docs(diagrams): add deployment diagram type standard, template and IT-topology reference - #132
Conversation
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @cuioss-oliver, you have reached your weekly rate limit of 500000 diff characters.
Please try again later or upgrade to continue using Sourcery
|
Warning Review limit reached
Next review available in: 46 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository: cuioss/coderabbit/.coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughChangesSkill profile updates
Deployment documentation
Estimated code review effort: 3 (Moderate) | ~25 minutes 🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
PR Reviewer Guide 🔍(Review updated until commit 9865794)
|
|
@coderabbitai review |
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.plan/project-architecture/integration-tests/enriched.json:
- Around line 59-63: Update the affected skill lists in enriched.json to retain
both existing HTTP skills, including cui-http and cui-http-testing, while adding
plan-marshall:build-server-client alongside them. Preserve the related
attack-database HTTP guidance and ensure the build-server dispatch behavior is
represented in the skill entries rather than only in the reasoning text.
In `@doc/development/diagram-type-deployment.md`:
- Around line 54-62: Update the sibling diagram-type references in the “Use a
different diagram type when” section to use the documented skill-notation paths
required when upstream sibling documents are absent, rather than relative
Markdown links. Preserve the referenced diagram type names and substitute
relative links only during graduation.
- Around line 105-110: Align the depth-3 radius between the canonical
deployment-diagram skeleton and the depth table: update the mismatched depth-3
value so both specify the standard rx/ry radius of 6. Preserve the existing
values for all other enclosure depths.
- Around line 24-35: The deployment diagram standard still contains
repository-specific assumptions outside its reference implementation, making the
unchanged-graduation claim inaccurate. In
doc/development/diagram-type-deployment.md at lines 24-35, keep the general
specification project-independent; at lines 356-382, move repository-specific
paths and rules into the reference section or replace them with
upstream-relative references. In doc/development/README.adoc at lines 76-80,
retain the unchanged-graduation claim only once the standard is portable.
- Around line 96-101: Update the label-band rule in the deployment diagram
documentation to make the reserved height conditional: use 44 px when the
enclosure has an encl-sub sub-label, otherwise retain 28 px. Apply the same
clarification to the corresponding rule or example around the additional
referenced section, ensuring child boxes cannot begin within the effective band.
- Around line 324-354: The deployment diagram documentation requires a blocking
render check without defining enforcement. For
doc/development/diagram-type-deployment.md lines 324-354, either add the check
to the documentation-validation workflow under .github/workflows/ or explicitly
state that render verification is a manual requirement; update
doc/development/integration-test-topology.adoc lines 104-112 to consistently
describe the same enforcement model.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: cuioss/coderabbit/.coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 08ba24d2-6040-4da7-9f44-dcfe592e79b1
⛔ Files ignored due to path filters (2)
doc/resources/diagrams/integration-test-topology.svgis excluded by!**/*.svgdoc/resources/templates/deployment-diagram-skeleton.svgis excluded by!**/*.svg
📒 Files selected for processing (8)
.plan/project-architecture/api-sheriff-parent/enriched.json.plan/project-architecture/api-sheriff/enriched.json.plan/project-architecture/benchmarks/enriched.json.plan/project-architecture/documentation/enriched.json.plan/project-architecture/integration-tests/enriched.jsondoc/development/README.adocdoc/development/diagram-type-deployment.mddoc/development/integration-test-topology.adoc
Triage dispositionsIn reply to comment_id:
|
…standard Resolves three CodeRabbit findings on PR #132, all confined to doc/development/diagram-type-deployment.md. 1. Cross-reference convention (dbd3c3): the "Use a different diagram type when" list named five absent upstream siblings as bare filenames while the doc mandates skill-notation paths for absent siblings. All five now use the skill-notation form, so the graduation-time substitution stays the single mechanical rule the doc claims it is. (The reviewer's premise that these were broken links was wrong — they are inline code spans; the real defect was the convention inconsistency.) 2. Label band (357e04): the containment-nesting table stated the reserved band unconditionally as 28 px, contradicting the enclosure-labels section's 44 px band for a sub-labelled enclosure. An author following the table alone placed a child at parent_top + 28 and overlapped the sub-label. The rule is now conditional and the no-child constraint keys to the effective band. The dependent 120 x 48 rationale is aligned. 3. Corner radius (718ee3): the depth table mapped depth 3 to rx 6, but both the skeleton template and the reference implementation use rx="4" on every depth-3 component, so copy-rename-fill produced a diagram the table called nonconforming. The sequence 8, 6, 6, 4 also did not decrease between depth 2 and 3, contradicting the stated rationale. The table is now keyed to enclosure ROLE rather than raw depth, which is what the radius actually tracks and what lets both canonical ladders stay describable: a leaf container takes rx="4" whatever its depth. No committed SVG changes, so no re-rasterisation was required. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
/review |
|
@coderabbitai review |
✅ Action performedReview finished.
|
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: cuioss/coderabbit/.coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 1a084760-31b1-49e3-879e-e509d6e4356b
📒 Files selected for processing (1)
doc/development/diagram-type-deployment.md
Triage dispositionsIn reply to comment_id:
|
Repopulates the per-module enrichment cache via 'architecture enrich all'. The documentation module gains the skills_by_profile.implementation profile it was missing, which had left documentation-only implementation tasks resolving zero architecture-driven skills; the other four modules pick up the build-server-client skill entry. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EkMQfbbBESLRHEch8ZuUWe
…-topology reference Adds a deployment/topology SVG diagram type to the house documentation, in three artifacts: - doc/development/diagram-type-deployment.md - the type standard, specifying containment nesting (depth limit, insets, per-level corner radius, label bands, minimum legible box size), protocol-and-port edge labels with the crowded-corridor and cross-container rules, the trust-boundary visual (dashed 8 4 at 2.0px plus a crossing glyph, distinguished without hue), first-party vs external components, and mounted material as pills. - doc/resources/templates/deployment-diagram-skeleton.svg - the copy-rename-fill skeleton, carrying a worked placeholder for every affordance. - doc/resources/diagrams/integration-test-topology.svg plus doc/development/integration-test-topology.adoc - the reference implementation and its contributor page, drawn entirely from integration-tests/docker-compose.yml and the mounted gateway.yaml. The standard is authored in Markdown rather than AsciiDoc as a deliberate format outlier, so the intended graduation to pm-documents:ref-svg-diagrams is a file move rather than a rewrite; the rationale and both destination paths are stated in the document itself. Also records the container-run render-verification recipe, including the two corrections established while proving it: the Alpine package is rsvg-convert (librsvg ships only the shared library), and the font packages are mandatory because a fontless container renders every glyph as tofu while still exiting 0. Both SVGs were rasterised against the light and dark GitHub backgrounds and read back before commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EkMQfbbBESLRHEch8ZuUWe
…standard Resolves three CodeRabbit findings on PR #132, all confined to doc/development/diagram-type-deployment.md. 1. Cross-reference convention (dbd3c3): the "Use a different diagram type when" list named five absent upstream siblings as bare filenames while the doc mandates skill-notation paths for absent siblings. All five now use the skill-notation form, so the graduation-time substitution stays the single mechanical rule the doc claims it is. (The reviewer's premise that these were broken links was wrong — they are inline code spans; the real defect was the convention inconsistency.) 2. Label band (357e04): the containment-nesting table stated the reserved band unconditionally as 28 px, contradicting the enclosure-labels section's 44 px band for a sub-labelled enclosure. An author following the table alone placed a child at parent_top + 28 and overlapped the sub-label. The rule is now conditional and the no-child constraint keys to the effective band. The dependent 120 x 48 rationale is aligned. 3. Corner radius (718ee3): the depth table mapped depth 3 to rx 6, but both the skeleton template and the reference implementation use rx="4" on every depth-3 component, so copy-rename-fill produced a diagram the table called nonconforming. The sequence 8, 6, 6, 4 also did not decrease between depth 2 and 3, contradicting the stated rationale. The table is now keyed to enclosure ROLE rather than raw depth, which is what the radius actually tracks and what lets both canonical ladders stay describable: a leaf container takes rx="4" whatever its depth. No committed SVG changes, so no re-rasterisation was required. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The row label read 'Everything the network contains', which is compose-ladder framing and contradicts the ladder-neutral rationale two lines above: in the orchestrated ladder (cluster to namespace to pod to container) a pod is contained by the namespace, not the network. 'Nested workload roles' reads correctly against both canonical ladders. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EkMQfbbBESLRHEch8ZuUWe
Promotes one recurring disposition pattern from this plan to a durable architecture hint on the documentation module: review suggestions that contradict an already-audited decision are declined with a citation rather than reversing the audit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EkMQfbbBESLRHEch8ZuUWe
12cf41f to
06979ae
Compare
|
/review |
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: cuioss/coderabbit/.coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: bef70f03-d38a-4e9e-8f68-6f795dca1bc9
⛔ Files ignored due to path filters (2)
doc/resources/diagrams/integration-test-topology.svgis excluded by!**/*.svgdoc/resources/templates/deployment-diagram-skeleton.svgis excluded by!**/*.svg
📒 Files selected for processing (8)
.plan/project-architecture/api-sheriff-parent/enriched.json.plan/project-architecture/api-sheriff/enriched.json.plan/project-architecture/benchmarks/enriched.json.plan/project-architecture/documentation/enriched.json.plan/project-architecture/integration-tests/enriched.jsondoc/development/README.adocdoc/development/diagram-type-deployment.mddoc/development/integration-test-topology.adoc
🚧 Files skipped from review as they are similar to previous changes (3)
- .plan/project-architecture/api-sheriff/enriched.json
- doc/development/README.adoc
- doc/development/integration-test-topology.adoc
Triage dispositionsIn reply to comment_id:
|
…geometry The standard claimed a depth-5 box cannot satisfy the 120x48 px minimum inside any standard viewBox. That is false: in the smallest viewBox (1000x620) a depth-5 box still has roughly 820x330 px after the 24 px outer margin, four 16 px insets and four worst-case 44 px label bands. Depth 4 remains the limit, now with the accurate rationale: the corner-radius ladder has only three steps (8/6/4), so depth 4 already shares depth 3's leaf radius and a fifth level would carry no distinguishing radius at all. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EkMQfbbBESLRHEch8ZuUWe
|
/review |
1 participant
Summary
pm-documents:ref-svg-diagramsships six diagram types and five templates, none of which expressescontainment, protocol-and-port edges, or trust boundaries — so a deployment/container type must be
authored from scratch. This plan produces that type as three artifacts in dependency order: a
Markdown type standard shaped to graft upstream unchanged, a skeleton SVG template, and one
reference implementation depicting the integration-test topology, which is real and on disk today.
The render-verification blocker is resolved first as its own gate deliverable, because the upstream
standard makes render-and-read-back non-skippable and no rasteriser is installed.
Intent
Changes
doc/development/diagram-type-deployment.md— new deployment/container diagram-type standard: fiveaffordances (containment, protocol-and-port edges, trust boundaries, external-actor notation,
deployment-target labeling), file naming, theme strategy, the render recipe, and a graduation
statement for promoting the type upstream.
doc/resources/templates/deployment-diagram-skeleton.svg— new skeleton SVG template implementingthe standard, verified to render legibly on both light and dark backgrounds.
doc/resources/diagrams/integration-test-topology.svg+doc/development/integration-test-topology.adoc— new reference implementation depicting the integration-test docker-compose topology (services,
ports, protocols) cross-checked against
integration-tests/docker-compose.ymlandintegration-tests/src/main/docker/sheriff-config/gateway.yaml.doc/development/README.adoc— indexes the new standard and the new reference diagram..plan/project-architecture/**/enriched.json— architecture-inventory snapshot refresh (plantooling artifact, not hand-authored content).
Test Plan
python3 .plan/execute-script.py plan-marshall:build-maven:maven run --command-args "verify -Ppre-commit")Related Issues
No linked issue.
Generated by plan-finalize skill
Intent
Problem: The project's SVG diagram standard (
pm-documents:ref-svg-diagrams) has six diagramtypes and five templates, but none of them can express containment, protocol-and-port edges, or
trust boundaries — the shapes a deployment/container diagram needs. Without a standard type,
future deployment-topology diagrams would each invent their own ad-hoc conventions, and there was
no verified render path (no rasteriser installed) to prove any new SVG standard actually renders
legibly before committing to it upstream.
Chosen approach: Resolve the render-verification blocker first, as its own gate deliverable,
because the upstream standard treats render-and-read-back as non-skippable. Then author the new
deployment diagram type in dependency order — a Markdown standard shaped to graft onto the upstream
doc unchanged, a skeleton SVG template implementing it, and one concrete reference implementation
(the integration-test docker-compose topology, which is real infrastructure on disk today, not a
synthetic example) cross-checked service-by-service against the actual
docker-compose.ymlandgateway config.
Non-goals: This change does not modify the upstream
pm-documents:ref-svg-diagramsstandarditself — the new type is written to graft on unchanged, not merge it in this PR. It does not
introduce a rasteriser dependency into the build (verification used an ad-hoc
[Intent truncated — 1393 of 1557 characters shown; full outline in the plan workspace]
Summary by CodeRabbit
plan-marshall:build-server-clientdefault skill entries for both implementation and module-testing profiles, alongside existing HTTP skills.