Ramblings in time and measure

Documentation woes

If you’ve ever inherited a codebase, you know the feeling: no documentation, a tangle of functions, and maybe a half-finished diagram from five years ago buried in a Confluence page. Its either a minor hassle, or a huge mess.

But there’s a faster way. With Mermaid.js, you can sketch flowcharts, sequence diagrams, and class diagrams directly in text. And here’s the kicker: with tools like Copilot or ChatGPT, you don’t even have to write those diagrams yourself. The AI can analyze your code and generate the Mermaid syntax for you.

pro tip: use Mermaid Chart for access to AI diagramming tools and a whiteboard which make creating diagrams with Mermaid that much easier

---

Flowcharts: Mapping Logic in Seconds

As I have shown in earlier posts, lets start with a super simple TypeScript function for validating a todo item:

function validateTodo(todo: Todo): boolean {
  if (!todo.title || todo.title.trim() === "") {
    return false;
  }
  if (todo.title.length > 200) {
    return false;
  }
  return true;
}

Drop this into ChatGPT and ask:

“Generate a Mermaid flowchart for this function.”

You’ll get:

Sequence Diagrams: Making Interactions Obvious

In the same project, here’s a login handler:

app.post("/login", async (req, res) => {
  const { email, password } = req.body;
  const user = await db.findUserByEmail(email);
  if (!user) return res.status(401).send("Unauthorized");

  const valid = await comparePasswords(password, user.hash);
  if (!valid) return res.status(401).send("Unauthorized");

  const token = generateToken(user.id);
  res.send({ token });
});

Ask Copilot or ChatGPT:

“Show this login handler as a Mermaid sequence diagram.”

---

Class Diagrams: Data Models Without Guesswork

Your todo API might define classes like:

class User {
  id: number;
  email: string;
  todos: Todo[];
}

class Todo {
  id: number;
  title: string;
  completed: boolean;
  owner: User;
}

AI prompt:

“Create a Mermaid class diagram for these classes.”

---

A Workflow That Actually Works

Obviously those are super simple – and not the best examples to really show advanced usage. But here’s the loop I use daily:

1. With ChatGPT: Copy a function, API handler, or class. Ask for the appropriate diagram type. Paste the Mermaid output into docs. Done.
2. With Copilot in VS Code: Highlight code, type a natural-language comment like “Generate a Mermaid sequence diagram for this function.” Copilot returns the snippet inline.
3. Whole-project analysis: Open your repo in VS Code, activate Copilot chat, and ask:

   “Analyze this codebase and generate Mermaid diagrams for key flows and models.”

   The results are surprisingly coherent — you’ll get class diagrams of your main models, plus sequence diagrams for critical endpoints.
   

💡 Pro tip: Switch the Copilot model to the most recent Sonnet version. It consistently produces the most accurate, context-aware diagrams from code.

---

Why It Matters

Reverse engineering isn’t about building “perfect” UML. It’s about clarity. With Mermaid and AI, the cost of producing diagrams drops to almost nothing — so your docs actually get written.

Instead of a dreaded documentation sprint, you can generate diagrams alongside your code in minutes.

---

Try It Yourself

Open VS Code right now. Highlight a function. Ask Copilot for a Mermaid diagram. Or paste a class into ChatGPT and see what happens.

What used to take hours now takes seconds — and your codebase will finally have the diagrams it deserves.