1# Architecture Planning
2 
3Select hosting stack and map components to Azure services.
4 
5## Stack Selection
6 
7| Stack           | Best For                                               | Azure Services                    |
8| --------------- | ------------------------------------------------------ | --------------------------------- |
9| **Containers**  | Docker experience, complex dependencies, microservices | Container Apps, AKS, ACR          |
10| **Serverless**  | Event-driven, variable traffic, cost optimization      | Functions, Logic Apps, Event Grid |
11| **App Service** | Traditional web apps, PaaS preference                  | App Service, Static Web Apps      |
12 
13### Decision Factors
14 
15| Factor                   | Containers |          Serverless          | App Service |
16| ------------------------ | :--------: | :--------------------------: | :---------: |
17| Docker experience        |     ✓✓     |                              |             |
18| Event-driven             |     ✓      |              ✓✓              |             |
19| Variable traffic         |            |              ✓✓              |      ✓      |
20| Complex dependencies     |     ✓✓     |                              |      ✓      |
21| Long-running processes   |     ✓✓     |    ✓ (Durable Functions)     |      ✓      |
22| Workflow / orchestration |            | ✓✓ (Durable Functions + DTS) |             |
23| Minimal ops overhead     |            |              ✓✓              |      ✓      |
24 
25### Container Hosting: Container Apps vs AKS
26 
27| Factor                    |       Container Apps        |                 AKS                 |
28| ------------------------- | :-------------------------: | :---------------------------------: |
29| **Scale to zero**         |             ✓✓              |                                     |
30| **Kubernetes API access** |                             |                 ✓✓                  |
31| **Custom operators/CRDs** |                             |                 ✓✓                  |
32| **Service mesh**          |       Dapr (built-in)       |                Istio                |
33| **Networking/dataplane**  |  Managed platform defaults  |     Azure CNI powered by Cilium     |
34| **GPU workloads**         |                             |                 ✓✓                  |
35| **Best for**              | Microservices, event-driven | Full K8s control, complex workloads |
36 
37#### When to Use Container Apps
38 
39- Microservices without Kubernetes complexity
40- Event-driven workloads (KEDA built-in)
41- Need scale-to-zero for cost optimization
42- Teams without Kubernetes expertise
43 
44#### When to Use AKS
45 
46- Need Kubernetes API/kubectl access
47- Require custom operators or CRDs
48- Service mesh requirements (Istio, Linkerd)
49- GPU/ML workloads
50- Complex networking or multi-tenant architectures
51 
52> **AKS Planning:** For AKS SKU selection (Automatic vs Standard), networking, identity, scaling, and security configuration, invoke the **azure-kubernetes** skill.
53 
54## Service Mapping
55 
56### Hosting
57 
58| Component Type           | Primary Service   | Alternatives                                     |
59| ------------------------ | ----------------- | ------------------------------------------------ |
60| SPA Frontend             | Static Web Apps   | Blob + CDN                                       |
61| SSR Web App              | Container Apps    | App Service, AKS                                 |
62| REST/GraphQL API         | Container Apps    | App Service, Functions, AKS                      |
63| Background Worker        | Container Apps    | Functions, AKS                                   |
64| Scheduled Task           | Functions (Timer) | Container Apps Jobs, Kubernetes CronJob (on AKS) |
65| Event Processor          | Functions         | Container Apps, AKS + KEDA                       |
66| Microservices (full K8s) | AKS               | Container Apps                                   |
67| GPU/ML Workloads         | AKS               | Azure ML                                         |
68 
69### Data
70 
71| Need       | Primary      | Reference                                       | Alternatives      |
72| ---------- | ------------ | ----------------------------------------------- | ----------------- |
73| Relational | Azure SQL    | [SQL Database](services/sql-database/README.md) | PostgreSQL, MySQL |
74| Document   | Cosmos DB    | [Cosmos DB](services/cosmos-db/README.md)       | MongoDB           |
75| Cache      | Redis Cache  |                                                 |                   |
76| Files      | Blob Storage | [Storage](services/storage/README.md)           | Files Storage     |
77| Search     | AI Search    |                                                 |                   |
78 
79### Integration
80 
81| Need          | Service     |
82| ------------- | ----------- |
83| Message Queue | Service Bus |
84| Pub/Sub       | Event Grid  |
85| Streaming     | Event Hubs  |
86 
87### Workflow & Orchestration
88 
89| Need                                | Service                                        | Notes                                                                                                                                                       |
90| ----------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
91| Multi-step workflow / orchestration | **Durable Functions + Durable Task Scheduler** | DTS is the **required** managed backend for Durable Functions. Do NOT use Azure Storage or MSSQL backends. See [durable.md](services/functions/durable.md). |
92| Low-code / visual workflow          | Logic Apps                                     | For integration-heavy, low-code scenarios                                                                                                                   |
93 
94### Supporting (Always Include)
95 
96| Service              | Purpose                 |
97| -------------------- | ----------------------- |
98| Log Analytics        | Centralized logging     |
99| Application Insights | Monitoring, APM         |
100| Key Vault            | Secrets management      |
101| Managed Identity     | Service-to-service auth |
102 
103---
104 
105## Document Architecture
106 
107Record selections in `.azure/deployment-plan.md` with rationale for each choice.
108