https://leomata.com/ Recent content on Leo Mata Hugo en-us Sat, 27 Jun 2026 10:00:00 +0000 https://leomata.com/blog/passwordless-auth-email-delivery/ Sat, 27 Jun 2026 10:00:00 +0000 https://leomata.com/blog/passwordless-auth-email-delivery/ We were adding passwordless sign-in to a client’s mobile and web app. Instead of a password, the user receives a sign-in link or a short code by email and enters it. It removes a stored credential and is usually fewer steps than a social login. The approach depends on the email being delivered. The code has to reach the user’s actual mailbox. A send that the mail provider accepts is not the same as a message the user receives, and if the code does not arrive, the user cannot log in. https://leomata.com/blog/brocs/ Sat, 23 May 2026 10:00:00 -0400 https://leomata.com/blog/brocs/ I was sitting with a friend who runs engineering at a healthtech startup, big name, redacted. PHI on the line, audit obligations, the kind of company where a wrong move means a press release no one wants to write. He had been working through the AI tooling market for a few weeks, evaluating what was available against what his organization actually needed. Each option solved a piece. None gave him a coherent answer for the whole. https://leomata.com/blog/cynefin-shipped/ Wed, 06 May 2026 12:00:00 +0000 https://leomata.com/blog/cynefin-shipped/ PR #7535 merged today. Mermaid now has a Cynefin framework diagram type, the first text-based DSL for Cynefin diagrams anywhere. This post wraps up the series. Eight months, eight posts, two diagram implementations, one merged PR, and a lot of lessons about how open source actually works. If you’re not familiar with the Cynefin framework, I wrote a full introduction earlier in this series. The short version: it’s a sense-making model that helps you decide how to decide, by categorizing problems into five domains based on the relationship between cause and effect. https://leomata.com/blog/cynefin-101/ Sun, 05 Apr 2026 10:00:00 +0000 https://leomata.com/blog/cynefin-101/ At the end of the last post, I said I was building Cynefin diagram support for Mermaid next. Before I get into the implementation, I want to talk about the framework itself, because it deserves a proper introduction. How I Found Cynefin Years ago at the Wikimedia Foundation, my Director introduced me to the Cynefin framework. He used it to map and manage the complexity of the ecosystems we operated in: infrastructure serving billions of requests, volunteer communities with their own dynamics, legacy systems interacting with bleeding-edge deployments. https://leomata.com/blog/wardley-maps-the-race/ Thu, 26 Mar 2026 20:00:00 +0000 https://leomata.com/blog/wardley-maps-the-race/ I spent the better part of three weekends building a complete Wardley Map diagram type for mermaid-js, the popular text-to-diagram library. It was thorough. It was modular. It was tested. And by the time I opened the PR, someone else had already merged theirs. Here’s what happened, and why I’d do it all again. Why Wardley Maps? If you’re not familiar, Wardley Maps are strategy diagrams created by Simon Wardley. They plot components of a value chain along two axes: visibility (how visible something is to the user) and evolution (how mature something is, from genesis to commodity). https://leomata.com/blog/what-is-a-software-factory/ Wed, 25 Mar 2026 10:00:00 +0000 https://leomata.com/blog/what-is-a-software-factory/ There is one metric that matters in software: did the idea ship as a live, running product? Not a prototype. Not a demo. Not a repository with a promising README. A working system, deployed, used. Everything else is work in progress. This sounds obvious. It isn’t. Most of the industry is optimizing for the wrong things — generating code faster, writing tests automatically, producing documentation on demand. These are useful. They are not the goal. https://leomata.com/blog/wardley-mermaid-next-steps/ Tue, 25 Nov 2025 10:00:00 +0000 https://leomata.com/blog/wardley-mermaid-next-steps/ The Wardley Map PR is in draft, working through code review. Here’s what’s on the roadmap once the core implementation lands. Immediate Priority: Regions The most requested Wardley Map feature. Regions let you group components into market segments, organizational boundaries, or areas of focus: wardleyMap title Platform Strategy region "Core Platform" [0.3, 0.4, 0.8, 0.9] region "Partner Ecosystem" [0.1, 0.2, 0.7, 0.4] component api "API" [0.5, 0.7] component db "Database" [0. https://leomata.com/blog/wardley-mermaid-deep-dive/ Sat, 22 Nov 2025 10:00:00 +0000 https://leomata.com/blog/wardley-mermaid-deep-dive/ For those curious about the internals, here’s how a Mermaid diagram type comes together. This is the architecture I followed to build Wardley Map support. The Stack Input (DSL) → Langium Grammar → Parser → AST → Database → Renderer → SVG Each layer has a specific job. Data flows one direction. No layer reaches back into a previous one. Let’s walk through them. Layer 1: Grammar The grammar file defines what’s valid syntax. https://leomata.com/blog/building-the-pr/ Mon, 17 Nov 2025 10:00:00 +0000 https://leomata.com/blog/building-the-pr/ Time to actually build Wardley Map support for Mermaid. Here’s the journey from “I should do this” to a working PR. Understanding the Codebase Mermaid is a mature project—70k+ stars, hundreds of contributors, years of history. Before writing code, I spent time understanding: How existing diagram types are structured: Each diagram type lives in packages/mermaid/src/diagrams/{type}/ The Langium-based parser architecture: Grammar files in packages/parser/src/language/ The rendering pipeline: Parse → Database → Renderer → SVG The test patterns: Unit tests, integration tests, visual regression tests The Pie, Packet, and Architecture diagrams all follow the modern Langium pattern. https://leomata.com/blog/why-mermaid/ Wed, 12 Nov 2025 10:00:00 +0000 https://leomata.com/blog/why-mermaid/ I could have built a standalone Wardley Map library. Or a VSCode extension. Or yet another web app. I chose to contribute to Mermaid instead. Here’s why. GitHub Native Mermaid is built into GitHub markdown rendering. Write a fenced code block with mermaid, and it just renders. No extensions. No build steps. No external services. ```mermaid flowchart LR A[Start] --> B[End] That's the dream: strategic diagrams that live in your README, your ADRs, your planning docs. https://leomata.com/blog/the-missing-diagram/ Fri, 07 Nov 2025 10:00:00 +0000 https://leomata.com/blog/the-missing-diagram/ So I wanted Wardley Maps in my workflow. Native. Version-controlled. In markdown. Living alongside my code and documentation. The options were… limited. What Exists Today I spent a weekend evaluating every Wardley Map tool I could find: OnlineWardleyMaps: The gold standard for web-based mapping. Great UI, good export options. But it’s a separate app—you create maps there, export images, paste them into docs. They become stale immediately. No version control. No diffs. https://leomata.com/blog/wardley-mapping-101/ Sun, 02 Nov 2025 10:00:00 +0000 https://leomata.com/blog/wardley-mapping-101/ I’ve been using Wardley Maps to think through strategy for Calliope AI, and I’m convinced more people should know about this tool. It’s changed how I approach technical strategy, and I want to bring it to more engineers. What is a Wardley Map? Created by Simon Wardley, it’s a visual way to map out your value chain and understand where things are headed. The map has two axes: Y-axis (Visibility): From infrastructure at the bottom to user-facing needs at the top. https://leomata.com/drafts/linkedin-cynefin-shipped/ Mon, 01 Jan 0001 00:00:00 +0000 https://leomata.com/drafts/linkedin-cynefin-shipped/ Cynefin diagrams now have a text-based DSL in Mermaid, for the first time! A friend introduced me to the Cynefin framework as a tool to map and manage complexity. I’m in no way an expert, but the bits I’ve picked up have changed how I think about problems, and I became a big fan. The Cynefin framework, created by Dave Snowden, is a conceptual sense-making model used to help identify the nature of a situation and determine the most appropriate approach to problem-solving. https://leomata.com/drafts/linkedin-passwordless-email-delivery/ Mon, 01 Jan 0001 00:00:00 +0000 https://leomata.com/drafts/linkedin-passwordless-email-delivery/ Passwordless sign-in is only as reliable as your email delivery. We’ve been adding email-based sign-in to a client’s app: a link or a code instead of a password. It is a good user experience, and it moves your login reliability onto one thing, email actually being delivered. If the message does not arrive, the user cannot get in. For the major mailbox providers we can test directly, because we keep accounts and can open them.