# az-scout/az-scout architecture

> Architecture diagram of the GitHub repository az-scout/az-scout, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/az-scout/az-scout
- Repository: https://github.com/az-scout/az-scout
- Video tour (about a minute): https://gitdiagram.com/az-scout/az-scout/video

## Overview

Azure Scout helps Azure operators inspect VM availability, zone mappings, pricing, Spot scores, and quota, then assess deployment confidence through a web UI, MCP tools, or terminal chat. The web/API and agent interfaces call shared Azure data services; SKU enrichment can incorporate quota, pricing, Spot, and confidence signals. Planner and topology plugins expose additional planning and mapping capabilities. Plugin discovery and management extend the application. Several subsystem paths are included from the source index and tree without claiming their unsampled internals were inspected; uncertain links are omitted.

Main entry points: [`src/az_scout/azure_api/__init__.py`](https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/__init__.py) (Azure API facade), [`src/az_scout/app.py`](https://github.com/az-scout/az-scout/blob/main/src/az_scout/app.py) (Web application), [`src/az_scout/plugin_manager/_operations.py`](https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugin_manager/_operations.py) (Plugin management), [`src/az_scout/internal_plugins/planner/routes.py`](https://github.com/az-scout/az-scout/blob/main/src/az_scout/internal_plugins/planner/routes.py) (Deployment planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web_app["Web application<br/>[app.py]"]
  node_web_routes["Discovery routes<br/>[discovery.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_terminal_chat["Terminal chat<br/>[cli_chat.py]"]
end

subgraph group_azure["Azure data and scoring"]
  node_azure_facade["Azure API facade<br/>[__init__.py]"]
  node_discovery["Tenant discovery<br/>[discovery.py]"]
  node_arm["ARM requests<br/>[_arm.py]"]
  node_sku_data["SKU availability<br/>[skus.py]"]
  node_pricing["VM pricing<br/>[pricing.py]"]
  node_quota["Quota data<br/>[quotas.py]"]
  node_spot["Spot scores<br/>[spot.py]"]
  node_confidence["Deployment scoring"]
  node_responses["API response models<br/>[responses.py]"]
end

subgraph group_assistant["AI and planning"]
  node_chat_service["AI chat service<br/>[_stream.py]"]
  node_chat_tools["Chat tools<br/>[_tools.py]"]
  node_planner["Deployment planner<br/>[routes.py]"]
  node_planner_tools["Planner tools<br/>[tools.py]"]
  node_topology["Zone mapping plugin<br/>[routes.py]"]
end

subgraph group_extensions["Authentication and plugins"]
  node_auth["Authentication<br/>[auth.py]"]
  node_oauth_routes["OAuth routes<br/>[auth.py]"]
  node_plugin_runtime["Plugin runtime<br/>[plugins.py]"]
  node_plugin_api["Plugin API<br/>[plugin_api.py]"]
  node_plugin_ops["Plugin management<br/>[_operations.py]"]
  node_plugin_installer["Plugin installer<br/>[_installer.py]"]
  node_plugin_store[("Plugin storage<br/>[_storage.py]")]
end

node_operator(("Azure operator"))
node_azure_service["Microsoft Azure"]
node_plugin_catalog["Plugin catalog"]

node_operator -->|"uses web UI"| node_web_app
node_operator -->|"queries tools"| node_mcp
node_operator -->|"asks questions"| node_terminal_chat
node_web_app -->|"registers routes"| node_web_routes
node_web_routes -->|"queries Azure data"| node_azure_facade
node_mcp -->|"calls data helpers"| node_azure_facade
node_terminal_chat -->|"discovers tenants"| node_azure_facade
node_terminal_chat -->|"streams chat"| node_chat_service
node_azure_facade -->|"exports discovery"| node_discovery
node_azure_facade -->|"exports pricing"| node_pricing
node_azure_facade -->|"exports SKU data"| node_sku_data
node_azure_facade -->|"exports quota data"| node_quota
node_azure_facade -->|"exports Spot scores"| node_spot
node_azure_facade -->|"enriches confidence"| node_confidence
node_discovery -->|"uses ARM helpers"| node_arm
node_azure_facade -->|"queries Azure"| node_azure_service
node_web_routes -->|"returns models"| node_responses
node_planner -->|"gets Azure data"| node_azure_facade
node_planner -->|"computes confidence"| node_confidence
node_planner -->|"uses response models"| node_responses
node_planner_tools -->|"uses Azure helpers"| node_azure_facade
node_planner_tools -->|"scores deployments"| node_confidence
node_topology -->|"queries mappings"| node_azure_facade
node_topology -->|"uses response models"| node_responses
node_chat_service -->|"dispatches tools"| node_chat_tools
node_chat_tools -->|"reuses tool definitions"| node_mcp
node_web_app -->|"protects requests"| node_auth
node_auth -->|"reads session token"| node_oauth_routes
node_web_app -->|"loads plugins"| node_plugin_runtime
node_plugin_runtime -->|"registers contributions"| node_plugin_api
node_operator -->|"manages plugins"| node_plugin_ops
node_plugin_ops -->|"runs install actions"| node_plugin_installer
node_plugin_ops -->|"reads plugin records"| node_plugin_store
node_plugin_installer -->|"uses package paths"| node_plugin_store
node_plugin_ops -->|"browses catalog"| node_plugin_catalog

click node_web_app "https://github.com/az-scout/az-scout/blob/main/src/az_scout/app.py"
click node_web_routes "https://github.com/az-scout/az-scout/blob/main/src/az_scout/routes/discovery.py"
click node_mcp "https://github.com/az-scout/az-scout/blob/main/src/az_scout/mcp_server.py"
click node_terminal_chat "https://github.com/az-scout/az-scout/blob/main/src/az_scout/services/cli_chat.py"
click node_azure_facade "https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/__init__.py"
click node_discovery "https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/discovery.py"
click node_arm "https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/_arm.py"
click node_sku_data "https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/skus.py"
click node_pricing "https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/pricing.py"
click node_quota "https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/quotas.py"
click node_spot "https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/spot.py"
click node_confidence "https://github.com/az-scout/az-scout/blob/main/src/az_scout/scoring/deployment_confidence.py"
click node_responses "https://github.com/az-scout/az-scout/blob/main/src/az_scout/models/responses.py"
click node_chat_service "https://github.com/az-scout/az-scout/blob/main/src/az_scout/services/ai_chat/_stream.py"
click node_chat_tools "https://github.com/az-scout/az-scout/blob/main/src/az_scout/services/ai_chat/_tools.py"
click node_planner "https://github.com/az-scout/az-scout/blob/main/src/az_scout/internal_plugins/planner/routes.py"
click node_planner_tools "https://github.com/az-scout/az-scout/blob/main/src/az_scout/internal_plugins/planner/tools.py"
click node_topology "https://github.com/az-scout/az-scout/blob/main/src/az_scout/internal_plugins/topology/routes.py"
click node_auth "https://github.com/az-scout/az-scout/blob/main/src/az_scout/auth.py"
click node_oauth_routes "https://github.com/az-scout/az-scout/blob/main/src/az_scout/routes/auth.py"
click node_plugin_runtime "https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugins.py"
click node_plugin_api "https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugin_api.py"
click node_plugin_ops "https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugin_manager/_operations.py"
click node_plugin_installer "https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugin_manager/_installer.py"
click node_plugin_store "https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugin_manager/_storage.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_app,node_web_routes,node_mcp,node_terminal_chat toneBlue
class node_azure_facade,node_discovery,node_arm,node_sku_data,node_pricing,node_quota,node_spot,node_confidence,node_responses toneAmber
class node_chat_service,node_chat_tools,node_planner,node_planner_tools,node_topology toneMint
class node_auth,node_oauth_routes,node_plugin_runtime,node_plugin_api,node_plugin_ops,node_plugin_installer,node_plugin_store toneRose
class node_operator,node_azure_service,node_plugin_catalog toneIndigo
```

## Components

### User interfaces

- [Web application](https://github.com/az-scout/az-scout/blob/main/src/az_scout/app.py): `src/az_scout/app.py`
- [Discovery routes](https://github.com/az-scout/az-scout/blob/main/src/az_scout/routes/discovery.py): `src/az_scout/routes/discovery.py`
- [MCP server](https://github.com/az-scout/az-scout/blob/main/src/az_scout/mcp_server.py): `src/az_scout/mcp_server.py`
- [Terminal chat](https://github.com/az-scout/az-scout/blob/main/src/az_scout/services/cli_chat.py): `src/az_scout/services/cli_chat.py`

### Azure data and scoring

- [Azure API facade](https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/__init__.py): `src/az_scout/azure_api/__init__.py`
- [Tenant discovery](https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/discovery.py): `src/az_scout/azure_api/discovery.py`
- [ARM requests](https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/_arm.py): `src/az_scout/azure_api/_arm.py`
- [SKU availability](https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/skus.py): `src/az_scout/azure_api/skus.py`
- [VM pricing](https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/pricing.py): `src/az_scout/azure_api/pricing.py`
- [Quota data](https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/quotas.py): `src/az_scout/azure_api/quotas.py`
- [Spot scores](https://github.com/az-scout/az-scout/blob/main/src/az_scout/azure_api/spot.py): `src/az_scout/azure_api/spot.py`
- [Deployment scoring](https://github.com/az-scout/az-scout/blob/main/src/az_scout/scoring/deployment_confidence.py): `src/az_scout/scoring/deployment_confidence.py`
- [API response models](https://github.com/az-scout/az-scout/blob/main/src/az_scout/models/responses.py): `src/az_scout/models/responses.py`

### AI and planning

- [AI chat service](https://github.com/az-scout/az-scout/blob/main/src/az_scout/services/ai_chat/_stream.py): `src/az_scout/services/ai_chat/_stream.py`
- [Chat tools](https://github.com/az-scout/az-scout/blob/main/src/az_scout/services/ai_chat/_tools.py): `src/az_scout/services/ai_chat/_tools.py`
- [Deployment planner](https://github.com/az-scout/az-scout/blob/main/src/az_scout/internal_plugins/planner/routes.py): `src/az_scout/internal_plugins/planner/routes.py`
- [Planner tools](https://github.com/az-scout/az-scout/blob/main/src/az_scout/internal_plugins/planner/tools.py): `src/az_scout/internal_plugins/planner/tools.py`
- [Zone mapping plugin](https://github.com/az-scout/az-scout/blob/main/src/az_scout/internal_plugins/topology/routes.py): `src/az_scout/internal_plugins/topology/routes.py`

### Authentication and plugins

- [Authentication](https://github.com/az-scout/az-scout/blob/main/src/az_scout/auth.py): `src/az_scout/auth.py`
- [OAuth routes](https://github.com/az-scout/az-scout/blob/main/src/az_scout/routes/auth.py): `src/az_scout/routes/auth.py`
- [Plugin runtime](https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugins.py): `src/az_scout/plugins.py`
- [Plugin API](https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugin_api.py): `src/az_scout/plugin_api.py`
- [Plugin management](https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugin_manager/_operations.py): `src/az_scout/plugin_manager/_operations.py`
- [Plugin installer](https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugin_manager/_installer.py): `src/az_scout/plugin_manager/_installer.py`
- [Plugin storage](https://github.com/az-scout/az-scout/blob/main/src/az_scout/plugin_manager/_storage.py): `src/az_scout/plugin_manager/_storage.py`

### Other components

- **Azure operator**
- **Microsoft Azure**
- **Plugin catalog**

## Connections

- Azure operator → Web application: uses web UI (evidence: `README.md`)
- Azure operator → MCP server: queries tools (evidence: `README.md`)
- Azure operator → Terminal chat: asks questions (evidence: `README.md`)
- Web application → Discovery routes: registers routes (evidence: `src/az_scout/app.py`)
- Discovery routes → Azure API facade: queries Azure data (evidence: `src/az_scout/routes/discovery.py`)
- MCP server → Azure API facade: calls data helpers (evidence: `src/az_scout/mcp_server.py`)
- Terminal chat → Azure API facade: discovers tenants (evidence: `src/az_scout/services/cli_chat.py`)
- Terminal chat → AI chat service: streams chat (evidence: `src/az_scout/services/cli_chat.py`)
- Azure API facade → Tenant discovery: exports discovery (evidence: `src/az_scout/azure_api/__init__.py`)
- Azure API facade → VM pricing: exports pricing (evidence: `src/az_scout/azure_api/__init__.py`)
- Azure API facade → SKU availability: exports SKU data (evidence: `src/az_scout/azure_api/__init__.py`)
- Azure API facade → Quota data: exports quota data (evidence: `src/az_scout/azure_api/__init__.py`)
- Azure API facade → Spot scores: exports Spot scores (evidence: `src/az_scout/azure_api/__init__.py`)
- Azure API facade → Deployment scoring: enriches confidence (evidence: `src/az_scout/azure_api/__init__.py`)
- Tenant discovery → ARM requests: uses ARM helpers (evidence: `src/az_scout/azure_api/discovery.py`)
- Azure API facade → Microsoft Azure: queries Azure (evidence: `README.md`)
- Discovery routes → API response models: returns models (evidence: `src/az_scout/routes/discovery.py`)
- Deployment planner → Azure API facade: gets Azure data (evidence: `src/az_scout/internal_plugins/planner/routes.py`)
- Deployment planner → Deployment scoring: computes confidence (evidence: `src/az_scout/internal_plugins/planner/routes.py`)
- Deployment planner → API response models: uses response models (evidence: `src/az_scout/internal_plugins/planner/routes.py`)
- Planner tools → Azure API facade: uses Azure helpers (evidence: `src/az_scout/internal_plugins/planner/tools.py`)
- Planner tools → Deployment scoring: scores deployments (evidence: `src/az_scout/internal_plugins/planner/tools.py`)
- Zone mapping plugin → Azure API facade: queries mappings (evidence: `src/az_scout/internal_plugins/topology/routes.py`)
- Zone mapping plugin → API response models: uses response models (evidence: `src/az_scout/internal_plugins/topology/routes.py`)
- AI chat service → Chat tools: dispatches tools (evidence: `src/az_scout/services/ai_chat/_stream.py`)
- Chat tools → MCP server: reuses tool definitions (evidence: `src/az_scout/services/ai_chat/_tools.py`)
- Web application → Authentication: protects requests (evidence: `src/az_scout/app.py`)
- Authentication → OAuth routes: reads session token (evidence: `src/az_scout/auth.py`)
- Web application → Plugin runtime: loads plugins (evidence: `src/az_scout/app.py`)
- Plugin runtime → Plugin API: registers contributions (evidence: `src/az_scout/plugins.py`)
- Azure operator → Plugin management: manages plugins (evidence: `README.md`)
- Plugin management → Plugin installer: runs install actions (evidence: `src/az_scout/plugin_manager/_operations.py`)
- Plugin management → Plugin storage: reads plugin records (evidence: `src/az_scout/plugin_manager/_operations.py`)
- Plugin installer → Plugin storage: uses package paths (evidence: `src/az_scout/plugin_manager/_installer.py`)
- Plugin management → Plugin catalog: browses catalog
