Stop Drawing Architecture Diagrams Manually: Meet the Open-Source AI Architecture Review Agents

Designing software architecture represents one of the most creative aspects of engineering. Documenting it, reviewing for security flaws, and keeping diagrams updated as systems evolve? Not so much. Many developers have experienced the frustration of sketching a brilliant microservices architecture on a whiteboard, taking a blurry photo, and spending hours wrestling with diagramming tools to create something presentable. By the time the actual security and risk review begins, the architecture has already evolved.

The Architecture Review Agent, an open-source project built by Microsoft MVP Shivam Goyal and his team, addresses this common pain point. This AI-powered tool transforms architectural descriptions into structured insights and visual maps, dramatically accelerating the architecture review process.

What is the Architecture Review Agent?

At its core, the Architecture Review Agent is an automated pipeline that accepts architectural descriptions in almost any format and converts them into structured insights and interactive visualizations. Whether you feed it a strictly formatted YAML file, a Markdown design document, or even a plain English description like "We have a React frontend hitting a Kong gateway, which routes to three microservices, each with its own Postgres DB," the agent processes it in seconds.

The tool outputs three key deliverables:

1. Interactive Excalidraw Diagram: Unlike static images, this is a fully interactive diagram that can be edited directly in your browser.

2. Prioritized Risk Analysis: An automated assessment of Single Points of Failure (SPOFs), scalability bottlenecks, security gaps, and architectural anti-patterns.

3. Component Dependency Mapping: A detailed breakdown of fan-in and fan-out metrics, plus detection of orphaned components.

Smart Input Intelligence

The Architecture Review Agent was designed to adapt to how developers actually work, rather than forcing teams to learn new proprietary diagramming languages. Its input intelligence handles multiple scenarios:

• Structured inputs: When given YAML or Markdown files, the agent uses a lightning-fast rule-based parser to extract architectural information.

• Unstructured inputs: For plain text descriptions, code files, or meeting notes, the agent automatically falls back to Azure OpenAI (GPT-4.1 recommended) to intelligently infer components, their types, and interconnections.

This flexibility means teams can start using the tool immediately with existing documentation without requiring extensive reformatting or restructuring of their architectural descriptions.

Actionable, Context-Aware Reviews

The tool goes beyond simple diagram generation to provide meaningful architectural analysis. The AI examines data flows to identify real-world issues:

• Detection of shared database anti-patterns
• Highlighting missing API gateways
• Identifying infrastructure components lacking redundancy

Risks are categorized by severity (Critical to Low), helping teams prioritize their remediation efforts. The system generates specific, actionable recommendations rather than generic observations.

It's important to note that while the agent is powerful, it's designed as a co-pilot for architecture teams, not a replacement for human expertise. AI-generated risk assessments should be treated as a starting point for deeper analysis, with formal security audits still conducted by human experts.

Export Capabilities That Matter

The tool recognizes that different stakeholders need different output formats:

• High-resolution PNG exports: Perfect for presentations to architecture review boards.

• Excalidraw JSON files: Enable team collaboration and refinement of designs.

• React web UI: Allows for direct editing of diagrams without additional software.

Deployment Options

The Architecture Review Agent offers two production-ready deployment paths:

Option A: Full-Stack Web App (Azure App Service)

This approach deploys a FastAPI backend and React frontend to Azure App Service, providing teams with a custom, drag-and-drop web interface. It's ideal for organizations that want full ownership over the API surface and user experience.

Option B: Microsoft Foundry Hosted Agents

For organizations seeking a zero-operations approach, Microsoft Foundry Hosted Agents represent a compelling solution. This recently previewed service allows teams to bring their own agent code (built with the Microsoft Agent Framework) and run it as a fully managed, containerized service.

Deploying on Microsoft Foundry offers several advantages:

• Zero-ops infrastructure: The platform automatically builds containers via ACR Tasks and manages compute, scaling seamlessly from 0 to 5 replicas including cost-saving scale-to-zero capabilities.

• Built-in conversation persistence: No need to build custom databases for chat history—the Foundry Agent Service natively manages conversation state.

• Enterprise security out-of-the-box: System-assigned Managed Identities (Entra ID) with Role-Based Access Control eliminate the need to hardcode API keys.

• Publish anywhere: Once deployed to Foundry, agents can be published directly to Microsoft Teams or Microsoft 365 Copilot without additional code.

• Seamless VS Code deployment: Integration with the Microsoft Foundry for VS Code extension makes cloud deployment as simple as opening the Command Palette and following prompts.

Getting Started

The project is completely open-source and designed for rapid adoption. With Python 3.11+ and access to Azure OpenAI or a Microsoft Foundry project, teams can generate their first architecture review in minutes:

1. Clone the repository from GitHub

2. Run the setup script

3. Feed the tool your existing architecture descriptions

The tool accepts messy, informal descriptions and transforms them into professional diagrams and analyses, making it immediately valuable without requiring extensive documentation cleanup.

Strategic Implications for Development Teams

The Architecture Review Agent represents more than just a productivity tool—it addresses fundamental challenges in modern software development:

• Documentation debt: Teams often struggle to maintain up-to-date architecture documentation. This tool bridges the gap between architectural changes and documentation updates.

• Consistency in reviews: Manual architecture reviews vary significantly based on reviewer expertise. The AI provides consistent baseline analysis across all reviews.

• Early detection of issues: By analyzing architectural descriptions before implementation begins, teams can identify potential problems earlier in the development lifecycle.

• Democratization of architecture knowledge: Junior developers can benefit from AI-generated insights that might otherwise require senior architect input.

The Architecture Review Agent exemplifies how AI can augment rather than replace human expertise in technical domains. It handles the repetitive work of diagram creation and initial analysis, freeing architects to focus on higher-level design decisions and nuanced problem-solving.

For organizations adopting DevSecOps practices, this tool provides a natural integration point between architecture, security, and development workflows. The risk analysis component aligns with security-by-design principles while the interactive diagramming supports continuous architecture refinement.

The project's GitHub repository includes comprehensive documentation and examples demonstrating end-to-end architecture reviews from file upload to risk detection and diagram generation. Teams can explore the Azure-Samples/agent-architecture-review-sample repository to see the tool in action and adapt it to their specific needs.

As software systems grow increasingly complex, tools like the Architecture Review Agent will become essential for maintaining architectural integrity and security without imposing unsustainable documentation burdens on development teams.