docs(warehouse-native): convert mode diagrams to architecture-beta (FT-2119) - #285
Closed
joalves wants to merge 11 commits into
Closed
docs(warehouse-native): convert mode diagrams to architecture-beta (FT-2119)#285joalves wants to merge 11 commits into
joalves wants to merge 11 commits into
Conversation
joalves
requested review from
bmsilva,
calthejuggler and
marcio-absmartly
as code owners
August 8, 2026 17:50
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. 🗂️ Base branches to auto review (3)
Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Comment |
✅ Deploy Preview for absmartly-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
… architecture-beta diagrams The mermaid init directive forced "theme": "base" with a hardcoded dark navy primaryTextColor, which overrode Docusaurus's automatic per-colorMode mermaid theme and made node labels nearly unreadable in dark mode (the old flowchart diagrams got away with this because their nodes had solid fill backgrounds; architecture-beta nodes render icon-only with no background box). Also two service nodes rendered directly on top of each other in both diagrams due to fcose's default layout, and adjacent group headers visually collided. Removed the theme override so Docusaurus's dark/default mermaid theme takes over color, added architecture-beta layout tuning (padding, nodeSeparation, idealEdgeLengthMultiplier, numIter, seed) for spacing, and adjusted edge port routing on 4 edges to resolve node/group overlap. Topology (which nodes connect to which) is unchanged.
…layout
The previous fix reduced overlap by hand-tuning individual edge ports,
but still left a scattered diagonal layout with a long crossing edge
(fcose's force-directed layout has no notion of "tidy grid" on its own).
architecture-beta has an explicit `align row {ids}` / `align column {ids}`
directive built for exactly this: declaring that a set of nodes share a
row or column, which architectureDb turns into hard alignment constraints
for the layout solver instead of leaving positioning to force simulation.
Restructured both diagrams as a 2-row grid (top row: SDK/sources, bottom
row: attributes/filter/query) with explicit align directives, which
eliminates the diagonal sprawl and produces mostly-straight edges.
Also bumped iconSize (80->100) so wrapped multi-line labels have more
width per line, fixing "Assignment ... data stored" clipping past its
group's bottom border, and trimmed the label itself slightly (the
"logic"/"metric" wording it dropped is already covered in the adjacent
prose paragraph, so no content is lost). Topology (which nodes connect
to which, and the direction of each edge) is unchanged.
…gonal sprawl engine wasn't part of any align row/column constraint, so fcose placed it wherever the force simulation happened to settle -- in practice, far from query in an isolated corner, with the query<->engine edges stretching diagonally across the full canvas. Adding engine to the same align row as query (they're directly connected) keeps it adjacent in the layout, collapsing both edges to short, near-horizontal lines instead of long diagonals. Topology is unchanged -- same two distinct directional edges between query and engine, same edge directions.
…box overlap
Putting engine in the same align row as query/filtersvc/attr packed
its group ("ABsmartly Cloud") right up against "Your warehouse
external"/"Your warehouse default", since align row only constrains
the y-axis and leaves no real gap between differently-grouped
neighbors on that axis -- config knobs (padding, nodeSeparation,
iconSize) don't affect this because align is a hard constraint that
overrides the force layout's spacing.
Moving engine to its own row, column-aligned directly below query
(their only edge), removes it from that shared axis entirely. Verified
with a programmatic overlap check against the live rendered SVG
(measuring actual group rect bounding boxes, not just eyeballing
screenshots): group box overlap area is now 0px^2 for both diagrams,
down from ~4000-5600px^2. The one remaining diagonal edge
(default->engine) is unavoidable -- default and engine are genuinely
far apart in different groups with only that one edge between them.
… overlap The Hybrid diagram's "ABsmartly default" and "Your warehouse external" group boxes still overlapped by ~4700px^2 even after the engine realignment fix -- iconSize=100 wasn't enough clearance for the cross-group edge (default->importsvc) to keep the two group boxes apart, since that edge's length is a fixed 0.5*iconSize regardless of idealEdgeLengthMultiplier (which only affects same-group edges). Verified programmatically (measuring the live rendered SVG's group rect bounding boxes, plus checking for mermaid render/lexer errors in the page) that iconSize=250 clears the overlap to exactly 0px^2 for both diagrams with the existing topology unchanged, then confirmed visually via full-page screenshots in both themes at real page width. No edges, ports, or align directives changed in this commit -- iconSize is the only difference.
…editorial SVGs Mermaid architecture-beta only exposes global edge/group theme variables, so matching the requested colorful, editorial visual treatment (blue warehouse container, coral ABsmartly Cloud, larger type) wasn't achievable without brittle CSS keyed to Mermaid's generated ids. Replaced both diagrams with hand-built, brand-tokenized SVGs (via the diagram-design skill's style system) that preserve the same topology and privacy-boundary semantics.
…ehouse-native diagrams Hybrid's ABsmartly Cloud node incorrectly claimed "no user-level data stored" — that's only true for Fully mode; Hybrid still holds exposures and any goals kept on the managed default source. Also added proper infra icons (phone, database, bucket, filter, search, cloud, chart) to both diagrams so they read as real architecture diagrams rather than plain labeled boxes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/web-console-docs/warehouse-native/modes.mdxfrom mermaidflowchart TBto nativearchitecture-betasyntax, now that the Docusaurus 3 upgrade (chore(deps): upgrade Docusaurus 2.4.3 to 3.10.x (FT-2118) #284) unlocked mermaid 11.16.1's architecture-beta support@iconify-json/mdiicon pack via DocusaurusclientModules(no swizzling) so the diagrams get richer iconography than architecture-beta's built-in 5-icon setStacking
This branch is stacked on
docs/docusaurus-v3-upgrade(#284), which has not merged yet — this PR targets that branch, notdevelopment. Retarget todevelopmentonce #284 merges.Content-fidelity notes
Three specific bugs were caught by human reviewers in earlier iterations of these exact diagrams; this PR was built and reviewed with all three as hard constraints, each independently re-verified against the final live file:
WGOALS/GOALSconnects directly toQUERY, never throughFILTERENGINE↔QUERYis two separate directional edges (query in, aggregate results out only), never one bidirectional edge (previously flagged on docs(warehouse-native): add mode architecture diagrams #282)architecture-betahas no edge-label or dashed-edge syntax, so the "exposures import" / "scheduled query" / "aggregate results only" annotations from the original flowchart were moved into an italic prose caption below each diagram instead.Test plan
yarn buildpasses cleanly ([SUCCESS] Generated static files in "build"., zero new errors)modes.mdxand matched against the original flowchart's edge list (9/9 Hybrid, 7/7 Fully)@docusaurus/theme-mermaid