{"slug": "teaching-openwiki-to-draw-from-no-diagrams-to-an-upstream-pr", "title": "Teaching OpenWiki to Draw: From “No Diagrams” to an Upstream PR", "summary": "A developer successfully added Mermaid diagrams to OpenWiki, LangChain's LLM-powered code documentation tool, by modifying its prompts to generate sequence and entity-relationship diagrams. The experiment revealed that auto-generated diagrams require syntax validation to avoid rendering errors, leading to a pull request that adds diagram support to the upstream project.", "body_md": "In [Part 1](https://medium.com/towards-artificial-intelligence/openwiki-source-code-docs-that-write-and-maintain-themselves-a-hands-on-look-fcec781e28e4) I covered what OpenWiki is — LangChain’s take on Karpathy’s “LLM Wiki,” applied to codebases. In [Part 2](https://medium.com/@reachyogeshchavan/b6cfd1180c38) I ran it for real and learned that model choice makes or breaks an agentic doc run. This part is about the thing I *didn’t* get on the first pass, and what happened when I chased it: **diagrams.**\n\nIt turned into the most satisfying leg of the whole experiment — because it ended not with a workaround in my own copy, but with a pull request against the actual project.\n\nOpenWiki produced a genuinely good wiki for my Spring Boot + Angular monorepo — architecture overview, auth flow, domain model, API surface, the works. All accurate, all source-grounded.\n\nAll prose and tables.\n\nNot a single diagram. And for a codebase, that’s a real miss. The fastest way to explain a JWT refresh handshake or how Booking, Event, and Settlement relate isn't a paragraph — it's a picture. A newcomer skims a sequence diagram in five seconds and *gets* it. So the obvious question: can I get OpenWiki to draw?\n\nIf you want diagrams that live inside a docs-as-code wiki, the format matters. I went with **Mermaid** [1], and the reasoning is worth stating because it’s the same logic that makes OpenWiki itself work:\n\nMermaid is *just fenced markdown* — a ``` mermaid block. It stays diffable, it versions alongside the code, and it renders where the docs already live. (One honest caveat: GitHub and GitLab render it natively; **Bitbucket's file view historically does not**, so verify your host before assuming inline rendering. Agents and Obsidian read it fine either way.)\n\nHere’s the thing that clicked. OpenWiki [2] is **prompt-driven** — under the hood it’s an LLM writing markdown files. If it can write a table, it can write a ``` mermaid block. Diagrams aren't a missing *feature*; they're a missing *instruction*.\n\nSo I ran a deliberately tight, one-off pass on an isolated copy — using Opus, the reliable choice from Part 2 — asking it to add exactly two diagrams and touch nothing else: a sequence diagram of the auth flow, and an ER diagram of the core entities. “Read only the files needed to make these accurate.”\n\nIt nailed it. Not “plausible-looking” — *accurate*. It opened the actual auth interceptor and read the token lifetimes out of config. The sequence diagram it produced:\n\nIt even captured the single-in-flight-refresh behaviour — the detail where concurrent 401s queue behind one refresh call — because it read that out of my interceptor. And in the ER diagram it correctly drew one relationship as a “soft link,” having noticed that a foreign-key-shaped column was actually a plain Long with no ORM relation. That's the difference between a diagram that helps and one that lies.\n\nThen I tried to render the sequence diagram. It failed.\n\nNot the content — the **syntax**. Opus had written a message label like store new token; queue concurrent 401s. In a Mermaid sequence diagram, a semicolon is a *statement separator*. That one ; split the line into a second, malformed statement, and the parser rejected the entire block. On GitHub it would have rendered as nothing — or as a raw error box.\n\nThe content was correct. A single poison character made it un-renderable.\n\nThis is the lesson worth carrying: **auto-generated diagrams need a validation pass.** The model gets the meaning right and occasionally gets the grammar wrong, and Mermaid has a few characters — semicolons, pipes, unescaped angle brackets — that quietly detonate inside labels. A mermaid lint step in CI catches this class of bug for free.\n\nA one-off prompt gave me diagrams once. But I run openwiki --update on new commits — would the diagrams survive? Would they stay in sync? I didn't want to guess, so I read the source.\n\nTwo findings changed my whole approach:\n\nI also checked whether AGENTS.md could serve as a persistent \"please draw diagrams\" instruction. It can't — OpenWiki reads that file only to manage its own reference stub, and treats other docs as *source material to document*, not as authoring instructions.\n\nConclusion: a durable diagram capability can’t be a prompt I remember to type. It has to live in the system prompt, and it has to explicitly tell update runs to *keep diagrams in sync* and to *follow label-safety rules.*\n\nThe quick path was to patch my own copy’s system prompt and move on. But this is open source, and the same gap will bite anyone who runs OpenWiki. So I built it as a **contributable feature** instead.\n\nThe design, optimized to actually get merged:\n\nEverything green: the full test suite (plus the new tests), typecheck, lint, and formatting.\n\nThis is the question a maintainer will ask, and it has a real answer. A one-off prompt only affects one run. A setting buys three things a prompt can’t:\n\nThat framing — *durability + correctness + discoverability*, not mere convenience — is what turns “nice idea” into “worth a config key.”\n\nShipping to someone else’s project is as much etiquette as code. The project’s CONTRIBUTING is blunt: **one PR = one change**, and *link an issue for anything non-trivial.* So:\n\nA quick note on sequencing, because I went back and forth on it: the textbook move is “open the issue, wait for a maintainer 👍, *then* PR.” But that advice was written for *before* you have code. Once you’re holding a complete, CI-clean, tightly-scoped implementation — and you’re wary of someone else grabbing the issue — opening the PR that references the issue is a legitimate, often *preferred* move. Design discussion and code review happen in one place, and an issue with a linked PR is effectively claimed. CONTRIBUTING only required me to *link* an issue, never to wait for approval. So I opened it.\n\nThe result of chasing a missing feature through a demo, a bug, a source dive, and a design:\n\nWhether or not it merges in exactly this shape, that’s the arc I wanted to share: a prompt-driven tool is *extensible by anyone who reads its prompts*, the failure modes are real but small (a semicolon!), and the most satisfying way to close a gap in an open-source tool is to close it for everyone.\n\n[1] “Mermaid — diagramming and charting tool,” official documentation. Available: [https://mermaid.js.org](https://mermaid.js.org)\n\n[2] LangChain, “OpenWiki,” GitHub repository. Available: [https://github.com/langchain-ai/openwiki](https://github.com/langchain-ai/openwiki)\n\n[3] Y. Chavan, “feat: add optional Mermaid diagram generation (OPENWIKI_DIAGRAMS),” langchain-ai/openwiki, Pull Request #199. Available: [https://github.com/langchain-ai/openwiki/pull/199](https://github.com/langchain-ai/openwiki/pull/199)\n\n*← Back to **Part 2** · Start at **Part 1*\n\n[Teaching OpenWiki to Draw: From “No Diagrams” to an Upstream PR](https://pub.towardsai.net/teaching-openwiki-to-draw-from-no-diagrams-to-an-upstream-pr-b596f352154e) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.", "url": "https://wpnews.pro/news/teaching-openwiki-to-draw-from-no-diagrams-to-an-upstream-pr", "canonical_source": "https://pub.towardsai.net/teaching-openwiki-to-draw-from-no-diagrams-to-an-upstream-pr-b596f352154e?source=rss----98111c9905da---4", "published_at": "2026-07-10 21:01:01+00:00", "updated_at": "2026-07-10 21:11:05.118306+00:00", "lang": "en", "topics": ["large-language-models", "developer-tools", "ai-agents"], "entities": ["OpenWiki", "LangChain", "Mermaid", "GitHub", "GitLab", "Bitbucket", "Opus"], "alternates": {"html": "https://wpnews.pro/news/teaching-openwiki-to-draw-from-no-diagrams-to-an-upstream-pr", "markdown": "https://wpnews.pro/news/teaching-openwiki-to-draw-from-no-diagrams-to-an-upstream-pr.md", "text": "https://wpnews.pro/news/teaching-openwiki-to-draw-from-no-diagrams-to-an-upstream-pr.txt", "jsonld": "https://wpnews.pro/news/teaching-openwiki-to-draw-from-no-diagrams-to-an-upstream-pr.jsonld"}}