Forem: Noah Matsell

AI Diagramming Tools for Developers

Noah Matsell — Thu, 12 Dec 2024 17:34:46 +0000

For Software Developers, diagrams are more than just visuals—they’re critical tools for understanding and communicating complex systems. Whether you’re designing a database schema, illustrating a workflow, or debugging an architecture, a well-crafted diagram can save hours of confusion.

With the rise of AI-powered tools, creating these diagrams has never been easier. In this post, I evaluate some of the most popular AI-enabled diagramming tools, including Miro, Excalidraw, Figma's FigJam, ChatGPT (with Mermaid). My goal is to see how they perform when tasked with real-world developer scenarios like sequence diagrams or database ERDs.

For this evaluation, I'll be creating two diagrams with each tool:

A sequence diagram for a simple uploading a file in a web application.

The sequence diagram prompt

Create a sequence diagram for uploading a file in a web application. The process includes:
- The user selecting a file.
- The browser sending the file to the server.
- The server validating the file.
- The server storing the file in cloud storage.
- The server sending a success response - back to the browser.
- Label the actors as User, Browser, Server, and Cloud Storage.

An entity relationship diagram (ERD) describing a simple database schema with a User, Author, and Post models.

The ERD prompt

Create an entity relationship diagram for a database schema with the following models:

- User: Attributes include id (primary key), name, and email.
- Author: Attributes include id (primary key) and bio.
- Post: Attributes include id (primary key), title, content, and authorId (foreign key).

Relationships:
- A User can create many Posts.
- An Author is associated with a User (one-to-one).
- Each Post is written by one Author.

The 4 main evaluation criteria are:

Ease of use
Customization
Accuracy
Export options + Integration with other tools

Let the testing begin!

Miro

Miro is a popular online whiteboard tool that offers a wide range of features, including diagramming, collaboration, and project management.

At the moment their "Create with AI" offering seems pretty robust. In addition to diagrams, it allows for creating stickies, docs, and images too.

Sequence Diagram Output

ERD Output

Performance Evaluation

Miro had a really strong showing here. Their AI capabilities do feel polished and well integrated in the larger context. It was easy to use and the output was accurate.

🟢🟢🟢⚪️ Ease of use
🟢🟢🟢⚪️ Export options + Integration with other tools
🟢🟢🟢⚪️ Customization
🟢🟢🟢🟢 Accuracy

Miro Total Score: 13/16 (81.25%)

Excalidraw

Excalidraw is a free, open-source whiteboarding tool for creating diagrams. It's known for its simplicity and ease of use.

Their AI offerings currently include a text-to-diagram tool and a (pretty mindblowing) diagram-to-code tool.

Sequence Diagram Output

ERD Output

Performance Evaluation

Excalidraw's AI capabilities are pretty straightforward. They don't feel quite as integrated as Miro's, but the tool is still very easy to use. Unfortunately, the output for the ERD diagram was an image, which makes it less customizable.

🟢🟢🟢⚪️ Ease of use
🟢🟢🟢⚪️ Export options + Integration with other tools
🟢🟢⚪️⚪️ Customization
🟢🟢⚪️⚪️ Accuracy

Excalidraw Total Score: 10/16 (62.5%)

ChatGPT + Mermaid

One of the many ways that ChatGPT can be used is to generate diagrams. In this case, I used ChatGPT to generate Mermaid markdown-inspired code representing the diagrams.

Sequence Diagram Output

ERD Output

Performance Evaluation

This was a bit difficult to compare against other tools. The output was extremely fast and accurate, but the process was a bit more manual. You do need a bit of technical knowledge to use Mermaid, but once you get the hang of the syntax it becomes extremely powerful. Diagrams represented in code can be easily shared, integrated, and version controlled. Unfortunately the barrier to entry is a bit higher.

🟢⚪️⚪️⚪️ Ease of use
🟢🟢🟢⚪️ Export options + Integration with other tools
🟢🟢⚪️⚪️ Customization
🟢🟢🟢🟢 Accuracy

ChatGPT Total Score: 10/16 (62.5%)

FigJam

Figma's FigJam is another whiteboarding tool that complements its original design tool. It offers a range of features for collaboration, brainstorming, and diagramming. The "Generate" AI offering is still in beta, and seems to be tucked away in the top right menu bar.

Sequence Diagram Output

ERD Output

Performance Evaluation

Unfortunately it seems like the diagramming aspect of this tool isn't really meant for prime time quite yet. I found the input options to be a bit confusing to use and, of all the tools, it had the most trouble accurately representing the diagrams. It seemed to treat everything as a simple flow chart.

🟢🟢⚪️⚪️ Ease of use
🟢🟢🟢⚪️ Export options + Integration with other tools
🟢🟢⚪️⚪️ Customization
🟢⚪️⚪️⚪️ Accuracy

FigJam Total Score: 8/16 (50%)

Top Tool and Final Thoughts

After evaluating these tools, while each has strengths and trade-offs, the clear winner here is Miro with a score of 13/16. It stands out for a comparatively mature AI offering that is well integrated in its existing ecosystem. Out of the tools tested, it's the best overall choice for developers seeking quick, accurate, and customizable diagrams.

I'll also give an honourable mention to ChatGPT + Mermaid. While it does require more technical knowledge, it shines for those who want precise, code-based outputs that are easy to version control. If you'd rather write code than mess around with a GUI, this is the tool for you.

If you're ready to streamline your diagramming workflows with AI, I'd recommend giving one of these tools a try. And if there's a tool not mentioned here, I'd love to hear about it in the comments below 👇

Fetching Liked Posts Using the Bluesky API

Noah Matsell — Sun, 08 Dec 2024 19:35:42 +0000

I've recently made the move over to Bluesky. I can already confirm that there is a vibrant tech community there with tons of interesting, useful, and inspiring content. I'm a happy new user! As a result, I've been wanting to embed my top liked Bluesky posts in my "Dev roundup" monthly newsletter posts. My aim is to provide a curated list of Bluesky posts that is specifically tailored to Software Developers.

Luckily, Bluesky's API is completely free to use, allowing programmatic access to all of the content within. This tutorial will walk you through the process of retrieving and embedding liked Bluesky posts using their API, perfect for personal blogs, portfolios, or content aggregation projects.

Understanding my Bluesky API Workflow

I have built a script that allows me to automatically embed my Bluesky posts in a markdown blog post. I think that any or all of the steps used in this script are valuable for many use-cases.

To summarize my workflow for embedding liked posts, we follow these key steps:

Create an authenticated session
Retrieve liked post URIs for an "actor"
Use these URIs to fetch oEmbed embed HTML
Clean and format the embed code

The Complete Implementation

Let's break down each function and its purpose:

1. Creating a Bluesky Session

export const createSession = async (): Promise<string | null> => {
  try {
    const response = await fetch(
      "https://bsky.social/xrpc/com.atproto.server.createSession",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          identifier: "your-handle",
          password: "your-password",
        }),
      }
    );
    const responseJson = await response.json();
    return responseJson.accessJwt;
  } catch (e) {
    console.error("Failed to create session: ", e);
    return null;
  }
};

Key Insights:

This function authenticates your Bluesky account.
- Note: this example hardcodes strings for credentials, but this should be avoided in production use cases.
It returns an accessJwt JWT (JSON Web Token) for subsequent API calls
Uses the createSession endpoint from Bluesky's ATP (Authenticated Transfer Protocol)
Error handling ensures graceful failure if authentication fails

2. Retrieving Liked Post URIs

export const getBlueskyLikeUris = async (actor: string, limit: number = 40) => {
  const token = await createSession();
  if (!token) {
    console.error("Failed to get token");
    return;
  }

  const response = await fetch(
    "https://bsky.social/xrpc/app.bsky.feed.getActorLikes?actor=${actor}&limit=${limit}",
    {
      method: "GET",
      headers: {
        Authorization: `Bearer ${token}`,
      },
    }
  );

  const responseJson = await response.json();
  const uris = responseJson.feed.map((entry: any) => entry.post.uri);

  return uris;
};

Key Insights:

Requires an authenticated session token
Uses the getActorLikes endpoint to fetch liked posts
Important -- the endpoint domain should be https://bsky.social, as this is an authenticated request.
Extracts unique URIs for each liked post
Limits to 40 posts (configurable)

3. Converting URIs to Embeddable HTML

export const getBlueskyPostEmbedMarkup = async (uri: string) => {
  try {
    const response = await fetch(`https://embed.bsky.app/oembed?url=${uri}`);
    const responseJson = await response.json();

    const formattedHTML = prettier.format(responseJson.html, {
      parser: "html",
      plugins: [require("prettier/parser-html")],
      htmlWhitespaceSensitivity: "ignore",
      printWidth: 1000,
    });

    return formattedHTML.replace(/<script[\s\S]*?<\/script>/g, "");
  } catch (e) {
    console.error("Failed to get Bluesky post embed markup");
    return null;
  }
};

Key Insights:

Uses Bluesky's oEmbed endpoint with post URIs to access a post's embeddable HTML
Optional: Utilizes prettier to format the HTML consistently
Optional: Removes <script> tags for security and clean embedding
- The reason for this is that I embed a single Bluesky script for each post containing Bluesky content.
Flexible error handling

Putting It All Together: A Complete Example

async function embedLikedPosts() {
  try {
    // Get liked post URIs
    const likedPostUris = await getBlueskyLikeUris();

    if (!likedPostUris) {
      console.error("No liked posts found");
      return;
    }

    // Convert URIs to embed HTML
    const embedPromises = likedPostUris.map(getBlueskyPostEmbedMarkup);
    const embedHtmlArray = await Promise.all(embedPromises);

    // Filter out any failed embeds
    const validEmbeds = embedHtmlArray.filter(embed => embed !== null);

    // Return the markup for all liked posts
    return `
      ## Some Fave Posts 🦋
      ${validEmbeds.join(`\n\n`)}
    `
  } catch (error) {
    console.error("Error embedding Bluesky posts:", error);
  }
}

Potential Enhancements

This solution works for me because all that I require is a statically generated monthly blog post.

Some improvements could include:

Add pagination support for fetching more than 40 liked posts
Implement caching to reduce unnecessary API calls
Create a more robust error handling mechanism
Creating mechanism for refreshing accessJwt token if used in long running processes
Sorting liked posts by popularity (likes)

Troubleshooting Tips

Verify your Bluesky credentials are correct
Check that the Bearer token is being set correctly on your authenticated requests.
Verify that the endpoint domains you are using are all valid.

Conclusion

Embedding Bluesky posts provides a dynamic way to showcase your social media interactions. By understanding the API workflow and implementing robust error handling, you can create engaging, personalized, and curated content integrations.

Next Steps

Experiment with the code
Customize the embed styling
Explore additional Bluesky API endpoints

Enjoy and happy tinkering! 🚀