The Architecture Review Agent is an open-source AI agent sample that reviews software architectures and generates interactive diagrams - automatically. Feed it any architectural description (YAML, Markdown, plain text, code, design docs) and it returns a structured review with risk analysis, actionable recommendations, and an Excalidraw diagram you can edit and share.
Clients (Teams/M365 Copilot, CLI, Web Browser) → Foundry Agent Service or Web App → Core Engine (Smart Parser, Risk Detector, Report Builder, Diagram Renderer, LLM Inference) → Azure OpenAI / Excalidraw MCP / ACR / Azure App Service
flowchart TB
subgraph Agent["Architecture Review Agent<br/>"]
review_architecture
infer_architecture
end
subgraph Tools["tools.py"]
Parser["Parser<br/>YAML / MD / Plaintext"]
LLMInference["LLM Inference<br/>AzureOpenAIChatClient"]
RiskDetector["Risk Detector<br/>Template + LLM"]
DiagramRenderer["Diagram Renderer<br/>Excalidraw + PNG"]
ComponentMapper["Component Mapper"]
ReportBuilder["Report Builder"]
MCPClient["MCP Client<br/>(Excalidraw Server)"]
end
review_architecture --> Tools
infer_architecture --> Tools
Tools --> LocalOutputs[".excalidraw / .png / .json"]
MCPClient --> ExcalidrawMCP["Excalidraw MCP<br/>(Interactive View)"]
- Instant architecture feedback - get a prioritised risk assessment and improvement plan in seconds, not days.
- Works with what you already have - paste a YAML spec, drag in a README, or describe your system in plain English. The LLM infers structure when the input isn't formal.
- Interactive diagrams - auto-generated Excalidraw diagrams render components, connections, and data flows. Edit them in-browser or export to PNG.
- Two deployment options - run as a full-stack Web App (FastAPI + React) on Azure App Service, or as a Hosted Agent on Microsoft Foundry with Teams / M365 Copilot integration.
- Built for developers - runs locally with a single script, deploys to Azure with one command, and exposes a REST API for pipeline integration.
| Microsoft Agent Framework | Hosted agent runtime for the Microsoft Foundry deployment path |
| Excalidraw MCP Server | Interactive diagram rendering via Model Context Protocol |
| Azure OpenAI (GPT-4.1) | LLM backend for architecture inference & risk analysis |
| FastAPI + React | Full-stack web app deployment path |
Microservices Banking Architecture — full end-to-end review: file upload → risk detection → interactive Excalidraw diagram → recommendations.
If the video does not render inline, download and watch it here.
| Capability | Description |
|---|---|
| Smart Input Intelligence | Accepts any input - YAML, Markdown, plaintext arrows, READMEs, design docs, code, configs. LLM auto-infers architecture when format isn't structured |
| Architecture Parsing | Rule-based parsers for YAML, Markdown, plaintext; automatic LLM fallback for unstructured content |
| Risk Detection | Template-based detector for structured inputs; LLM-generated context-aware risks with 1-liner issues & recommendations when using inference |
| Interactive Diagrams | Renders architecture diagrams via Excalidraw MCP server for interactive viewing |
| PNG Export | High-resolution PNG output for docs, presentations, and offline sharing |
| Component Mapping | Dependency analysis with fan-in/fan-out metrics and orphan detection |
| Structured Reports | Executive summary, prioritised recommendations, and severity-grouped risk assessment |
| Web UI | React frontend with interactive Excalidraw diagrams, drag-and-drop file upload, risk tables, and downloadable outputs |
| FastAPI Backend | REST API exposing the full review pipeline - deployable to Azure App Service |
| Hosted Agent | Deploys as an OpenAI Responses-compatible API via Microsoft Agent Framework |
This sample ships with two production deployment paths. Both share the same core analysis engine (tools.py) choose the one that fits your operational model.
A traditional full-stack web application: FastAPI backend + React frontend, packaged in a single Docker image and deployed to Azure App Service.
- You own the API surface - custom REST endpoints (
/api/review,/api/infer, etc.) - Interactive browser UI - React + Excalidraw with drag-and-drop file upload, tabbed results, PNG/Excalidraw downloads
- Standard App Service model - bring-your-own infrastructure, scale via App Service Plan (manual or auto-scale rules)
- Authentication - API key or Azure AD, configured by you
Best for: Teams that want a custom UI, need to embed the API in existing tooling, or prefer full control over infrastructure and scaling.
Key files: api.py · Dockerfile.web · frontend/ · scripts/windows/deploy-webapp.ps1
A managed agent deployed to Microsoft Foundry's Hosted Agent infrastructure via the VS Code Foundry extension. The platform handles containerisation, identity, scaling, and API compliance.
- OpenAI Responses API - your agent automatically exposes the OpenAI-compatible
/responsesendpoint - Managed infrastructure - Microsoft Foundry builds, hosts, and scales the container (0 → 5 replicas, including scale-to-zero)
- Managed identity - no API keys in the container; the platform assigns a system-managed identity with RBAC
- Conversation persistence - the Foundry Agent Service manages conversation state across requests
- Channel publishing - publish your agent to Microsoft Teams, Microsoft 365 Copilot, a Web App preview, or a stable API endpoint - no extra code required
- Observability - built-in OpenTelemetry tracing with Azure Monitor integration
- Stable deployment workflow - the VS Code Foundry extension provides step-by-step guidance with automatic ACR integration, managed identity assignment, and built-in validation
Best for: Teams that want a managed, scalable API with zero infrastructure overhead, or need to publish the agent to Teams / M365 Copilot channels. The extension-based deployment flow is more reliable than script-based approaches and provides real-time feedback.
Key files: main.py · agent.yaml · Dockerfile · deployment.md
| Option A - Web App | Option B - Hosted Agent | |
|---|---|---|
| Entry point | api.py (FastAPI + Uvicorn) | main.py (Agent Framework) |
| Container | Dockerfile.web (multi-stage Node + Python) | Dockerfile (Python only) |
| API style | Custom REST (/api/review, /api/infer) |
OpenAI Responses API (/responses) |
| UI included | Yes - React + Excalidraw | No (API only; use Foundry Playground or channels) |
| Azure target | Azure App Service + ACR | Microsoft Foundry Agent Service |
| Scaling | App Service Plan (manual / auto-scale rules) | Platform-managed (0–5 replicas, scale-to-zero) |
| Identity | Configured by you (API key, Azure AD) | System-assigned managed identity (automatic) |
| Conversations | Stateless REST (you manage state) | Platform-managed conversation persistence |
| Channel publishing | N/A (custom UI) | Teams, M365 Copilot, Web preview, stable endpoint |
| Observability | Add your own (App Insights, etc.) | Built-in OpenTelemetry + Azure Monitor |
| Deployment | Scripts: .\scripts\windows\deploy-webapp.ps1 |
VS Code Foundry extension |
| Teardown | .\scripts\windows\teardown.ps1 -ResourceGroup <rg> |
Via Foundry portal |
Tip: You can run both simultaneously use the Web App for your internal team's browser-based reviews, and the Hosted Agent for API consumers and Teams/Copilot integration.
agent-architecture-review-sample/
├── main.py # Hosted agent entry point (Microsoft Agent Framework)
├── api.py # FastAPI backend (REST API for the web UI)
├── tools.py # All tool logic (parser, risk detector, diagram renderer, MCP client, PNG export)
├── run_local.py # CLI runner for local testing (no Azure required)
├── agent.yaml # Foundry hosted agent deployment manifest
├── requirements.txt # Python dependencies (pinned versions)
├── Dockerfile # Container deployment (hosted agent)
├── Dockerfile.web # Container deployment (web app - FastAPI + React)
├── deployment.md # Step-by-step deployment & RBAC guide
├── .env.template # Environment variable template
├── scripts/ # All automation scripts organized by OS
│ ├── README.md # Script usage guide
│ ├── windows/ # PowerShell scripts for Windows
│ │ ├── setup.ps1 # One-click setup (Windows)
│ │ ├── dev.ps1 # Start dev servers (Windows)
│ │ ├── deploy-webapp.ps1 # Deploy web app to App Service
│ │ └── teardown.ps1 # Delete all Azure resources
│ └── linux-mac/ # Bash scripts for Linux/macOS
│ ├── setup.sh # One-click setup (Unix)
│ ├── dev.sh # Start dev servers (Unix)
│ ├── deploy-webapp.sh # Deploy web app to App Service
│ └── teardown.sh # Delete all Azure resources
├── frontend/ # React UI (Vite + Excalidraw)
│ ├── src/
│ │ ├── App.jsx # Main app with input, tabs, and results
│ │ ├── api.js # API client
│ │ └── components/ # Summary, RiskTable, ComponentMap, DiagramViewer, Recommendations
│ ├── vite.config.js # Vite config with API proxy
│ └── package.json
├── scenarios/
│ ├── ecommerce.yaml # Sample: 12-component e-commerce microservices
│ ├── event_driven.md # Sample: 8-component event-driven IoT pipeline
│ ├── microservices_banking.yaml # Sample: microservices banking architecture
│ ├── healthcare_platform.yaml # Sample: healthcare platform
│ └── startup_mvp.yaml # Sample: startup MVP
└── output/ # Generated outputs (auto-created)
├── architecture.excalidraw
├── architecture.png
└── review_bundle.json
- Python 3.11+
- (Optional) Azure OpenAI access for LLM inference & hosted agent mode
Setup scripts are provided that create a .venv virtual environment, install all dependencies, and initialise the .env file in one step:
Windows (PowerShell):
# Clone the repository
git clone https://github.com/Azure-Samples/agent-architecture-review-sample
cd agent-architecture-review-sample
# Run the setup script (creates .venv, installs deps, copies .env.template → .env)
.\scripts\windows\setup.ps1Linux / macOS (Bash):
# Clone the repository
git clone https://github.com/Azure-Samples/agent-architecture-review-sample
cd agent-architecture-review-sample
# Run the setup script
chmod +x scripts/linux-mac/setup.sh
bash scripts/linux-mac/setup.shIf you prefer to set things up manually:
# Clone the repository
git clone https://github.com/Azure-Samples/agent-architecture-review-sample
cd agent-architecture-review-sample
# Create virtual environment
python -m venv .venv
# Activate virtual environment
# Windows (PowerShell):
.\.venv\Scripts\Activate.ps1
# Windows (cmd):
.\.venv\Scripts\activate.bat
# Linux/macOS:
source .venv/bin/activate
# Upgrade pip & install dependencies
python -m pip install --upgrade pip
pip install -r requirements.txt
# Create .env from template
cp .env.template .env # then edit .env with your settings# Copy the template
cp .env.template .envEdit .env with your settings:
# Microsoft Foundry / OpenAI Configuration
# Use PROJECT_ENDPOINT for Microsoft Foundry projects, or AZURE_OPENAI_ENDPOINT for Azure OpenAI
PROJECT_ENDPOINT=https://your-project.services.ai.azure.com/api/projects/your-project
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
MODEL_DEPLOYMENT_NAME=gpt-4.1
AZURE_OPENAI_API_KEY="your-azure-openai-api-key"
# SSL: Set to "1" if behind a corporate proxy or experiencing SSL certificate errors
# ARCH_REVIEW_NO_SSL_VERIFY=1Note: The
ARCH_REVIEW_NO_SSL_VERIFY=1flag disables SSL verification for the Excalidraw MCP server connection. Use this if you're behind a corporate proxy or firewall that intercepts HTTPS traffic. You can also set it inline:# PowerShell $env:ARCH_REVIEW_NO_SSL_VERIFY="1"# Bash export ARCH_REVIEW_NO_SSL_VERIFY=1
The local runner executes the full pipeline parse, risk analysis, diagram generation, component mapping, and structured report output.
# Analyse a YAML architecture file (rule-based parser)
python run_local.py scenarios/ecommerce.yaml
# Analyse a Markdown architecture file
python run_local.py scenarios/event_driven.md
# Inline plaintext (chained arrows supported)
python run_local.py --text "Load Balancer -> Web Server -> App Server -> PostgreSQL DB"
# With Excalidraw MCP server rendering (interactive diagram)
python run_local.py scenarios/ecommerce.yaml --render
# Feed ANY file - auto-falls back to LLM inference if not structured
python run_local.py README.md
python run_local.py design_doc.txt
# Force LLM inference (requires Azure OpenAI configured in .env)
python run_local.py some_readme.md --infer
python run_local.py --infer "We have a React frontend, Kong gateway, three microservices, and PostgreSQL"
python run_local.py --text "We have a React frontend, Kong gateway, three microservices, and PostgreSQL" --inferOutputs (saved to output/):
architecture.excalidraw- Excalidraw file for local viewingarchitecture.png- High-resolution PNG diagramreview_bundle.json- Full structured review report (JSON)
The Architecture Review Agent includes a full-stack web interface with an interactive Excalidraw diagram viewer, risk tables, and component maps. See Two Deployment Options for a comparison with Option B.
.\scripts\windows\dev.ps1This starts the FastAPI backend on port 8000 and the Vite dev server on port 5173. Open http://localhost:5173 in your browser.
# Terminal 1 - Backend
python -m uvicorn api:app --reload --port 8000
# Terminal 2 - Frontend
cd frontend
npm install # first time only
npx vite --port 5173docker build -f Dockerfile.web -t arch-review-web .
docker run -p 8000:8000 --env-file .env arch-review-webOpen http://localhost:8000 - the container serves both the API and the React UI.
Automated deployment scripts handle resource provisioning, container build, and configuration:
PowerShell:
.\scripts\windows\deploy-webapp.ps1 -ResourceGroup arch-review-rg -AppName arch-review-webBash:
bash scripts/linux-mac/deploy-webapp.sh --resource-group arch-review-rg --app-name arch-review-webThe scripts create an Azure Container Registry, build the image via ACR Tasks,
provision an App Service Plan + Web App with managed identity, and configure
app settings from your .env file.
To tear down all resources:
PowerShell:
.\scripts\windows\teardown.ps1 -ResourceGroup arch-review-rgBash:
bash scripts/linux-mac/teardown.sh --resource-group arch-review-rg| Method | Path | Description |
|---|---|---|
POST |
/api/review |
Submit architecture text for full review |
POST |
/api/review/upload |
Upload a YAML/MD/TXT file |
POST |
/api/infer |
Force LLM inference on free-form text |
GET |
/api/download/png/{run_id} |
Download PNG diagram |
GET |
/api/download/excalidraw/{run_id} |
Download Excalidraw JSON |
GET |
/api/health |
Health check |
The hosted agent starts an OpenAI Responses-compatible API server. Locally it runs on port 8088; when deployed to Microsoft Foundry, the platform manages the endpoint, scaling, identity, and conversation state. See Two Deployment Options for a comparison with Option A.
python main.py
# → Architecture Review Agent Server running on http://localhost:8088Test with a curl / PowerShell request:
Invoke-RestMethod -Uri "http://localhost:8088/responses" `
-Method POST -ContentType "application/json" `
-Body '{"input":{"messages":[{"role":"user","content":"Review: LB -> API -> DB"}]}}'docker build -t arch-review .
docker run -p 8088:8088 --env-file .env arch-reviewThe VS Code Foundry extension provides the most stable and straightforward deployment workflow:
- Install the Microsoft Foundry for VS Code extension
- Open the Command Palette (
Ctrl+Shift+P) and runMicrosoft Foundry: Deploy Hosted Agent - Select your Foundry workspace and follow the prompts
- The extension handles ACR build, container deployment, and managed identity assignment automatically
See deployment.md for the complete step-by-step guide with screenshots and RBAC configuration.
Once deployed as a hosted agent, the platform manages:
| Capability | Details |
|---|---|
| Container hosting | Built via ACR Tasks, deployed to Foundry-managed compute |
| Auto-scaling | 0 → 5 replicas with scale-to-zero support |
| Managed identity | System-assigned identity with RBAC - no API keys in the container |
| Conversation persistence | The Foundry Agent Service stores and manages conversation state |
| Channel publishing | Publish to Microsoft Teams, M365 Copilot, Web App preview, or a stable API endpoint |
| Observability | Built-in OpenTelemetry tracing integrated with Azure Monitor |
| API compliance | Automatic OpenAI Responses API endpoint |
Foundry Playground (VS Code): Open the Foundry extension → Hosted Agents (Preview) → Architecture Review Agent → Playground tab.
REST API:
$endpoint = "https://<your-resource>.services.ai.azure.com/api/projects/<your-project>"
$token = (az account get-access-token --resource "https://cognitiveservices.azure.com" --query accessToken -o tsv)
Invoke-RestMethod `
-Uri "$endpoint/openai/responses?api-version=2025-05-15-preview" `
-Method POST `
-Headers @{ "Authorization" = "Bearer $token"; "Content-Type" = "application/json" } `
-Body (@{ input = @{ messages = @(@{ role = "user"; content = "Review: LB -> API -> Cache -> DB" }) } } | ConvertTo-Json -Depth 5)Important
For the full deployment guide including RBAC setup, VS Code Foundry Extension workflow, and troubleshooting, see deployment.md.
For official Microsoft documentation, see Hosted Agents documentation.
This sample requires a deployed model (GPT-4.1 recommended) on Azure OpenAI or Microsoft Foundry.
- Go to Microsoft Foundry and create or open a project.
- Navigate to Models + endpoints → Deploy model → Deploy base model.
- Select gpt-4.1 (or your preferred model) and click Deploy.
- Copy the Project endpoint (e.g.,
https://<project>.services.ai.azure.com). - Note the Deployment name (e.g.,
gpt-4.1). - Set the environment variables:
PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com
MODEL_DEPLOYMENT_NAME=gpt-4.1- In the Azure Portal, create an Azure OpenAI resource.
- Go to Microsoft Foundry → select the resource → Deployments → Create deployment.
- Choose gpt-4.1, set the deployment name, and deploy.
- Copy the Endpoint (e.g.,
https://<resource>.openai.azure.com/). - Set the environment variables:
AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4.1The Architecture Review Agent supports two authentication methods:
- API Key (simplest) - Set
AZURE_OPENAI_API_KEYin.env. Used automatically when present. - DefaultAzureCredential (fallback) - Supports Azure CLI (
az login), Managed Identity, and service principal env vars (AZURE_CLIENT_ID/AZURE_TENANT_ID/AZURE_CLIENT_SECRET).
For local development with API key:
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-key-hereOr with Azure CLI:
az login
az account set --subscription <your-subscription-id>The Architecture Review Agent accepts any input - structured or unstructured. Component names, types, and architectures are fully dynamic.
flowchart LR
A["ANY INPUT<br/>(YAML, MD, README,<br/>code, prose, etc.)"] --> B{Smart Parser}
B -- "Structured" --> C["Rule-based<br/>(fast)"]
B -- "Unstructured" --> D["LLM Inference<br/>(auto-fallback)"]
C --> E["Structured Architecture<br/>(components + connections)"]
D --> E
E --> F[Risk Analysis]
F --> G[Diagram Generation]
G --> H[Report]
- Structured formats (YAML with
components/connections, Markdown with## Componentsheaders, plaintext arrows) → fast rule-based parser. - Unstructured inputs (any other file, prose, code, config) → when rule-based parsing yields ≤1 component, the LLM automatically analyses the content, infers components/types/connections, and proceeds.
- Force LLM → use
--inferflag to always use LLM inference, even on structured inputs.
name: My Architecture
components:
- name: API Gateway
type: gateway
technology: Kong
replicas: 2
- name: User Service
type: service
replicas: 3
- name: User Database
type: database
technology: PostgreSQL
connections:
- from: api_gateway
to: user_service
protocol: REST
- from: user_service
to: user_database
protocol: TCPAccepted keys: components/services/nodes and connections/edges/flows/links.
## Components
### API Gateway
- **Type:** gateway
- **Technology:** Kong
- **Replicas:** 2
### User Service
- Handles user authentication and profiles
## Connections
- API Gateway -> User Service (REST)
- User Service -> User Database (TCP)API Gateway -> User Service -> User Database
API Gateway -> Product Service -> Product DB
Product Service -> Redis Cache
Chained arrows (A -> B -> C) are auto-expanded into individual connections.
Feed it a README, design document, code file, Terraform config, meeting notes - the LLM analyses it:
Our platform uses React for the frontend, served through CloudFront CDN.
All API calls go through a Kong API Gateway which routes to three microservices:
User Service, Order Service, and Inventory Service. Each service has its own
PostgreSQL database. Order Service publishes events to a Kafka topic that
Inventory Service consumes. We use Redis for session caching and Datadog
for monitoring.
The model will infer:
- 10 components - React Frontend, CloudFront CDN, Kong API Gateway, User Service, Order Service, Inventory Service, 3× PostgreSQL DBs, Kafka, Redis, Datadog
- Component types - frontend, cache, gateway, service, database, queue, monitoring
- ~12 connections - Frontend→CDN→Gateway→Services→DBs, Order→Kafka→Inventory, etc.
Then proceeds with full risk analysis, diagram generation, and report.
| Tool | Description |
|---|---|
review_architecture |
One-call pipeline - smart-parse (with automatic LLM fallback) → risk analysis → diagram + Excalidraw MCP render + PNG export → component map → structured report with executive summary and prioritised recommendations |
infer_architecture |
LLM inference only - extract components, types, and connections from any unstructured text (README, code, design doc, prose) without running the full review pipeline |
The Architecture Review Agent uses two risk engines depending on the parsing path:
Fast pattern-matching across four categories:
| Category | What it detects |
|---|---|
| SPOF | Components with 1 replica and ≥2 dependants, or infrastructure types (gateway, database, cache, queue) with no redundancy |
| Scalability | Shared resources (cache, database, queue) used by ≥3 services - contention risk |
| Security | Frontend-to-database direct access, missing API gateway, external dependencies without circuit-breakers |
| Anti-patterns | Shared database pattern - multiple services writing to the same datastore |
When the LLM infers the architecture (auto-fallback or --infer), it also produces context-aware risks with concise 1-liner issues and actionable recommendations - covering SPOFs, redundancy gaps, security concerns, observability, compliance (e.g. PCI DSS), and architecture-specific bottlenecks.
Risks are severity-bucketed: critical → high → medium → low.
When types aren't explicitly set, the Architecture Review Agent infers them from component names:
| Type | Keywords | Diagram Colour |
|---|---|---|
| database | database, db, mysql, postgres, mongodb, cosmos... | Yellow |
| cache | cache, redis, memcached, cdn | Orange |
| queue | queue, kafka, rabbitmq, sqs, event hub, pubsub... | Purple |
| gateway | gateway, load balancer, nginx, envoy, ingress | Violet |
| frontend | frontend, ui, spa, react, angular, vue, web app | Blue |
| storage | storage, s3, blob, bucket, file | Green |
| external | external, third-party, stripe, twilio | Red |
| monitoring | monitor, logging, prometheus, grafana, datadog | Grey |
| service | (default for anything else) | Green |
- Microsoft Agent Framework (
azure-ai-agentserver-agentframework) - Hosted agent runtime - Excalidraw MCP Server - Interactive diagram rendering via MCP protocol
- Azure OpenAI - LLM backend (GPT-4.1 recommended) via
AzureOpenAIChatClient(API key orDefaultAzureCredential) - Pillow - PNG diagram export
- PyYAML - YAML parsing
- Rich - CLI output formatting
![]() Shivam Goyal |

