ADR-052: Layer Renaming and AI Foundry Reorganization

Status: Accepted Date: 2025-10-24 Deciders: Infrastructure Team, Development Team, Architect Technical Story: Improve infrastructure clarity by renaming numeric layers to semantic names and reorganizing AI Foundry for better logical grouping

Context and Problem Statement

Our current 4-layer infrastructure architecture uses numeric layer names (Layer 1, Layer 2, Layer 3, Layer 4) which:

Lack Semantic Meaning: Developers must memorize what "Layer 2" contains
Don't Describe Purpose: Numbers don't convey deployment frequency or logical grouping
Cause Confusion: New developers ask "What's the difference between Layer 1 and Layer 2?"
Don't Scale Well: Adding new layers becomes "Layer 5, 6, 7..." without clear meaning

Additionally, AI Foundry Hub and Project are currently in Layer 1 (Foundation), but they are platform services that applications depend on, not pure infrastructure. This creates logical inconsistency: - Layer 1: VNet, Subnets, NSG (infrastructure) + AI Foundry (platform service) ← Mixed concerns - Layer 2: ACR (platform service) ← AI Foundry should be here with ACR

Example Developer Confusion:

Developer: "Where do I find the AI Foundry endpoint?"
Answer: "It's in Layer 1."
Developer: "Why isn't it in Layer 2 with ACR? They're both platform services."
Answer: "Good question... historical reasons?"

Decision Drivers

Clarity: Names should describe purpose and content
Semantic Meaning: Descriptive names over numeric labels
Logical Grouping: Group resources by architectural concern, not deployment convenience
Onboarding: New developers should intuitively understand layer purposes
Frequency Alignment: Layer names should hint at change frequency
Industry Standards: Use naming patterns familiar to cloud architects

Decision

Rename layers from numeric to semantic names and reorganize AI Foundry to Substrate layer.

Layer Renaming

Old Name	New Name	Semantic Meaning	Change Frequency
Layer 1	Foundation	Core infrastructure that rarely changes	Once per environment
Layer 2	Substrate	Platform services apps depend on	Occasional (platform upgrades)
Layer 3	AI Models	AI model deployments and configurations	Weekly/monthly (model testing)
Layer 4	Apps	Application containers and services	Daily/hourly (code changes)

AI Foundry Reorganization

Move AI Foundry from Foundation to Substrate:

Before (Incorrect Grouping):

Foundation (Layer 1):
  - VNet, Subnets, NSG          ← Infrastructure
  - Azure Bastion + VM          ← Infrastructure
  - Managed Identity            ← Infrastructure
  - Log Analytics               ← Infrastructure
  - AI Foundry Hub & Project    ← Platform Service (WRONG LAYER!)

Substrate (Layer 2):
  - Azure Container Registry    ← Platform Service

After (Correct Grouping):

Foundation:
  - VNet, Subnets, NSG          ← Pure Infrastructure
  - Azure Bastion + VM          ← Infrastructure
  - Managed Identity            ← Infrastructure
  - Log Analytics               ← Infrastructure
  - Key Vault                   ← Infrastructure

Substrate:
  - Azure Container Registry    ← Platform Service
  - AI Foundry Hub & Project    ← Platform Service (MOVED HERE!)

Rationale: 1. Foundation = Infrastructure Only: Networking, identity, logging, security 2. Substrate = Platform Services: Services that applications consume (ACR, AI Foundry) 3. Apps layer depends on Substrate: API needs both ACR (images) and AI Foundry (agents) 4. Logical Consistency: ACR and AI Foundry are both platform services

New Layer Definitions

Foundation (formerly Layer 1)

Semantic Meaning: Core infrastructure foundation that provides networking, identity, and security primitives

Resources: - VNet with subnet architecture - Network Security Groups (NSGs) - Azure Bastion + Windows Jump Box VM - Managed Identity (for all other resources) - Log Analytics Workspace - Key Vault (for deployment outputs)

Change Frequency: Once per environment (rarely modified) Deployment Time: ~10-15 minutes Dependencies: None

Conceptual Analogy: Foundation of a building - laid once, rarely changed

Substrate (formerly Layer 2)

Semantic Meaning: Platform substrate that provides services applications consume

Resources: - Azure Container Registry (ACR) - stores container images - AI Foundry Hub - AI platform management - AI Foundry Project - workspace for AI agents

Change Frequency: Occasional (platform version upgrades, configuration changes) Deployment Time: ~5-7 minutes Dependencies: Foundation (VNet, Managed Identity)

Conceptual Analogy: Substrate/soil that applications grow in - provides essential nutrients

AI Models (formerly Layer 3)

Semantic Meaning: AI model deployments and configurations

Resources: - GPT-4o deployment - GPT-4o-mini deployment - Other model deployments (future)

Change Frequency: Weekly/monthly (testing different models, adjusting capacity) Deployment Time: ~3-5 minutes Dependencies: Substrate (AI Foundry Project)

Conceptual Analogy: Seeds planted in substrate - can be changed frequently to test different varieties

Apps (formerly Layer 4)

Semantic Meaning: Application containers and services

Resources: - ACI Container Group (or future: Container Apps, AKS) - API container - UI container - MCP Application Verification container - MCP Document Processing container - MCP Financial Calculations container

Change Frequency: Daily/hourly (every code change) Deployment Time: ~1-2 minutes (after image build) Dependencies: Substrate (ACR, AI Foundry), AI Models (GPT-4o)

Conceptual Analogy: Fruit/crops growing on plants - harvested and replanted frequently

Consequences

Positive

Improved Clarity: Semantic names immediately convey purpose
"Foundation" → clearly infrastructure
"Substrate" → clearly platform services
"AI Models" → clearly AI deployments
"Apps" → clearly application code
Better Onboarding: New developers understand architecture faster
No need to memorize "Layer 1 has networking and AI Foundry"
Intuitive grouping by architectural concern
Logical Consistency: AI Foundry with ACR makes architectural sense
Both are platform services applications consume
Apps layer depends on both for functionality
Foundation is pure infrastructure
Documentation Alignment: Diagrams and docs use meaningful terms
Architecture diagrams more intuitive
Deployment guides easier to follow
Troubleshooting guides clearer
Frequency Awareness: Names hint at change frequency
"Foundation" suggests stability
"Apps" suggests frequent updates

Negative

Breaking Changes: All existing references need updating
Bicep files: layer1-foundation.bicep → foundation.bicep
Scripts: deploy-layer-1-foundation.sh → deploy-foundation.sh
Parameter files: dev-layer1.parameters.json → dev-foundation.parameters.json
Documentation: All guides referencing "Layer 1/2/3/4"
Migration Effort: ~2-3 hours to update all files and documentation
16 file renames (git mv to preserve history)
Update internal references in scripts
Update documentation
Temporary Confusion: Existing team members may initially use old names
Mitigation: Update CLAUDE.md with prominent notice
Mitigation: Use clear commit messages
Mitigation: Pair old and new names in docs during transition
AI Foundry Module Movement: Need to reorganize Bicep modules
Move AI Foundry modules from foundation.bicep to substrate.bicep
Update dependencies and outputs
Risk of deployment errors if not done carefully

Mitigations

Risk	Mitigation
Broken references after renaming	Search all files for "layer1", "layer2", etc., update systematically
Team uses old terminology	Update CLAUDE.md prominently, use new names consistently
Deployment failures during AI Foundry move	Test in dev environment first, validate all dependencies
Documentation out of sync	Update all docs in single commit with file renames
Historical ADRs confusing	Add note to old ADRs: "Layer X is now called Y"

File Rename Mapping

Bicep Files (4 renames)

layer1-foundation.bicep      → foundation.bicep
layer2-platform.bicep        → substrate.bicep
layer3-models.bicep          → ai-models.bicep
layer4-apps.bicep            → apps.bicep

Deployment Scripts (4 renames)

deploy-layer1-foundation.sh  → deploy-foundation.sh
deploy-layer2-platform.sh    → deploy-substrate.sh
deploy-layer3-models.sh      → deploy-ai-models.sh
deploy-layer4-apps.sh        → deploy-apps.sh

Parameter Files (8 renames)

dev-layer1.parameters.json   → dev-foundation.parameters.json
dev-layer2.parameters.json   → dev-substrate.parameters.json
dev-layer3.parameters.json   → dev-ai-models.parameters.json
test-layer1.parameters.json  → test-foundation.parameters.json
test-layer2.parameters.json  → test-substrate.parameters.json
test-layer3.parameters.json  → test-ai-models.parameters.json
dev-layer4.parameters.json   → dev-apps.parameters.json (if exists)
test-layer4.parameters.json  → test-apps.parameters.json (if exists)

Total: 16 file renames

Implementation Plan

Step 1: Update CLAUDE.md

Update project documentation with new layer names BEFORE renaming files.

Step 2: Rename Files (Preserve Git History)

cd /workspaces/loan-defenders/infrastructure/bicep

# Rename Bicep files
git mv layer1-foundation.bicep foundation.bicep
git mv layer2-platform.bicep substrate.bicep
git mv layer3-models.bicep ai-models.bicep
git mv layer4-apps.bicep apps.bicep

# Rename deployment scripts
cd /workspaces/loan-defenders/infrastructure/scripts
git mv deploy-layer1-foundation.sh deploy-foundation.sh
git mv deploy-layer2-platform.sh deploy-substrate.sh
git mv deploy-layer3-models.sh deploy-ai-models.sh
git mv deploy-layer4-apps.sh deploy-apps.sh

# Rename parameter files
cd /workspaces/loan-defenders/infrastructure/bicep/environments
git mv dev-layer1.parameters.json dev-foundation.parameters.json
git mv dev-layer2.parameters.json dev-substrate.parameters.json
git mv dev-layer3.parameters.json dev-ai-models.parameters.json
git mv dev-layer4.parameters.json dev-apps.parameters.json
git mv test-layer1.parameters.json test-foundation.parameters.json
git mv test-layer2.parameters.json test-substrate.parameters.json
git mv test-layer3.parameters.json test-ai-models.parameters.json
git mv test-layer4.parameters.json test-apps.parameters.json

Step 3: Update Internal References

# Update references in deployment scripts
cd /workspaces/loan-defenders/infrastructure/scripts

# Update script references to new Bicep file names
sed -i 's/layer1-foundation.bicep/foundation.bicep/g' *.sh
sed -i 's/layer2-platform.bicep/substrate.bicep/g' *.sh
sed -i 's/layer3-models.bicep/ai-models.bicep/g' *.sh
sed -i 's/layer4-apps.bicep/apps.bicep/g' *.sh

# Update parameter file references
sed -i 's/layer1\.parameters\.json/foundation.parameters.json/g' *.sh
sed -i 's/layer2\.parameters\.json/substrate.parameters.json/g' *.sh
sed -i 's/layer3\.parameters\.json/ai-models.parameters.json/g' *.sh
sed -i 's/layer4\.parameters\.json/apps.parameters.json/g' *.sh

Step 4: Move AI Foundry Modules

# In foundation.bicep - REMOVE AI Foundry modules
# Move these module definitions to substrate.bicep:
#   - ai-foundry-hub.bicep
#   - ai-foundry-project.bicep

# In substrate.bicep - ADD AI Foundry modules
# Add dependency on Foundation outputs (VNet, Managed Identity)

Step 5: Update Documentation

# Update all references in documentation
cd /workspaces/loan-defenders/docs

# Update layer terminology
find . -type f -name "*.md" -exec sed -i 's/Layer 1/Foundation/g' {} +
find . -type f -name "*.md" -exec sed -i 's/Layer 2/Substrate/g' {} +
find . -type f -name "*.md" -exec sed -i 's/Layer 3/AI Models/g' {} +
find . -type f -name "*.md" -exec sed -i 's/Layer 4/Apps/g' {} +

Step 6: Validate

# Verify no broken references
grep -r "layer1" infrastructure/ docs/ --include="*.bicep" --include="*.sh" --include="*.md"
grep -r "layer2" infrastructure/ docs/ --include="*.bicep" --include="*.sh" --include="*.md"
grep -r "layer3" infrastructure/ docs/ --include="*.bicep" --include="*.sh" --include="*.md"
grep -r "layer4" infrastructure/ docs/ --include="*.bicep" --include="*.sh" --include="*.md"

# Test deployment (dry-run)
./infrastructure/scripts/deploy-foundation.sh dev ldfdev-rg --what-if
./infrastructure/scripts/deploy-substrate.sh dev ldfdev-rg --what-if

Architecture Diagram Comparison

Before (Numeric Layers)

┌─────────────────────────────────────────────────────────────┐
│ Layer 4: Apps (1-2 min, daily/hourly)                      │
│   - ACI Container Group (API, UI, 3 MCP servers)           │
└─────────────────────────────────────────────────────────────┘
                            ↓ depends on
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: AI Models (3-5 min, weekly/monthly)               │
│   - GPT-4o deployment                                       │
│   - GPT-4o-mini deployment                                  │
└─────────────────────────────────────────────────────────────┘
                            ↓ depends on
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Platform (5-10 min, occasionally)                 │
│   - Azure Container Registry (ACR)                          │
└─────────────────────────────────────────────────────────────┘
                            ↓ depends on
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Foundation (10-15 min, rarely)                    │
│   - VNet, Subnets, NSG                                      │
│   - Azure Bastion + Jump Box VM                             │
│   - Managed Identity, Log Analytics                         │
│   - AI Foundry Hub & Project  ← WRONG LAYER!               │
└─────────────────────────────────────────────────────────────┘

After (Semantic Names + AI Foundry Reorganization)

┌─────────────────────────────────────────────────────────────┐
│ Apps (1-2 min, daily/hourly) - Application Containers      │
│   - ACI Container Group (API, UI, 3 MCP servers)           │
└─────────────────────────────────────────────────────────────┘
                            ↓ depends on
┌─────────────────────────────────────────────────────────────┐
│ AI Models (3-5 min, weekly/monthly) - Model Deployments    │
│   - GPT-4o deployment                                       │
│   - GPT-4o-mini deployment                                  │
└─────────────────────────────────────────────────────────────┘
                            ↓ depends on
┌─────────────────────────────────────────────────────────────┐
│ Substrate (5-7 min, occasionally) - Platform Services      │
│   - Azure Container Registry (ACR)                          │
│   - AI Foundry Hub & Project  ← MOVED HERE! ✅             │
└─────────────────────────────────────────────────────────────┘
                            ↓ depends on
┌─────────────────────────────────────────────────────────────┐
│ Foundation (10-15 min, rarely) - Core Infrastructure       │
│   - VNet, Subnets, NSG                                      │
│   - Azure Bastion + Jump Box VM                             │
│   - Managed Identity, Log Analytics, Key Vault             │
└─────────────────────────────────────────────────────────────┘

Key Improvements: 1. ✅ Semantic names clearly describe purpose 2. ✅ AI Foundry logically grouped with ACR (both platform services) 3. ✅ Foundation is pure infrastructure (no platform services) 4. ✅ Dependency flow more intuitive

Terminology Transition

During documentation updates, use this transition approach:

Example 1 (Architecture Docs):

## Foundation Layer (formerly Layer 1)
Core infrastructure including VNet, Bastion, and Managed Identity.

Example 2 (Deployment Guides):

## Step 1: Deploy Foundation
Run `./infrastructure/scripts/deploy-foundation.sh`
(Previously: `deploy-layer1-foundation.sh`)

Example 3 (Troubleshooting):

If Foundation deployment fails, check VNet configuration.
Note: Foundation was previously called "Layer 1" in older docs.

Success Criteria

✅ All 16 files renamed successfully (git history preserved)
✅ No references to "layer1", "layer2", "layer3", "layer4" in active files
✅ AI Foundry modules moved from Foundation to Substrate
✅ Deployment scripts work with new file names
✅ Documentation updated consistently
✅ CLAUDE.md prominently shows new layer names
✅ Test deployment succeeds in dev environment

Related: ADR-049 (Container Deployment - ACI) - uses layer terminology
Related: ADR-050 (Bastion Replaces VPN) - Foundation layer change
Related: ADR-051 (KISS Simplification) - parameter file consolidation
Related: ADR-041 (4-Layer Architecture) - original layer design (still valid, just renamed)

References

Status: Accepted Date Accepted: 2025-10-24 Impact: Medium (file renames + AI Foundry reorganization) Breaking Changes: Yes (all layer references updated)