Introducing Swark: Automatic Architecture Diagrams from Code

Rifx.Online
Programming , Technology , Machine Learning
14 Jan, 2025

Software architecture is hard to get right. Misaligned teams, unclear diagrams, and time-consuming processes often result in frustration and suboptimal design decisions. As engineering teams embrace a decentralized, collaborative approach to architecture, the stakes grow even higher.

In my previous article, “Software Architecture is Hard”, I explored these challenges in depth, highlighting the critical gaps in communication and diagramming standards that plague many teams.

In an attempt to make software architecture a bit easier, equipped with the new capabilities unlocked by AI and LLMs, I tried to tackle and automate one of the most vital parts of software architecture — diagramming.

Meet Swark

Swark is a free and open source VS Code extension that allows creating architecture diagrams from code automatically using large language models (LLMs).

Within a few clicks, you can create an architecture diagram for your repository:

Why Swark?

🌟 Free and Open Source: All you need is GitHub Copilot, which is now available for free. You can review Swark’s code to understand how it works, and contribute to make it better.
🌍 Universal Language Support: Classic code visualization solutions are deterministic and require to incrementally add support in new languages or frameworks. With Swark, all the “logic” is encapsulated within the LLM, and therefore it natively support all languages.
🔑 Seamless Integration: Swark integrates directly with GitHub Copilot. No additional setup, authentication, or API keys required.
🛡️ Privacy First: Your source code is shared only with GitHub Copilot — no other external APIs or providers involved.
🧜‍♀️ Mermaid.js: Swark generates diagrams in Mermaid.js, a popular diagram-as-code framework. You can edit and refine the diagrams as needed.

Use Cases

🔎 Learn a New Codebase: Instantly generate architecture diagrams to gain a high-level understanding of unfamiliar repositories. Ideal for onboarding and tackling new projects.
🤖 Review AI-Generated Code: As AI-generated projects become more common, Swark helps you quickly visualize their structure and ensure they meet your standards.
📕 Improve Documentation: Keep your documentation fresh and detailed with up-to-date architecture diagrams that take minutes to create.
🧩 Spot Design Flaws: Visualize your repo’s dependency graph to identify unwanted dependencies or areas for optimization.
✅ Test Coverage Insights: Include test files in Swark’s input to see test coverage at a glance and address gaps.

How It Works

File Retrieval: Swark retrieves code files within the chosen folder. Swark automatically adjusts the number of retrieved files to match the LLM max token limit.
Prompt Building: based on the retrieved files, Swark builds a prompt to generate an architecture diagram. The code files are included in the prompt, together with instructions on how to build the diagram.
LLM Request: Swark invokes LLM request to GitHub Copilot via VS Code Language Model API.
Diagram Preview: upon a successful response, the diagram is presented. This is done by creating a markdown file that includes the diagram in Mermaid syntax and previewing it.