Every diagramming tool I have tried over the years — Lucidchart, Miro, Whimsical, draw.io — solves the wrong problem. Drawing boxes was never the hard part. The hard part is translating the system that lives in your head onto a canvas, and then keeping that picture honest after the system changes. My fix was to stop drawing diagrams and start generating them. Claude writes diagram source — Mermaid, Excalidraw JSON, draw.io XML — and the moment a diagram is text, it behaves like code: you can version it, diff it, and regenerate it when reality moves.
That shift matters more to me than it might to someone with one product. I run several things at once: this site (a Laravel platform I maintain myself), Ramlit Limited (my software agency), ColorPark (design work), xCyberSecurity (security consulting), plus a Deputy Head of Development role at Electronic First. After 8+ years and 1,500+ projects, the bottleneck is never typing speed. It is holding the whole map in my head. So I made Claude hold it instead.
Why I map my business as text, not pictures
The failure mode of every whiteboard session I have ever run is the same: the diagram is accurate for about two weeks. Then a service gets swapped, a deploy pipeline changes, a venture picks up a new revenue stream, and the picture quietly becomes fiction. Nobody reopens Lucidchart to fix it, because reopening Lucidchart is work.
Text-based diagrams fix this because the source lives next to the things it describes. My ecosystem map is a Mermaid file in a repo. When I changed how mejba.me deploys (GitHub Actions rsync to Hostinger), updating the map was a three-line edit in the same pull-request mindset as everything else I ship. The diagram renders fresh from source every time, so there is no stale exported PNG pretending to be documentation.
The second reason is that Claude is genuinely good at this translation step. I describe the system in plain language, and it emits valid diagram source. I do not fight alignment guides or connector snapping. I review a diff.
The three formats I actually use
Mermaid first, always. Claude renders Mermaid natively in artifacts, so I see the diagram immediately without leaving the conversation. More importantly, Mermaid is cheap. A flowchart with forty nodes is roughly forty lines of source. The same diagram as Excalidraw JSON is thousands of lines, because every element carries coordinates, dimensions, seeds, and style fields. When I just need to see structure — what connects to what — Mermaid wins on both speed and token cost. If you are watching your usage, this is the single biggest lever; I wrote more about that in my token management notes for Claude Code.
Excalidraw JSON when layout carries meaning. Mermaid decides layout for you. Sometimes I want spatial control — the four ventures arranged around a hub, shared infrastructure grouped in one region. Excalidraw's file format is plain JSON, and Claude can write it directly. I save the output as a .excalidraw file and open it in the Excalidraw VS Code extension, so generation and preview happen in the same editor.
Draw.io XML for anything a client sees. Excalidraw's hand-drawn look is great for my own thinking and wrong for a formal proposal. Draw.io's mxGraph XML is more verbose, but the output looks like the corporate diagrams clients expect.
The arrow-binding problem nobody warns you about
Here is the detail that took me real time to learn, and the reason "just ask the AI for an Excalidraw file" disappoints people on the first try.
In Excalidraw, an arrow is either free-floating or bound to elements. A bound arrow carries a startBinding and endBinding — each referencing an element ID with a focus value and a gap — and the connected shapes list the arrow back in their boundElements array. Bound arrows move with their nodes. Free-floating arrows just sit at coordinates.
Language models, left to their own devices, tend to emit free-floating arrows. The diagram looks perfect on first render. Then you drag one node to make room, and every connection stays behind like chalk lines around a body. The first ecosystem map I generated had this problem on almost every edge, and I nearly wrote off the whole approach before I understood why.
The fix is to be explicit. My diagram prompts now always include a line like: "Every arrow must be bound: set startBinding and endBinding to the connected element IDs, and register the arrow in each element's boundElements." With that constraint stated, Claude gets the cross-references right, including the tedious bidirectional bookkeeping that makes manual JSON editing miserable.
The related lesson: prefer edits over regeneration. If a diagram is 80% right, asking Claude to regenerate from scratch scrambles positions and IDs, and you lose any manual nudges you made on the canvas. Asking it to modify the existing JSON — "add one node under xCyberSecurity, bind it into the flow" — preserves everything else.
What my actual map looks like
This is a simplified version of the Mermaid source for my venture map. It is real — these are my actual properties and how they relate:
flowchart TD
ME[Mejba Ahmed] --> MJ[mejba.me<br/>Laravel blog + portfolio]
ME --> RL[Ramlit Limited<br/>software agency]
ME --> CP[ColorPark<br/>design services]
ME --> XC[xCyberSecurity<br/>security consulting]
ME --> EF[Electronic First<br/>Deputy Head of Dev]
MJ --> INFRA[(Hostinger + GitHub Actions)]
RL --> CLIENTS[Client projects]
CLIENTS --> MJ
XC --> CLIENTS
CP --> CLIENTS
The arrows that surprised me were the ones pointing back into mejba.me. When I forced myself to draw the flows instead of just listing the ventures, I saw that agency work feeds the blog (case studies, tutorials), the blog feeds the agency (inbound leads), and the security and design ventures both route through the same client relationships. That loop was invisible to me as a list. It was obvious as a graph.
That is the honest value of this exercise. I will not claim a mapped diagram cut some process from four hours to forty-five minutes — I do not have clean before/after numbers, and anyone who gives you suspiciously tidy ones is decorating. What mapping actually did for me was decision-grade clarity: seeing which properties shared infrastructure I was paying for twice, and which manual handoffs between ventures were candidates for the automation work I describe in building an AI operating system around Claude Code.
The workflow, step by step
This is the loop I run when mapping any system, whether it is my own ventures or a client's operations at Ramlit:
- Describe before drawing. I write a plain-text outline first: the entities, the connections, what flows along each edge (money, data, work). A clear spec cuts iteration rounds, which cuts tokens.
- Generate Mermaid in an artifact. Structure review happens here. Wrong groupings and missing edges are cheap to fix at this stage.
- Promote to Excalidraw only if needed. If the diagram is going to be worked on spatially — annotated in a workshop, rearranged by hand — I have Claude translate the agreed structure into Excalidraw JSON with bound arrows.
- Commit the source. The
.mmdor.excalidrawfile goes into the relevant repo. The diagram is now documentation that travels with the code. - Update by diff. When the system changes, I change the source and re-render. No archaeology in a drawing tool.
The same generate-review-commit rhythm shows up in my visual design workflow with Claude Code, and the design-system version of it in my Claude and Figma workflow. Diagrams are just another artifact type once you treat their source as the product.
Where this pays off
Three uses have earned a permanent place in how I operate:
Onboarding. Explaining the Ramlit project pipeline to a new developer used to be a rambling call. Now it is a rendered diagram plus twenty minutes of questions. The diagram does not drift because it is regenerated from source that gets updated when the pipeline does.
Automation triage. When a workflow is drawn as a graph, the mechanical steps are visually distinct from the judgment steps. I color-code them — automated, automatable, must-stay-human — and that becomes the backlog. Every automation I have shipped for my own operations started as a colored node on one of these maps.
Client communication. A draw.io process diagram in a proposal does more than a page of prose. Clients point at boxes. Pointing at boxes is the highest-bandwidth requirements conversation I know.
If you run more than one thing — a product and a side business, an agency and a blog — the map is worth an afternoon. Start with one process, the one you explain most often, and generate it rather than draw it. You will update a text file. You will not update a Lucidchart document. That difference is the whole method.
Where these maps actually break is not the diagram — it is the first automation someone builds on top of a map nobody updated. Turning real operations into a living, versioned diagram before that automation push is part of my consulting work, and the contact page is the fastest way to start that conversation.
