Layer Architecture

Layer Architecture

Overview

The az prototype extension organizes all Azure resources and application code into a four-level taxonomy: Layer, Capability, Component, and Resource. This hierarchy drives deployment ordering, agent ownership, and service placement throughout the pipeline.

The canonical source of truth for this taxonomy is azext_prototype/knowledge/taxonomy.yaml. The az prototype validate command checks that stage capability and service component values match this file.

Four-Level Hierarchy

Layer  -->  Capability  -->  Component  -->  Resource

Level	Description	Example
Layer	Top-level architectural boundary	infra
Capability	Sub-classification within a layer	core-networking
Component	Functional role within a capability	api-gateway
Resource	Azure resource type or code artifact	Microsoft.ApiManagement/service

Complete Taxonomy

Core Layer

Cross-cutting foundations -- identity and observability.

Capability	Component	Description
Identity	managed-identity	User/system-assigned managed identities
Observability	log-analytics	Log Analytics workspace
	application-insights	Application Insights
	monitoring	Azure Monitor

Infrastructure Layer

Azure resource provisioning via IaC.

Capability	Component	Description
Core Networking	connectivity	VNet, subnets, peering, gateways
	load-balancing	Load Balancer, App Gateway, Front Door
	private-access	Private Endpoints, Private DNS Zones
	dns	DNS Zones, DNS records
	api-gateway	API Management
Compute	container-hosting	Container Apps, AKS
	web-hosting	App Service
	serverless	Azure Functions
	static-hosting	Static Web Apps
Security	secrets-management	Key Vault
	threat-protection	Azure Defender
	identity-protection	Microsoft Sentinel
AI Services	cognitive	Azure OpenAI, Cognitive Services
	search	Azure AI Search
	ml	ML Workspace, AI Foundry
Supporting	container-registry	Azure Container Registry
	configuration	Azure App Configuration
	communication	Communication Services, Notification Hubs

Data Layer

Databases, storage, and messaging services.

Capability	Component	Description
Data Services	relational-db	Azure SQL, PostgreSQL, MySQL
	nosql-db	Cosmos DB
	caching	Azure Cache for Redis
	analytics	Databricks, Synapse, Data Factory
Storage Services	blob-storage	Blob containers
	file-storage	Azure Files, Premium File Shares
	data-lake	Data Lake Storage Gen2
Messaging	message-broker	Service Bus
	event-streaming	Event Hubs
	event-routing	Event Grid
	iot-ingestion	IoT Hub

Application Layer

Application source code with distinct sub-layers.

Capability	Component	Description
Presentation	controllers	API controllers (Blazor/MVC server-side)
	views	UI pages, Razor views, React components
	components	Reusable UI components
	routing	Client-side routing, navigation
Domain (Business Logic)	services	Business logic service classes
	entities	Domain models, value objects
	validation	Business rule validation
	workflows	Workflow orchestration, sagas
Data Access	repositories	Repository pattern implementations
	orm-adapters	Entity Framework Core, SQLAlchemy, Prisma
	query-builders	Custom query builders, specifications
Background	workers	Background hosted services
	message-handlers	Service Bus / Event Hub consumers
	scheduled-tasks	Timer-triggered functions, cron jobs

Documentation Layer

Architecture and deployment documentation.

Capability	Component	Description
Documentation	architecture-doc	Architecture documentation
	deployment-guide	Deployment guides and runbooks

Layer Ownership

Each layer is owned by a specific architect agent that maintains awareness of all services and patterns within that boundary.

Layer	Owner Agent	Delegates To
core	cloud-architect	terraform-agent, bicep-agent
infra	infrastructure-architect	terraform-agent, bicep-agent
data	data-architect	terraform-agent, bicep-agent
app	application-architect	csharp-developer, python-developer, react-developer
docs	doc-agent	(none)

The cloud-architect serves as the top-level coordinator across all layers and owns the core cross-cutting layer directly. The security-architect operates as a cross-cutting reviewer across all layers (infra, data, and app) but does not own a layer.

Deployment Order

Layers are deployed in a strict dependency order. Each layer's resources may depend on outputs from the previous layer:

core  -->  infra  -->  data  -->  app  -->  docs

Order	Layer	Rationale
1	core	Identity and observability must exist before any resources reference them
2	infra	Networking, compute, and supporting services must be provisioned before data or app layers can use them
3	data	Databases and storage must exist before application code can connect
4	app	Application code deploys into infrastructure, connects to data services
5	docs	Documentation is generated last, referencing the deployed architecture

Within a layer, stages are further ordered by capability dependencies (e.g., networking before compute, compute before supporting services).

Service Placement Rules

Services are placed into layers and capabilities based on their primary architectural role, not their ARM namespace alone. Key placement decisions:

Service	Layer	Capability	Component	Rationale
Key Vault	infra	security	secrets-management	Infrastructure-level secrets management
API Management	infra	core-networking	api-gateway	Network-layer API gateway/routing
IoT Hub	data	messaging	iot-ingestion	Data ingestion endpoint
Event Grid	data	messaging	event-routing	Event routing between services
Service Bus	data	messaging	message-broker	Async message brokering
Event Hubs	data	messaging	event-streaming	High-throughput event streaming
Cosmos DB	data	data-services	nosql-db	NoSQL database
Container Apps	infra	compute	container-hosting	Compute hosting for containers
Static Web Apps	infra	compute	static-hosting	Frontend hosting

Inter-Layer Communication Patterns

Layers communicate through well-defined boundaries:

From	To	Communication Pattern
core	infra	Managed identities attached to infrastructure resources
infra	data	Private endpoints from VNets to data services; RBAC role assignments
data	app	Connection endpoints (not secrets) consumed via environment variables; managed identity for auth
app (presentation)	app (domain)	Direct method calls via dependency injection
app (domain)	app (data-access)	Repository interfaces; dependency injection
app (frontend)	app (backend)	REST API calls with Bearer token (MSAL)

Cross-layer rules:

• Application code NEVER accesses infrastructure directly (uses SDKs and endpoints)
• Frontend NEVER accesses Azure services directly (uses backend API endpoints)
• All service-to-service authentication uses managed identity
• Data access from the application layer uses managed identity, never connection strings with secrets

Source of Truth

The canonical taxonomy definition is in:

azext_prototype/knowledge/taxonomy.yaml

The az prototype validate command validates that all stage capability values and service component values in deployment plans match the entries in this file. Any new service or capability must be added to the taxonomy before it can be used in a build.

See also: Application Architecture for details on the app layer's sub-layer structure, Agent System for the full agent roster and contracts.