Skip to content

Commit de849a7

Browse files
committed
docs: fix handlers_describe reference and mermaid size claims
- handlers_describe is an MCP tool, not a gRPC endpoint; clarify the browser reads from the schema registry gRPC service directly - Remove inaccurate "< 50KB gzipped" mermaid.js claims (actual size with dagre is ~200KB+); reframe the Mermaid vs @xyflow/react comparison around portability and automatic layout instead of bundle size
1 parent 3069b74 commit de849a7

1 file changed

Lines changed: 14 additions & 12 deletions

File tree

docs/prd/036-cookbook-browser.md

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -273,8 +273,8 @@ Mermaid is the right tool here because:
273273

274274
- The Starlark flow is inherently linear with branches
275275
— exactly what Mermaid flowcharts express
276-
- mermaid.js is already a standard rendering library
277-
(< 50KB gzipped for the flowchart module)
276+
- mermaid.js is a standard rendering library with
277+
automatic layout (dagre) built in
278278
- GitHub, GitLab, and Markdown tools render it natively,
279279
making the generated diagrams portable
280280
- Starlark's bounded nature (no while loops, no
@@ -329,10 +329,12 @@ Service: position_keeping
329329
```
330330

331331
**Data path**: The handlers.yaml is already parsed by
332-
the schema registry at startup and served via an
333-
existing gRPC endpoint (`handlers_describe`). The
334-
browser reads from this same endpoint — no new data
335-
path, no separate docs to maintain. When a developer
332+
the schema registry at startup. The MCP server exposes
333+
this via `meridian_handlers_describe`, and the
334+
underlying data is available through the schema
335+
registry's gRPC service. The browser reads from this
336+
same service — no new data path, no separate docs to
337+
maintain. When a developer
336338
adds a parameter to handlers.yaml, it appears in the
337339
browser on the next deploy because it IS the same
338340
data.
@@ -517,8 +519,8 @@ page) is an open question — see OQ5.
517519

518520
### Phase 4: Service Module Reference
519521

520-
- Fetch handler definitions from existing gRPC
521-
endpoint (handlers_describe)
522+
- Fetch handler definitions from the schema registry
523+
gRPC service (same data backing `meridian_handlers_describe`)
522524
- Render as collapsible API reference panel: service
523525
name, handler signature, typed params, returns,
524526
compensation chain
@@ -579,8 +581,7 @@ Rationale:
579581

580582
- Starlark's bounded structure (no while, no recursion)
581583
maps perfectly to finite Mermaid flowcharts
582-
- mermaid.js is lightweight (< 50KB gzipped for
583-
flowcharts), well-maintained, and renders natively
584+
- mermaid.js is well-maintained and renders natively
584585
in GitHub/GitLab/Markdown tools
585586
- The generated Mermaid markup is portable — it can be
586587
embedded in ADRs, PRDs, or issue descriptions
@@ -592,8 +593,9 @@ Rationale:
592593
Alternatives considered:
593594

594595
- **@xyflow/react**: More interactive (drag, zoom) but
595-
adds ~150KB, requires layout logic, and the
596-
interactivity isn't needed for a read-only flow view
596+
requires manual layout logic, produces non-portable
597+
output, and the interactivity isn't needed for a
598+
read-only flow view
597599
- **Custom SVG**: Full design control but high
598600
implementation cost for layout algorithms
599601

0 commit comments

Comments
 (0)