Journey flow diagrams in /map (Mermaid, crawler-generated)#8
Open
roobottom wants to merge 4 commits into
Open
Conversation
Per-journey flow diagrams generated deterministically by crawling the live app.
- scripts/flow-crawl.js: drives the running prototype (Playwright), seeds entry
state once via the preview-data query param, submits each screen's rendered
form, follows redirects, maps URLs to step ids, and writes flow.mmd. Live
versions only (versions.json `live` flag).
- scripts/flow-validate.js: node-id = step-id checks + coverage warnings.
- API: buildJourneyModel serves flow:{mermaid}|null + flowExpected.
- Frontend: mermaid dep + FlowDiagram (clickable step nodes -> step detail);
JourneyPage gains a header Board/Flow tab toggle.
Crawls linear Continue-flows cleanly (create-*, cancel-a-date-range). Hub-and-
spoke change-* journeys and branch decisions are Phase 2.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The crawler now explores via re-seed + replay: a screen with a submit button is submitted; a screen without one (an edit summary hub) has its in-journey "Change X" links followed. A trailing /success URL with no map.json step maps to a synthetic ext_success terminal node (fixes the cancel cross-journey handoff). Now crawls change-single-clinic (summary -> date/times/services -> check-answers -> success), change-clinic-series and sites in addition to the linear flows. Remaining: affected-bookings decision branch (needs multi-state seeding), change-one-off entry redirect, and a couple of coverage gaps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Crawls each journey once per distinct variant `data` seed and merges the graphs. When the entry lands on different first screens across seeds (a state-driven decision, e.g. cancel routes to affected-bookings when the clinic has bookings, else check-answers), a decision_start diamond is emitted. Optional map.json `flowEntry` lets a journey start at a redirecting URL. Cancel journeys now render the affected-bookings decision diamond; create-clinic -series picks up the conditional closures step. Change-flow affected-bookings is change-driven (recomputed from an edit) and is left for /flow-annotate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- .github/prompts/flow-annotate.prompt.md: an agent reads the routes to label decision diamonds and add change-driven branches the crawler can't reach, refining (never redrawing) the crawled flow.mmd, then runs flow:validate. - AGENTS.md §12 documents the flow.mmd artifact, the live-only rule, the node-id = step-id convention, flow:crawl/flow:validate, and the golden rule to regenerate from the app rather than hand-draw structure. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.
Adds a flow diagram per journey to
/map, generated deterministically by crawling the running prototype — so developers can see how screens connect (logic, branches, decisions), not just the screenshots.How it works
npm run flow:crawldrives the live app (Playwright, reusing the screenshot harness): seeds entry state once via the preview-data query param, submits each screen's own rendered form (valid by construction) or follows "Change X" hub links, follows the real redirects, maps URLs back tomap.jsonstep ids, and writesapp/journeys/<version>/<journey>/flow.mmd. Deterministic (fixed fixtures + thetodayoverride), committed like the screenshots.dataseed and emits adecision_*diamond where the entry routes to different first screens across seeds (state-driven, e.g. cancel → affected-bookings vs check-answers)."live": trueinapp/map/versions.json, currentlyv4); historic screenshot-only versions show no Flow tab.npm run flow:validate: node id = step id (clickable), errors on unknown step nodes, warns on coverage gaps./flow-annotate(.github/prompts/): an agent reads the routes to label decision diamonds and add change-driven branches the crawler can't reach — refining, never redrawing, the crawled diagram. Documented in AGENTS.md §12.What crawls
9 of 11 v4 journeys render flows: create-* (linear), change-single-clinic / change-clinic-series / sites (hub-and-spoke), cancel-* (with the affected-bookings decision diamond).
Known limits (by design)
/flow-annotate.flow:validatewarns it's missing for change-* journeys.change-clinic-that-is-part-of-a-clinic-seriesenters via a stale today-relative session id (redirects to/clinics/week) so it's flowless — a fixture-drift issue, not the crawler.clinicsis a browse area (no sequential flow).Verify
npm start(Node 22), open/map/v4/cancel-single-clinic→ Flow tab shows the decision diamond;/map/v4/change-single-clinicshows the hub-and-spoke flow; click a node to jump to its step.npm run flow:validatepasses.🤖 Generated with Claude Code