1# Composition Algorithm — REFERENCE ONLY
2 
3Step-by-step algorithm for composing a base App Service template with an integration recipe.
4 
5> **This is the authoritative process. Follow it exactly.**
6 
7## Algorithm
8 
9```
10INPUT:
11  - language:    dotnet | typescript | javascript | python | java
12  - scenario:    web-api | web-app
13  - integration: none | sql | cosmos | auth | redis
14  - iac:         bicep | terraform
15 
16OUTPUT:
17  - Complete project directory ready for `azd up`
18```
19 
20### Step 1: Fetch Base Template
21 
22```bash
23# Determine template by scenario + language
24IF scenario == 'web-api':
25  TEMPLATE = web_api_templates[language]    # See web-api.md
26ELSE IF scenario == 'web-app':
27  TEMPLATE = web_app_templates[language]    # See web-app.md
28 
29# Non-interactive init
30ENV_NAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | tr ' _' '-')-dev"
31# PowerShell: $ENV_NAME = "$(Split-Path -Leaf (Get-Location) | ForEach-Object { $_.ToLower() -replace '[ _]','-' })-dev"
32azd init -t $TEMPLATE -e "$ENV_NAME" --no-prompt
33```
34 
35### Step 2: Check if Recipe Needed
36 
37```
38IF integration IN [none]:
39  → DONE. Base template is complete.
40 
41IF integration IN [sql, cosmos, redis, auth]:
42  → Full recipe. Continue to Step 3.
43```
44 
45### Step 3: Add IaC Module (for full recipes only)
46 
47**Bicep:**
481. Read recipe's `README.md` for the Bicep module file
492. Copy module into `infra/app/`
503. Add module reference in `infra/main.bicep`:
51   ```bicep
52   module sqlServer './app/sql.bicep' = {
53     name: 'sqlServer'
54     scope: rg
55     params: {
56       name: name
57       location: location
58       tags: tags
59       appServicePrincipalId: web.outputs.SERVICE_WEB_IDENTITY_PRINCIPAL_ID
60     }
61   }
62   ```
634. If VNET_ENABLED, add the network module for private endpoints
64 
65**Terraform:**
661. Copy recipe `.tf` files into `infra/`
672. Merge app settings into web app resource block
683. Networking uses `count = var.vnet_enabled ? 1 : 0`
69 
70### Step 4: Add App Settings
71 
72Read the recipe's `README.md` for required app settings. Add them to the web app config.
73 
74> **CRITICAL: Managed Identity Configuration**
75>
76> For service bindings, prefer User Assigned Managed Identity (UAMI).
77> Always include connection settings that reference managed identity, not passwords:
78>
79> ⚠️ **Connection-string format is language-specific.** The example below is **.NET / ADO.NET** format. For other stacks, use the per-language env vars documented in `recipes/sql/source/{language}.md`:
80>
81> | Language | Env var(s) | Format |
82> |---|---|---|
83> | .NET | `AZURE_SQL_CONNECTION_STRING` | `Server=...;Authentication=Active Directory Managed Identity;User Id=<clientId>;` (ADO.NET) |
84> | Python | `AZURE_SQL_SERVER`, `AZURE_SQL_DATABASE`, `AZURE_CLIENT_ID` | Code obtains MI access token and passes via ODBC `attrs_before` |
85> | Node.js | `DATABASE_URL` | `sqlserver://<host>:1433;database=<db>;authentication=ActiveDirectoryMsi;clientId=<clientId>` (Prisma) |
86 
87> ```bicep
88> appSettings: [
89>   { name: 'AZURE_SQL_CONNECTION_STRING', value: 'Server=${sqlServer.properties.fullyQualifiedDomainName};Database=${dbName};Authentication=Active Directory Managed Identity;User Id=${managedIdentity.properties.clientId};' }
90> ]
91> ```
92 
93### Step 5: Add Source Code Integration
94 
951. Read `recipes/{integration}/source/{language}.md`
962. Add the integration code (service client, middleware, configuration)
973. Add package dependencies (NuGet, npm, pip, Maven)
98 
99> ⛔ **Do NOT replace the main entry point file** (Program.cs, app.py, index.js).
100> Recipes ADD integration code alongside the existing application code.
101 
102### Step 6: Update azure.yaml (if needed)
103 
104Some recipes require hooks:
105```yaml
106hooks:
107  postprovision:
108    posix:
109      shell: sh
110      run: ./infra/scripts/setup-db.sh
111    windows:
112      shell: pwsh
113      run: ./infra/scripts/setup-db.ps1
114```
115 
116### Step 7: Validate and Deploy
117 
118**Required Environment Setup:**
119```bash
120azd env set AZURE_LOCATION eastus2
121```
122 
123**Deployment (two-phase recommended):**
124```bash
125azd provision --no-prompt     # Create resources + RBAC assignments
126sleep 60                       # Wait for RBAC propagation
127azd deploy --no-prompt        # Deploy code (RBAC now active)
128```
129 
130> **CRITICAL: Never store database passwords in app settings.**
131> The correct approach is managed identity with passwordless connections.
132 
133## Critical Rules
134 
1351. **NEVER synthesize Bicep or Terraform from scratch** — always start from base template IaC
1362. **Do not restructure or replace base IaC files** — only ADD recipe modules alongside them
1373. **ALWAYS use recipe RBAC role GUIDs** — never let the LLM guess role IDs
1384. **ALWAYS use `--no-prompt`** — the agent must never elicit user input during azd commands
1395. **ALWAYS include a health check endpoint** at `/health`
1406. **ALWAYS use managed identity** — no connection strings with passwords
1417. **ALWAYS tag the App Service** with `azd-service-name` matching `azure.yaml`
142