Developer Mode: Smart Routing with Kind Fast Path & Capacity Failover

# Product Requirements Document: Developer Mode

---

## Executive Summary

Developer Mode transforms AKS Desktop from a Kubernetes management tool into an app deployment platform. It targets application developers who want to deploy code to Azure without understanding Kubernetes — the same audience that uses Heroku, Fly.io, or Railway today. By hiding all infrastructure complexity behind smart defaults and auto-configuration, Developer Mode offers a "pick a repo, click deploy, app is running" experience on top of Azure Kubernetes Service.

### The Problem

AKS Desktop currently presents users with a complex Kubernetes-oriented interface: cluster configuration, node pools, workloads, networking, storage, pod-level metrics, HPA configuration, and multi-step deployment wizards. For application developers who just want to ship code, this is overwhelming and unnecessary. These users don't care about pods, ingress manifests, or container registries — they care about whether their app is running, how fast it responds, and what the logs say.

Compounding this, AKS cluster creation takes 5-10 minutes and can fail due to regional capacity constraints — a direct contradiction of the "fast deploy" promise.

### The Opportunity

There is a significant gap between "Kubernetes for platform teams" (what AKS Desktop does today) and "deploy my app" (what developers actually want). Multiple platforms have proven this market exists with their developer-first approach. By adding a Developer Mode that delivers this type of experience on Azure infrastructure, AKS Desktop can serve both audiences — platform engineers who need the full Kubernetes surface, and application developers who prefer it hidden.

### The Solution

A global "Developer Mode" toggle that transforms the entire AKS Desktop experience: new sidebar navigation focused on apps (not clusters), a 3-step deploy flow (pick repo → review config → deploy), an app dashboard with metrics/logs/scaling, and a **Smart Router** that automatically picks the fastest path to get the app running — deploying locally in seconds via Kind when no Azure infrastructure exists, while provisioning AKS in the background.

---

## Target User

### Primary Persona: The App Developer

- Has code in a GitHub repository
- Wants it running on Azure with a public URL
- Does not know (or care about) Kubernetes concepts
- Comfortable with: Git, GitHub, web frameworks (Node, Python, .NET, Go)
- Not comfortable with: Kubernetes manifests, container registries, ingress controllers, HPA configuration, node pools
- Current alternatives: Heroku, Fly.io, Railway, Azure App Service, Azure Container Apps

### Key User Insight

> "I don't want to learn Kubernetes. I just want my app deployed. Tell me the URL and show me if it's healthy."

### What This Persona Values

1. **Speed** — from code to running app in seconds, not minutes
2. **Simplicity** — pick a repo, click deploy, done
3. **Visibility** — is my app running? How fast is it? What do the logs say?
4. **Auto-everything** — auto-detect, auto-configure, auto-deploy on push

---

## Core Principle

**The developer never sees the word "cluster," "pod," "namespace," "ingress," or any other Kubernetes primitive.** They work with apps, instances, sizes, and regions.

### Vocabulary Mapping

| Developer Mode | Kubernetes Concept |
|---|---|
| App | Managed Namespace + Deployment |
| Instance | Pod / Replica |
| Size (Small/Medium/Large) | Resource requests/limits |
| Region | Cluster location |
| Auto-scale | Horizontal Pod Autoscaler |
| Env & Secrets | ConfigMaps / Secrets |
| Deploy | Apply manifests / Pipeline run |

---

## UX Philosophy

### Reduce Decisions to Zero

The best deploy experience asks the user to make **zero decisions** to get from code to running app. Every question, toggle, or form field is friction that loses users. The ideal flow:

1. Connect your source (one click)
2. We figure everything out (auto-detection)
3. You confirm and deploy (one click)

This means: **detect everything, auto-fix everything, hide everything that doesn't need attention.**

### The Five Pillars

**1. Confident First Impressions** — The landing page should make the user feel like the tool is powerful and trustworthy. Bold heading with a specific claim ("Ship to Azure in 60 seconds"), feature cards that explain what the system does for you, single prominent CTA button. Never start with a bare form.

**2. Smart Defaults Over Exposed Settings** — Show a collapsed one-line summary (`appName · framework · region · size`) with detection badges (`Dockerfile found`, `Port 8080`, `Auto-deploy on push`). Hide the full form behind a "Customize" link. Auto-expand only when something needs attention.

**3. Auto-Fix, Don't Reject** — When user input doesn't meet requirements (DNS names, character limits), fix it automatically rather than showing an error. `"My-Cool.App"` → `"my-cool-app"`. Only show validation errors when the user manually edits the name to something invalid.

**4. Engaging Progress** — Long-running operations are make-or-break moments. Use a terminal-style build log with steps appearing one at a time, a pulsing active indicator, elapsed times, and step counters. Break one big step into many small visible steps to keep users engaged.

**5. Immediate Mode Commitment** — Toggle Developer Mode ON → navigate directly to `/dev/deploy`. App launch with mode already on → auto-redirect. Don't make users navigate to find what they just enabled.

### Visual Language

- **Terminal panels:** dark background (`#0d0b1a`) with monospace font
- **Cards/surfaces:** `action.hover` background with `divider` border
- **Status colors:** green (running), blue pulsing (in-progress), dim (pending), red (error)
- **Typography:** gradient hero headings (h4, 700), section headings (h5, 600), body2 for content

---

## Feature Requirements

### FR-1: Mode Switching

**Priority:** P0

A global toggle transforms the entire application UI.

| Requirement | Detail |
|---|---|
| Toggle location | Settings page + sidebar switcher |
| Default | Standard Mode (opt-in to Developer Mode) |
| Persistence | Stored in plugin settings, survives app restart |
| Mode coexistence | Same underlying data (namespaces) visible in both modes |
| Transition | Instant — no data migration, no restart required |

**Acceptance criteria:**
- Toggling to Developer Mode replaces the sidebar, hides all K8s navigation, and redirects to `/dev/deploy`
- Toggling back restores the standard Headlamp UI immediately
- Apps created in Developer Mode appear as projects in Standard Mode (and vice versa for projects with developer labels)

---

### FR-2: Developer Mode Navigation

**Priority:** P0

| Element | Behavior |
|---|---|
| Sidebar: Apps section | Lists all developer apps with inline health indicators (green/yellow/red dot) |
| Sidebar: "Deploy New App" | Entry point to the deploy flow |
| Sidebar: Account section | Links to Profile and Settings |
| Sidebar: Mode toggle | Compact switcher showing "Developer Mode" / "Standard Mode" with "switch" label |
| Sidebar: Provisioning indicator | Subtle cloud icon with spinner when background AKS provisioning is active (hoverable for details) |
| Hidden elements | No Cluster, Nodes, Workloads, Network, Storage, or any K8s operational sections |

**Acceptance criteria:**
- Sidebar shows only Apps, Deploy New App, and Account
- Health indicators reflect real deployment status (running, deploying, error, stopped)
- Clicking an app navigates to its dashboard
- Settings link opens Headlamp's settings page

---

### FR-3: Deploy New App Flow

**Priority:** P0

A 3-step wizard: Connect Repository → Review Configuration → Deploy.

#### Step 1: Connect Repository

| Requirement | Detail |
|---|---|
| Authentication | GitHub OAuth via existing auth flow |
| Repo picker | Searchable list of user's GitHub repos |
| Branch selector | Dropdown fetched from GitHub API, defaults to default branch |
| Navigation | "Continue" button advances to Step 2 |

#### Step 2: Review Configuration

All settings are auto-detected/auto-configured with smart defaults. Each is editable. Presented as a collapsed summary with a "Customize" link for power users.

| Setting | Default | How determined | Editable |
|---|---|---|---|
| App name | Repo name (DNS-sanitized) | Derived from repo | Yes (text field) |
| Dockerfile | Detected or "will be generated" | GitHub API check for Dockerfile | Display only |
| Region | South Central US | Subscription default (future: nearest) | Yes (dropdown) |
| Size | Small (1 vCPU, 2 GB) | Default | Yes (Small/Medium/Large) |
| Auto-deploy | On | Default | Yes (toggle) |

Navigation: "Back" returns to Step 1, "Deploy" starts the deploy.

#### Step 3: Deploying

The **Smart Router** automatically selects the fastest deployment path based on the user's environment. The user never sees this decision — they just see progress.

**Path A — Direct AKS (~30 seconds):** When a tagged AKS cluster already exists in the user's selected region.
1. Built container image (remote ACR build)
2. Deployed to cluster (K8s manifests applied)
3. Health check passed
4. Auto-deploy pipeline configured (background)

**Path B — Kind Fast Path (~30 seconds + background AKS):** When no AKS cluster exists but Docker is available locally.
1. Setting up local environment (Kind cluster)
2. Building container image (local Docker build)
3. Loading image into local cluster
4. Deployed to local cluster
5. *Background: Azure environment being prepared...*

**Path C — AKS Provision (~5-10 minutes):** When no AKS cluster and no Docker runtime.
1. Validating region capacity
2. Provisioning infrastructure (cluster + ACR)
3. Built container image (remote ACR build)
4. Deployed to cluster
5. Health check passed

**Agent path (no Dockerfile, any deployment path):** Adds 5-10 minutes for containerization-assist-mcp analysis and Dockerfile generation before the build step.

#### Completion

Success screen with:
- App name + "is live!" message (or "is running locally!" for Kind path)
- URL (Azure URL or `localhost:PORT` for Kind)
- Region and auto-deploy status
- "Open App" and "Go to Dashboard" buttons
- For Kind path: info banner explaining Azure is being prepared in the background

**Acceptance criteria:**
- User can deploy an app from a GitHub repo with a Dockerfile in under 60 seconds (when Docker is available locally)
- Direct AKS path deploys in under 2 minutes (existing cluster)
- No Kubernetes terminology visible at any step
- Progress shows real-time status of each step
- Failed steps show clear error state
- User never chooses between deployment paths — the system selects automatically

---

### FR-4: App Dashboard

**Priority:** P0

The developer's home base after deploying.

#### Layout: Three Zones

**Zone 1 — Hero:**
- App name + status badge (Running / Deploying / Error / Stopped)
- URL (clickable, opens in browser) — localhost for Kind, Azure URL for AKS
- Region, instance count, last deploy info (commit + message + time)
- "Redeploy" and "Open App" buttons
- **Promotion banner** (Kind environment only — see FR-9)

**Zone 2 — Glanceable Cards:**
Three compact cards in a row:
1. **Metrics Card** — request rate, error rate, p95/p50 latency (or "Available after promotion to Azure" placeholder when on Kind)
2. **Scaling Card** — instance count, auto-scale status, mini chart (or placeholder when on Kind)
3. **Recent Deploys Card** — last 3 deploys with commit, message, time

**Zone 3 — Live Log Tail:**
Dark terminal-style panel, ~10 lines of streaming logs aggregated across all instances. "Errors only" filter toggle. "Open full logs" link.

#### Tabs

| Tab | Content |
|---|---|
| Overview | The three-zone layout above |
| Logs | Full searchable log viewer, aggregated across instances |
| Deploys | Deploy history from GitHub Actions with commit, status, time |
| Env & Secrets | Key-value editor for environment variables. Secrets masked. |
| Scaling | Instance count, size selection, auto-scale toggle (or "Available after promotion" on Kind) |

**Acceptance criteria:**
- Dashboard shows real deployment status from Kubernetes (works on both Kind and AKS)
- Metrics card shows real Prometheus data on AKS; placeholder on Kind
- Logs stream from all pods (up to 5), aggregated and sorted by timestamp
- Deploy history fetches from GitHub Actions workflow runs
- Env & Secrets editor allows adding/editing/removing variables
- Scaling tab shows current scaling configuration on AKS; placeholder on Kind

---

### FR-5: Smart Router & Invisible Infrastructure

**Priority:** P0

All Azure/Kubernetes infrastructure is created and managed behind the scenes. A **Smart Router** automatically selects the fastest deployment path.

#### Smart Router Decision Tree

```
User clicks Deploy
→ Check: tagged AKS cluster exists & healthy for this region?
YES → DIRECT_AKS path (deploy to existing cluster, ~30s)
NO → Check: Docker runtime available locally?
YES → KIND_FAST path (deploy to Kind ~30s, provision AKS in background)
NO → AKS_PROVISION path (provision AKS with progress UI, ~5-10 min)
```

The user never sees this decision. They click "Deploy" and the system picks the fastest available path.

#### Environment Detection

Runs once at app startup, cached for the session:
- Query Azure Resource Graph for AKS clusters tagged `aks-desktop:devmode=true` matching the current user
- Check for Docker daemon availability (`docker info`)
- Check for existing Kind cluster (`kind get clusters`)

#### Auto-provisioned Azure Resources (per region, first deploy)

| Resource | Naming Convention | Configuration |
|---|---|---|
| Resource Group | `aks-developer-{region}` | Tagged with devmode metadata |
| AKS Cluster | `aks-dev-{region}` | Standard tier, 2-node system + autoscaling user pool (1-10), Prometheus, managed identity, Azure RBAC, Azure CNI |
| Container Registry | `aksdev{region}{unique}` | Basic SKU |

#### Azure Resource Tags

All devmode Azure resources are tagged for discovery and attribution:

| Tag | Value |
|-----|-------|
| `aks-desktop:devmode` | `"true"` |
| `aks-desktop:owner` | `"{userObjectId}"` |
| `aks-desktop:owner-name` | `"{userDisplayName}"` |
| `aks-desktop:created` | `"{ISO timestamp}"` |

Cluster discovery uses Resource Graph queries filtering on these tags. The naming convention is kept for human readability but tags are the source of truth.

#### Per-app Resources

| Resource | Detail |
|---|---|
| Managed Namespace | One per app, labeled with developer mode metadata |
| Deployment | App container with configured size/replicas |
| Service | ClusterIP exposing the app port (AKS) or NodePort (Kind) |
| Ingress | Web app routing with auto-generated hostname (AKS only) |

#### Cluster Reuse Logic

- Existing tagged AKS cluster in region → deploy directly (~30s)
- No AKS cluster + Docker available → Kind locally (~30s) + background AKS provisioning
- No AKS cluster + no Docker → provision AKS with progress UI (~5-10 min)
- Subsequent apps in same region → new namespace (~30s)

**Acceptance criteria:**
- Developer never sees "cluster," "namespace," or "node" in the UI
- First deploy with Docker available runs in under 60 seconds
- All Azure resources are tagged for discovery and cost attribution
- System automatically selects the fastest available deployment path
- Capacity failures are handled with automatic region fallback

---

### FR-6: Capacity Validation & Region Failover

**Priority:** P0

AKS cluster creation can fail due to VM SKU capacity constraints in a region. The system proactively validates capacity before attempting provisioning.

#### How It Works

1. **Pre-flight check** — Query `az vm list-skus` for the required VM sizes (`Standard_D2s_v3`, `Standard_D4s_v3`) in the selected region. Check for restrictions.

2. **Region ranking** — If the selected region lacks capacity, check geographically nearby alternatives in parallel using a static adjacency map (e.g., `eastus2` → `eastus`, `centralus`, `northcentralus`, `southcentralus`).

3. **User interaction:**
- If selected region has capacity → proceed silently
- If selected region lacks capacity → present available alternatives with one-click accept: "East US 2 doesn't have available capacity. Deploy to Central US?"
- If no regions have capacity → clear error with retry option

4. **Retry on creation failure** — Even with pre-validation, creation can fail (race conditions, quota limits). If provisioning fails, try remaining validated regions automatically. For Kind Fast Path users, this happens silently in the background — only prompt if all options are exhausted.

**Acceptance criteria:**
- Users are never surprised by capacity failures they have to debug
- Region fallback is offered proactively, not after a 10-minute failed provision
- Kind Fast Path users are shielded from capacity issues entirely during initial deploy

---

### FR-7: Kind Fast Path (Local Development)

**Priority:** P0

When no AKS cluster exists and Docker is available locally, deploy to a local Kind cluster for instant feedback while AKS provisions in the background.

#### Kind Cluster Setup (~15-20 seconds, one-time)

- Install Kind binary if not present (platform-appropriate, stored in `~/.aks-desktop/bin/kind`)
- Create or reuse cluster named `aks-desktop-dev` (single node, minimal config)
- Multiple apps share the same Kind cluster as separate namespaces (mirrors the AKS model)

#### App Deployment to Kind (~10-15 seconds)

1. Build image locally (`docker build`)
2. Load into Kind (`kind load docker-image`)
3. Apply Kubernetes manifests (NodePort service, no Ingress, `imagePullPolicy: Never`)
4. Apply namespace labels including `aks-desktop/environment: kind`
5. App available at `http://localhost:{assignedPort}`

#### Port Allocation

- Tracked in `~/.aks-desktop/kind-ports.json`
- Range 9100-9199, deterministic per app name
- Freed when app is removed or promoted

#### User Experience on Kind

| Capability | Status |
|------------|--------|
| App URL | `localhost:{port}` |
| Logs | Full |
| Deployment status | Full |
| Metrics | "Available after promotion to Azure" |
| Scaling | Not available |
| Auto-deploy | Disabled (local builds only) |

#### Kind Cluster Lifecycle

| Event | Behavior |
|-------|----------|
| App exit | Best-effort cleanup (`kind delete cluster`) |
| App launch (stale cluster detected) | Clean up and start fresh |
| Manual | User can delete from settings |

Kind clusters are throwaway infrastructure. No persistent storage, no state sync with AKS. Promotion is a fresh deploy, not a migration.

**Acceptance criteria:**
- Kind deploy completes in under 60 seconds from "Deploy" click
- App runs and is accessible at localhost URL
- Logs and status work identically to AKS
- Kind cluster is cleaned up on app exit
- Multiple apps can run on the same Kind cluster

---

### FR-8: Background AKS Provisioning

**Priority:** P0

When the Kind Fast Path is active, AKS infrastructure provisions in the background without user interaction.

#### Behavior

- Starts immediately when Kind deploy begins (concurrent, not sequential)
- Validates capacity in selected region, falls back to adjacent regions silently
- Creates resource group, AKS cluster, and ACR — all tagged
- Reports state via a subtle sidebar indicator (cloud icon with spinner)

#### Failure Handling

- Capacity failure → silently try next adjacent region
- All regions exhausted → non-blocking notification: "Couldn't find Azure capacity in nearby regions. [Try again] [Change region]"
- Transient errors → retry up to 3 times with backoff
- **Kind keeps working throughout** — AKS failure never disrupts the local experience

**Acceptance criteria:**
- User is never blocked waiting for AKS provisioning when on Kind
- Background provisioning failures don't affect the running local app
- Provisioning status is visible but not intrusive

---

### FR-9: Promotion (Kind → AKS)

**Priority:** P0

When background AKS provisioning completes, the user can promote their app to Azure with one click.

#### Promotion Banner

A non-intrusive, persistent banner at the top of the app dashboard:

> "Your Azure environment is ready. **Promote to Azure** →"

Single click. No configuration. No decisions.

#### Promotion Flow

1. **User clicks "Promote to Azure"** — stays on Kind, app continues running
2. **Background sequence:**
- Build image in ACR (`az acr build` from GitHub repo)
- Apply manifests to AKS cluster (real Ingress, ClusterIP service)
- Apply namespace labels (`aks-desktop/environment: aks`)
- Wait for deployment healthy
- Wait for ingress to get external URL
- If auto-deploy enabled, configure GitHub Actions pipeline
3. **Seamless switch:**
- Dashboard silently switches to point at AKS
- URL changes from `localhost:PORT` to Azure URL
- Notification: "Your app is now running on Azure — {url}"
- Metrics, scaling, and auto-deploy become available
- Kind cluster stays alive for the session (cleaned up on app exit)

#### Failure During Promotion

- ACR build or AKS deploy fails → notification with "Retry" button, Kind keeps running
- User is never left without a working app

#### Edge Cases

- **User never clicks the banner** — Kind keeps working, banner persists
- **Subsequent deploys after promotion** — router sees healthy AKS cluster → DIRECT_AKS path, Kind no longer involved

**Acceptance criteria:**
- Promotion is a single click with no configuration
- User's app continues running on Kind during the entire promotion process
- Dashboard switches seamlessly once AKS deployment is healthy
- Promotion failure never disrupts the running Kind app

---

### FR-10: Containerization

**Priority:** P0

Two paths depending on whether the repo has a Dockerfile.

#### Fast Path (Dockerfile exists)

- **AKS:** Remote build via `az acr build` (no local Docker required)
- **Kind:** Local `docker build` + `kind load docker-image`
- K8s manifests (Deployment + Service + Ingress/NodePort) generated from templates
- Applied directly to the cluster

#### Agent Path (no Dockerfile)

- Reuses existing containerization-assist-mcp via GitHub Copilot agent
- Agent analyzes repo, generates Dockerfile + K8s manifests + deploy workflow
- Presented to user as continuous progress (two-PR flow hidden)

**Acceptance criteria:**
- Dockerfile detection via GitHub API (checks repo root)
- Fast path skips the agent entirely — build and deploy directly
- Agent path generates production-quality Dockerfile and manifests
- Framework detection: Node.js (Express, Next, Fastify, React, Vue), Python, Go, .NET

---

### FR-11: CI/CD Pipeline (Auto-deploy)

**Priority:** P1

After the first deploy, subsequent deploys happen automatically on push to the configured branch.

- **Fast path:** Pipeline configured in the background after app is running
- **Agent path:** Pipeline ready immediately (agent generates the workflow)
- Uses GitHub Actions with workload identity federation
- Auto-deploy enabled by default, toggleable in the deploy flow
- Only available after promotion to AKS (not on Kind)

**Acceptance criteria:**
- Pushing to the configured branch triggers an automatic deploy
- Deploy history shows both manual and automated deploys
- Auto-deploy can be toggled on/off

---

### FR-12: Data Model

**Priority:** P0

Developer Mode apps are standard Kubernetes namespaces with additional labels.

```yaml
labels:
headlamp.dev/project-managed-by: aks-desktop
aks-desktop/mode: developer
aks-desktop/app-name: my-node-api
aks-desktop/github-repo: devuser/my-node-api
aks-desktop/github-branch: main
aks-desktop/app-region: eastus2
aks-desktop/environment: kind | aks
```

The `aks-desktop/environment` label distinguishes between apps running on a local Kind cluster (`kind`) and apps running on AKS (`aks`). This drives dashboard behavior (metrics/scaling availability, promotion banner visibility).

**Acceptance criteria:**
- Labels applied during deploy, before success screen
- `isDeveloperApp()` utility correctly identifies developer apps
- Apps visible in both Developer Mode (as apps) and Standard Mode (as projects)
- No separate database or state store — all state in K8s labels
- Environment label correctly reflects Kind vs AKS deployment target

---

## Non-Functional Requirements

### NFR-1: Performance

| Metric | Target |
|---|---|
| Mode toggle | < 100ms UI transition |
| Kind fast-path deploy (Docker available) | < 60 seconds |
| Direct AKS deploy (existing cluster) | < 2 minutes |
| First-time AKS provision (no Docker) | < 10 minutes |
| Kind→AKS promotion | < 3 minutes |
| Dashboard load | < 2 seconds |
| Log tail update interval | 5 seconds |
| Sidebar health indicator update | Real-time via K8s watch |

### NFR-2: Reliability

- Deploy flow handles Azure CLI failures gracefully with clear error messages
- Infrastructure provisioning is idempotent (safe to retry)
- Cluster discovery uses Resource Graph tag queries (robust, not name-dependent)
- Capacity validation prevents wasted provisioning attempts
- Kind deployment provides a working fallback when AKS isn't available
- Promotion failures never disrupt the running Kind app
- Log streaming fails silently (non-blocking)

### NFR-3: Security

- GitHub tokens managed via existing OAuth flow with automatic refresh
- Azure credentials via managed identity (no secrets stored)
- Workload identity federation for GitHub Actions
- Env var secrets masked in the UI, stored as K8s Secrets
- Azure Resource Graph queries validate inputs to prevent KQL injection

### NFR-4: Compatibility

- Works when `Headlamp.isRunningAsApp()` is true (Electron desktop app only)
- Requires Azure CLI authentication
- Requires GitHub account with repo access
- Kind fast path requires Docker Desktop or compatible container runtime (graceful degradation when unavailable)
- Standard mode functionality unchanged when Developer Mode is not active

---

## Out of Scope (v1)

These features are explicitly deferred to v2+:

| Feature | Rationale |
|---|---|
| Custom domains | v1 uses auto-generated Azure URLs |
| Managed database/service provisioning | v1 uses env vars for external service connections |
| Multi-region deployment | v1 deploys to a single region per app |
| Team collaboration / shared apps | v1 is single-user (tags include owner for future multi-user support) |
| Bring your own cluster | v1 auto-provisions; v2 adds cluster selection |
| Cost estimation | Deferred pending Azure pricing API integration |
| App-to-app networking | v1 apps are independent; no service mesh |
| Rollback | v1 supports redeploy; explicit rollback to prior version is v2 |
| Kind as persistent dev environment | v1 Kind is throwaway; v2 may support persistent local dev |
| State sync between Kind and AKS | v1 promotion is a fresh deploy; v2 may sync state |

---

## Success Metrics

### Adoption

- % of users who enable Developer Mode after installation
- % of Developer Mode users who complete at least one deploy
- Ratio of Developer Mode deploys to Standard Mode deploys

### Time to Value

- Time from "Deploy" click to running app (target: < 60s for Kind fast path)
- Time from app launch to first successful deploy
- Drop-off rate at each deploy flow step
- Kind→AKS promotion rate (% of Kind deploys that get promoted)

### Engagement

- Dashboard views per user per week
- Log tail usage (% of dashboard sessions that view logs)
- Redeploy frequency
- Auto-deploy adoption rate (% of apps with auto-deploy enabled)

### Quality

- Deploy success rate (target: > 95% for repos with Dockerfiles)
- Agent path success rate (target: > 80% for supported frameworks)
- Capacity validation accuracy (% of pre-validated regions that succeed)
- Promotion success rate (target: > 99%)

---

## Competitive Analysis

| Capability | Fly.io | Heroku | Railway | AKS Desktop Developer Mode |
|---|---|---|---|---|
| Deploy from repo | CLI `fly launch` | GitHub integration | GitHub integration | GUI: pick repo, click deploy |
| Time to first deploy | ~2 min | ~3 min | ~1 min | ~30s (Kind) / ~2 min (AKS) |
| Auto-detect framework | Yes (scanners) | Buildpacks | Nixpacks | containerization-assist-mcp |
| Infrastructure management | Hidden (Firecracker VMs) | Hidden (dynos) | Hidden | Hidden (Kind + AKS clusters) |
| Config file | `fly.toml` (15 lines) | `Procfile` | `railway.toml` | None (UI-driven) |
| Local development | `fly dev` (beta) | None | None | Kind cluster (instant) |
| Metrics | Built-in Prometheus | Add-on | Built-in | Built-in (Prometheus via AKS) |
| Scaling | CLI + config | Slider | Slider | GUI: size + instance count |
| CI/CD | GitHub Actions (4-line YAML) | GitHub integration | Auto-deploy | GitHub Actions (auto-configured) |
| Region failover | Manual | N/A | N/A | Automatic capacity validation + failover |
| Cloud provider | Fly.io | Salesforce | Railway | Azure (customer's subscription) |
| **Key differentiator** | CLI-first, edge computing | Simplicity, ecosystem | Speed, Nixpacks | Enterprise Azure, customer-owned infra, instant local deploy |

### Our Unique Position

Unlike Fly.io/Heroku/Railway, the infrastructure runs in the customer's own Azure subscription. This means:
- Enterprise compliance and data residency requirements are met by default
- No vendor lock-in on the compute layer
- Existing Azure monitoring, security, and networking integrate naturally
- The same cluster can host both Developer Mode apps and platform-team workloads

Unlike all competitors, we offer **instant local deployment** via Kind — the app is running before Azure infrastructure even exists. This eliminates the "cold start" problem entirely for users with Docker installed.

---

## Dependencies

| Dependency | Type | Status |
|---|---|---|
| Azure CLI (bundled) | Runtime | Shipped |
| GitHub OAuth (Electron IPC) | Runtime | Shipped |
| containerization-assist-mcp | External service | v1.3.2 integrated |
| Headlamp plugin API | Framework | Stable |
| AKS managed namespaces | Azure feature | Available |
| Web app routing (Ingress) | AKS add-on | Available |
| Prometheus monitoring | AKS add-on | Available |
| Docker Desktop / compatible runtime | Optional local | User-provided |
| Kind CLI | Local (auto-installed) | Bundled on demand |

---

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|---|---|---|---|
| First-deploy without Docker takes too long (5-10 min) | User abandonment | Medium | Kind fast path eliminates this for Docker users; engaging progress UI for others |
| Regional capacity exhaustion | Deploy failure | Medium | Pre-validation + automatic region failover; Kind users unaffected |
| Agent path fails for unsupported frameworks | Deploy failure | Medium | Fall back to "provide a Dockerfile" guidance; expand framework support over time |
| Ingress/routing complexity on AKS | URLs don't work | Low | Use web app routing add-on; fall back to LoadBalancer service type |
| Cost surprise from auto-provisioned clusters | User trust | Medium | v2: add cost estimation in deploy review step |
| Docker not available on user's machine | Can't use Kind fast path | Medium | Graceful fallback to AKS-only path with clear progress UI |
| Kind cluster left running after crash | Resource leak | Low | Stale cluster detection and cleanup on next app launch |
| Mode switching loses context | User confusion | Low | Both modes share the same data; no information is lost |

---

## Appendix: Implementation Architecture

### Smart Router Architecture

```
User clicks Deploy
↓
Cluster Router (environment detection)
├── Azure Resource Graph: tagged devmode clusters
├── Docker: daemon available?
└── Kind: cluster running?
↓
Path Selection
├── DIRECT_AKS → existing cluster, fast deploy
├── KIND_FAST → local deploy + background AKS provisioning
└── AKS_PROVISION → foreground AKS provisioning
```

### Component Reuse Map

| Shared Component | Standard Mode Usage | Developer Mode Usage |
|---|---|---|
| MetricsCard | Project overview | App dashboard Zone 2 |
| ScalingCard | Project overview | App dashboard Zone 2 |
| LogsTab | Project detail tab | App Logs tab (aggregated) |
| ScalingTab | Project detail tab | App Scaling tab |
| Azure CLI utilities | All Azure operations | Cluster/ACR provisioning |
| GitHub auth/API | Pipeline wizard | Deploy flow repo picker |
| Pipeline orchestration | Pipeline wizard | Agent path deploy |
| Manifest templates | Standard deploy | Both Kind and AKS deploy |

### Data Flow

```
Developer Mode UI
↓ picks repo
GitHub API (detect Dockerfile, fetch branches)
↓ user clicks Deploy
Smart Router (detect environment, select path)
↓
├── Kind Fast Path:
│ ├── docker build (local image)
│ ├── kind load (into local cluster)
│ ├── K8s API (apply NodePort manifests)
│ └── Background: az aks create (parallel AKS provisioning)
│
├── Direct AKS:
│ ├── az acr build (remote container build)
│ └── K8s API (apply Deployment + Service + Ingress)
│
└── AKS Provision:
├── az vm list-skus (capacity validation)
├── az group create + az aks create + az acr create
├── az acr build (remote container build)
└── K8s API (apply Deployment + Service + Ingress)
↓ app running
K8s API (deployment status) → Dashboard status
Prometheus → Dashboard metrics (AKS only)
K8s API (pod logs) → Dashboard live logs
GitHub Actions API → Dashboard deploy history
↓ promotion (Kind → AKS)
az acr build → K8s API (AKS manifests) → seamless switch
```

The issue identifies the /dev/deploy flow, Settings page, sidebar, and app dashboard as entry points, but names no files or tests. Start by mapping those entry points and the existing mode and deployment architecture. Done means the listed Developer Mode flows, automatic routing paths, dashboards, and acceptance criteria work end to end without exposing Kubernetes terminology.

Written by the indexing model from the issue text.