---
name: "azure-solution-architect"
description: Design Azure architectures for startups using serverless patterns and infrastructure-as-code templates. Use when asked to design serverless architecture, create Bicep/ARM templates, optimize Azure costs, set up CI/CD pipelines, or migrate to Azure. Covers Azure Functions, API Management, Cosmos DB, Container Apps, Azure Database for PostgreSQL, and cost optimization.
---

# Azure Solution Architect

Design scalable, cost-effective Microsoft Azure architectures for startups with infrastructure-as-code templates.

---

## Workflow

### Step 1: Gather Requirements

Collect application specifications:

```
- Application type (web app, mobile backend, data pipeline, SaaS)
- Expected users and requests per second
- Budget constraints (monthly spend limit)
- Team size and Azure experience level
- Compliance requirements (GDPR, HIPAA, ISO 27001)
- Availability requirements (SLA, RPO/RTO)
```

### Step 2: Design Architecture

Run the architecture designer to get pattern recommendations:

```bash
python scripts/architecture_designer.py --input requirements.json
```

**Example output:**

```json
{
  "recommended_pattern": "serverless_web",
  "service_stack": ["Blob Storage", "Front Door", "API Management", "Azure Functions", "Cosmos DB", "Entra External ID"],
  "estimated_monthly_cost_usd": 35,
  "pros": ["Low ops overhead", "Pay-per-use", "Auto-scaling"],
  "cons": ["Cold starts", "Consumption plan limits", "Eventual consistency"]
}
```

Select from recommended patterns:
- **Serverless Web**: Blob Storage + Front Door + API Management + Azure Functions + Cosmos DB + Entra External ID
- **Event-Driven Microservices**: Event Grid + Azure Functions + Service Bus + Durable Functions
- **Three-Tier**: Application Gateway + Container Apps + Azure Database for PostgreSQL + Azure Cache for Redis
- **GraphQL Backend**: API Management (GraphQL) + Azure Functions + Cosmos DB + Entra External ID

See `references/architecture_patterns.md` for detailed pattern specifications.

**Validation checkpoint:** Confirm the recommended pattern matches the team's operational maturity and compliance requirements before proceeding to Step 3.

### Step 3: Generate IaC Templates

Create infrastructure-as-code for the selected pattern:

```bash
# Serverless stack (Bicep)
python scripts/serverless_stack.py --app-name my-app --location eastus
```

**Example Bicep output (core serverless resources):**

```bicep
@description('Base name for the application resources')
param appName string = 'my-app'

@description('Azure region for all resources')
param location string = resourceGroup().location

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: '${appName}sa'
  location: location
  sku: { name: 'Standard_LRS' }
  kind: 'StorageV2'
}

resource functionPlan 'Microsoft.Web/serverfarms@2023-01-01' = {
  name: '${appName}-plan'
  location: location
  sku: { name: 'Y1', tier: 'Dynamic' } // Consumption plan
}

resource functionApp 'Microsoft.Web/sites@2023-01-01' = {
  name: '${appName}-fn'
  location: location
  kind: 'functionapp'
  properties: {
    serverFarmId: functionPlan.id
    siteConfig: {
      appSettings: [
        { name: 'COSMOS_DB', value: cosmosAccount.properties.documentEndpoint }
      ]
    }
  }
}

resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = {
  name: '${appName}-cosmos'
  location: location
  kind: 'GlobalDocumentDB'
  properties: {
    databaseAccountOfferType: 'Standard'
    capabilities: [ { name: 'EnableServerless' } ]
    locations: [ { locationName: location, failoverPriority: 0 } ]
  }
}
```

> Full templates including API Management, Entra External ID, managed identities, and Azure Monitor diagnostics are generated by `serverless_stack.py` and also available in `references/architecture_patterns.md`.

**Example Terraform (azurerm) snippet (three-tier pattern):**

```hcl
resource "azurerm_container_app_environment" "app" {
  name                = "app-env"
  location            = azurerm_resource_group.main.location
  resource_group_name = azurerm_resource_group.main.name
}

resource "azurerm_postgresql_flexible_server" "app" {
  name                   = "app-db"
  resource_group_name    = azurerm_resource_group.main.name
  location               = azurerm_resource_group.main.location
  sku_name               = "GP_Standard_D2s_v3"
  storage_mb             = 32768
  version                = "15"
  zone                   = "1"
}
```

### Step 4: Review Costs

Analyze estimated costs and optimization opportunities:

```bash
python scripts/cost_optimizer.py --resources current_setup.json --monthly-spend 2000
```

**Example output:**

```json
{
  "current_monthly_usd": 2000,
  "recommendations": [
    { "action": "Right-size PostgreSQL GP_D4s_v3 → GP_D2s_v3", "savings_usd": 420, "priority": "high" },
    { "action": "Purchase 1-yr Azure Savings Plan for compute at 40% utilization", "savings_usd": 310, "priority": "high" },
    { "action": "Move Blob objects >90 days to Cool/Archive tier", "savings_usd": 85, "priority": "medium" }
  ],
  "total_potential_savings_usd": 815
}
```

Output includes:
- Monthly cost breakdown by service
- Right-sizing recommendations
- Reservations / Savings Plans opportunities
- Potential monthly savings

### Step 5: Deploy

Deploy the generated infrastructure:

```bash
# Bicep / ARM
az deployment group create \
  --resource-group my-app-rg \
  --template-file main.bicep \
  --parameters appName=my-app

# Terraform
terraform init && terraform apply
```

### Step 6: Validate and Handle Failures

Verify deployment and set up monitoring:

```bash
# Check deployment status
az deployment group show --resource-group my-app-rg --name main

# Set up Azure Monitor metric alert
az monitor metrics alert create --name high-errors ...
```

**If deployment fails:**

1. Check the failure reason:
   ```bash
   az deployment operation group list \
     --resource-group my-app-rg \
     --name main \
     --query "[?properties.provisioningState=='Failed']"
   ```
2. Review Azure Monitor / Application Insights logs for Function or Container App errors.
3. Fix the template or resource configuration.
4. Because ARM/Bicep deployments are incremental and idempotent, re-run the deployment after fixing; delete partially created resources only when a resource is in an unrecoverable state:
   ```bash
   # Inspect, then (if required) remove a failed resource group
   az group delete --name my-app-rg --yes
   # Redeploy
   az deployment group create --resource-group my-app-rg --template-file main.bicep ...
   ```

**Common failure causes:**
- Authorization errors → verify the managed identity / service principal has the right RBAC role assignments
- Resource limit / quota exceeded → request a quota increase via the Azure portal (Subscriptions → Usage + quotas)
- Invalid template syntax → run `az bicep build --file main.bicep` (or `az deployment group validate`) before deploying

---

## Tools

### architecture_designer.py

Generates architecture patterns based on requirements.

```bash
python scripts/architecture_designer.py --input requirements.json --output design.json
```

**Input:** JSON with app type, scale, budget, compliance needs
**Output:** Recommended pattern, service stack, cost estimate, pros/cons

### serverless_stack.py

Creates serverless Bicep templates.

```bash
python scripts/serverless_stack.py --app-name my-app --location eastus
```

**Output:** Production-ready Bicep with:
- API Management + Azure Functions
- Cosmos DB account (serverless)
- Entra External ID tenant reference
- Managed identities with least privilege
- Azure Monitor / Application Insights diagnostics

### cost_optimizer.py

Analyzes costs and recommends optimizations.

```bash
python scripts/cost_optimizer.py --resources inventory.json --monthly-spend 5000
```

**Output:** Recommendations for:
- Idle resource removal
- Instance / SKU right-sizing
- Reservations and Savings Plans purchases
- Storage tier transitions (Hot/Cool/Archive)
- NAT Gateway / Private Endpoint alternatives

---

## Quick Start

### MVP Architecture (< $100/month)

```
Ask: "Design a serverless MVP backend for a mobile app with 1000 users"

Result:
- Azure Functions + API Management for API
- Cosmos DB serverless for data
- Entra External ID for authentication
- Blob Storage + Front Door for static assets
- Estimated: $20-50/month
```

### Scaling Architecture ($500-2000/month)

```
Ask: "Design a scalable architecture for a SaaS platform with 50k users"

Result:
- Container Apps for containerized API
- Azure Database for PostgreSQL Flexible Server
- Azure Cache for Redis for session caching
- Front Door for CDN
- Azure DevOps / GitHub Actions for CI/CD
- Availability zones deployment
```

### Cost Optimization

```
Ask: "Optimize my Azure setup to reduce costs by 30%. Current spend: $3000/month"

Provide: Current resource inventory (VMs, databases, storage, etc.)

Result:
- Idle resource identification
- Right-sizing recommendations
- Reservations / Savings Plans analysis
- Storage lifecycle policies
- Target savings: $900/month
```

### IaC Generation

```
Ask: "Generate Bicep for a three-tier web app with auto-scaling"

Result:
- Virtual network with public/private subnets
- Application Gateway with HTTPS
- Container Apps with auto-scaling
- Azure Database for PostgreSQL with read replicas
- Network security groups and managed identities
```

---

## Input Requirements

Provide these details for architecture design:

| Requirement | Description | Example |
|-------------|-------------|---------|
| Application type | What you're building | SaaS platform, mobile backend |
| Expected scale | Users, requests/sec | 10k users, 100 RPS |
| Budget | Monthly Azure limit | $500/month max |
| Team context | Size, Azure experience | 3 devs, intermediate |
| Compliance | Regulatory needs | HIPAA, GDPR, ISO 27001 |
| Availability | Uptime requirements | 99.9% SLA, 1hr RPO |

**JSON Format:**

```json
{
  "application_type": "saas_platform",
  "expected_users": 10000,
  "requests_per_second": 100,
  "budget_monthly_usd": 500,
  "team_size": 3,
  "azure_experience": "intermediate",
  "compliance": ["ISO27001"],
  "availability_sla": "99.9%"
}
```

---

## Output Formats

### Architecture Design

- Pattern recommendation with rationale
- Service stack diagram (ASCII)
- Monthly cost estimate and trade-offs

### IaC Templates

- **Bicep**: Production-ready Bicep modules
- **ARM JSON**: Portable Azure Resource Manager templates
- **Terraform HCL**: `azurerm` provider configurations

### Cost Analysis

- Current spend breakdown with optimization recommendations
- Priority action list (high/medium/low) and implementation checklist

---

## C4 Diagrams — Azure service tagging and theming (mandatory)

When Azure services appear in the project's C4 model (Structurizr DSL) — including the deployment elements `deploymentNode` and `infrastructureNode` — each Azure service element MUST carry a **dedicated tag** (PascalCase, e.g. `AzureDevOps` for *Azure DevOps*) and a matching **themed style** in `theme/0001-project-styles.dsl` that uses the **official Structurizr Microsoft Azure theme icon** and Azure colours:

```dsl
element AzureDevOps {
    icon https://static.structurizr.com/themes/microsoft-azure-2024.07.15/azure-devops.png
    stroke #509aeb
    color #509aeb
}
```

- Icon base URL: `https://static.structurizr.com/themes/microsoft-azure-2024.07.15/<service>.png` (official theme — <https://github.com/structurizr/themes>). Use the real icon file name; never invent one.
- Never leave an Azure service without its `element <Tag>` style — add it if missing.

**Single source of truth** (full rule, examples, validation): [`project-defaults/references/structurizr.md`](../project-defaults/references/structurizr.md), section « Services cloud Azure : tag dédié + style thématisé ». This skill does not duplicate it.

---

## Reference Documentation

| Document | Contents |
|----------|----------|
| `references/architecture_patterns.md` | 6 patterns: serverless, microservices, three-tier, data processing, GraphQL, multi-region |
| `references/service_selection.md` | Decision matrices for compute, database, storage, messaging |
| `references/best_practices.md` | Serverless design, cost optimization, security hardening, scalability |