docs(architecture): the consumers diagram carries the shape, not the list - #377
Conversation
…list Three subgraphs of three unconnected nodes each: mermaid laid them out nine boxes wide, and the leaves duplicated the table directly below them. A diagram should carry what is actually shaped — the waist and the fan-out — so it is now five boxes on one line, and the twelve leaves fold into the Python-surface table as rows. That table gains a "you want to" column and the planned entries the dashed boxes used to hold, so solid-vs-dashed becomes an italic row rather than a line style a caption has to explain. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 13 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: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
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 |
Two things went vague when the consumers diagram lost its subgraph titles. The contract: the waist box now names itself (MathSchema) and says what it guarantees — names typed, dims checked, degree judged — and `check it` says what it does rather than asking a question, since parse → expand → validate → lower IS the answer to "will this build". Where data enters: the "no data, no solver" / "the only part that touches your data" distinction was carried by the old subgraph titles and had simply gone. It is back as an arrow — one, into `run it` — which is stronger, because the boundary is a shape rather than a caption. The surface table gains a `data?` column for the same reason, plus a paragraph on what the mapping must contain: binding is by name at both levels, with one narrow positional fallback for an unnamed pandas index, which is documented because renaming named levels would transpose data silently. In the pipeline diagram, `lowering.py` and `sources.py` move out of the relational/ box. Both are flat modules, so drawing them inside a box captioned "imports nothing from the package but errors.py" was false — both read the schema. Outside and dashed, they read as what they are: the seam, and the place data arrives. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The data cylinder fed only sources.py, which said the linopy lane builds models out of nothing. It takes data= and coerces it in linopy/loader.py — a separate path that never calls tidy_sources, because one lane wants tidy polars frames and the other an xr.Dataset. Drawn as a second, dotted arrow, matching the AST's own opt-in edge into that lane: both the math and the data reach it only if you ask for it. The prose names the split and the one thing the lanes do share — the convex: curvature guard, which needs values rather than a schema, which is why it sits with the data where both can call it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Listing pandas as an input shape on the pipeline diagram contradicts the dependency story three sections below it — pandas is a bridge *out*, shipped with the [linopy] extra, and the bare-install job runs the suite without it. It was never needed on the label either: a pandas frame is accepted because it exports the Arrow PyCapsule protocol, so "any Arrow table" already covers it. Both cylinders now read parquet · polars · any Arrow table. The remaining pandas mention is the unnamed-index positional fallback, which is genuinely pandas-specific and stays. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 participant
The last commit of #375 raced the merge and did not land — this is that commit, rebased onto main. The nine-box diagram is what is on
maintoday.The problem
The consumers diagram had three subgraphs of three unconnected nodes each. With no edges between them
direction TBdoes nothing, so mermaid laid them out horizontally: nine boxes wide. And once #375 put the API names in the leaves, those leaves duplicated the table sitting directly below them.Stacking the nodes with invisible links (
~~~) fixes the width, but trades it for height — very tall, with large gaps — and does nothing about the duplication.The fix
A diagram should carry what is actually shaped: the narrow waist and the fan-out. A list of twelve capabilities is not shaped, it is a list — and it now has a table.
Five boxes, one line. The twelve leaves fold into the Python-surface table as rows, which is where the names already were.
"Ships today vs. cheap to build" was a line style the caption had to explain ("solid is what ships; dashed is what the shape makes cheap"). It is now an italic row in that table, sitting next to the thing it is a variant of.
Net −33 lines.
Re-rendered through
mermaid-clito confirm.Verification
709 passed / 4 skipped / 1 xfailed ·
ruff checkclean ·mkdocs build --strictclean. Documentation only — no source change.🤖 Generated with Claude Code