Researched: 2026-03-27 Domain: Azure AI Services integration -- 7 independently configurable service modes Confidence: MEDIUM-HIGH

Phase 07 was previously completed with 4 plans covering Azure OpenAI LLM, config persistence (ServiceConfig model + Fernet encryption), connection testing, and frontend wiring. The expanded scope adds 4 NEW adapters/connectors (Azure Avatar real implementation, Content Understanding, OpenAI Realtime, Voice Live API) and a region-based capability detection system. The existing infrastructure (ServiceConfig DB model, encryption, CRUD API, frontend ServiceConfigCard) is solid and reusable -- the new work layers on top.

The critical architectural insight is that these 7 services have fundamentally different integration patterns: some are backend-only (OpenAI LLM, Content Understanding), some are primarily frontend (Avatar WebRTC, Realtime WebSocket), and some are hybrid (Voice Live combines backend token brokering with frontend WebSocket). The backend's role varies per service -- from full adapter (OpenAI LLM) to config-store-and-connection-tester (Avatar, Realtime). The region capability map must be a hardcoded lookup table (per user decision) since there is no single Azure API to query all service availability.

Primary recommendation: Extend the existing connection_tester.py and azure_config.py with real API calls for the 3 new services (Content Understanding, Realtime, Voice Live), add a region capability lookup module, and implement the missing azure_openai_realtime service name in SERVICE_DISPLAY_NAMES. Frontend changes are minimal -- the 7 service cards already exist, just add region availability hints.

<user_constraints>

• All 7 modes are independently configurable -- NOT a fallback chain
• Each service has its own enable/disable toggle, endpoint, API key, region
• A service being "unavailable" in a region shows informational status, NOT auto-switch
• Admin explicitly chooses which services to enable
• System does NOT silently switch providers -- if a configured service fails, it reports error
• Config persistence uses existing service_config DB table with Fernet encryption
• API design: PUT/POST test/GET endpoints (partially implemented)
• NEW: GET /api/v1/azure-config/region-capabilities/{region} endpoint
• Azure OpenAI adapter already exists and is working
• Azure Speech STT/TTS adapters already exist from Phase 06
• Azure Avatar adapter is stub (is_available=False) -- needs real implementation
• Azure Content Understanding adapter is NEW
• Azure OpenAI Realtime adapter is NEW
• Azure Voice Live API adapter is NEW with Agent mode + Model mode
• Dynamic adapter registration on config save and on startup

• Encryption key management approach (env var vs config)
• Exact error messages for connection test failures
• Retry/timeout strategy for Azure API calls
• Region capability API data source (hardcoded map vs live Azure API call)
• Azure AD token auth implementation details for Voice Live Agent mode

• Azure Database for PostgreSQL configuration from UI (deployment infrastructure, not AI service)
• Avatar WebRTC rendering in frontend (Phase 08)
• Per-session provider override (always use deployment-wide config for now)
• Live Azure Management API for region capability querying (start with hardcoded map) </user_constraints>

<phase_requirements>

The expanded scope does NOT require any new Python packages. Content Understanding uses plain REST (httpx), Realtime API uses the openai SDK, and Voice Live uses httpx for connection testing (frontend handles the actual WebSocket). Avatar connection testing uses httpx REST calls.

Installation: No new packages needed. The existing pyproject.toml dependencies cover everything.

This is the most important architectural decision for the planner:

Key insight: For services 4, 6, 7 the backend does NOT proxy the real-time stream. The backend stores config, tests connectivity, and provides tokens/credentials. The frontend connects directly to Azure. This means the "adapter" for these services is lighter -- it only needs is_available() and connection testing, not a full execute() method.

backend/app/
  services/
    agents/
      adapters/
        azure_openai.py          # EXISTS
        azure_content.py         # NEW: Content Understanding adapter
        azure_realtime.py        # NEW: Realtime config/availability adapter
        azure_voice_live.py      # NEW: Voice Live config/availability adapter
      avatar/
        azure.py                 # EXISTS (stub) -> UPDATE with real connection test
      stt/azure.py               # EXISTS
      tts/azure.py               # EXISTS
    connection_tester.py         # EXISTS -> UPDATE with real tests for all 7
    config_service.py            # EXISTS (no changes needed)
    voice_live_service.py        # EXISTS (token broker) -> UPDATE SUPPORTED_REGIONS
    region_capabilities.py       # NEW: hardcoded region -> services map
  api/
    azure_config.py              # EXISTS -> UPDATE: add region-capabilities endpoint, add azure_openai_realtime to SERVICE_DISPLAY_NAMES
  schemas/
    azure_config.py              # EXISTS -> UPDATE: add RegionCapabilitiesResponse schema

What: A simplified adapter that implements is_available() and holds config but does NOT implement full execute().

When to use: Avatar, Realtime, Voice Live -- services where the real-time interaction happens in the frontend.

Example:

# Source: Project convention from azure_openai.py pattern
class AzureRealtimeAdapter(BaseCoachingAdapter):
    """Azure OpenAI Realtime API config adapter.

    Backend stores config and tests connectivity.
    Frontend connects directly via WebSocket.
    """
    name = "azure_openai_realtime"

    def __init__(
        self,
        endpoint: str,
        api_key: str,
        deployment: str = "gpt-4o-realtime-preview",
    ) -> None:
        self._endpoint = endpoint
        self._api_key = api_key
        self._deployment = deployment

    async def execute(self, request: CoachRequest) -> AsyncIterator[CoachEvent]:
        """Not used -- frontend connects directly to Azure Realtime API."""
        yield CoachEvent(
            type=CoachEventType.ERROR,
            content="Realtime API is frontend-direct; use token broker endpoint",
        )
        yield CoachEvent(type=CoachEventType.DONE, content="")

    async def is_available(self) -> bool:
        return bool(self._endpoint and self._api_key and self._deployment)

What: A complete adapter with execute() that makes real API calls.

When to use: Content Understanding -- the backend needs to call the REST API, poll for results, and return structured data.

Example:

# Source: Azure Content Understanding REST API docs
class AzureContentUnderstandingAdapter(BaseCoachingAdapter):
    """Azure Content Understanding adapter for document/multimodal analysis."""
    name = "azure_content"

    def __init__(self, endpoint: str, api_key: str) -> None:
        self._endpoint = endpoint.rstrip("/")
        self._api_key = api_key

    async def execute(self, request: CoachRequest) -> AsyncIterator[CoachEvent]:
        """Analyze content using Azure Content Understanding REST API."""
        # POST {endpoint}/contentunderstanding/analyzers/{analyzer}:analyze?api-version=2025-11-01
        # Poll Operation-Location until status=Succeeded
        # Yield results as CoachEvent
        ...

    async def is_available(self) -> bool:
        return bool(self._endpoint and self._api_key)

What: A Python dict mapping region identifiers to sets of supported services. Sourced from official Azure docs, maintained manually.

When to use: For the region-capabilities endpoint.

Example:

# Source: https://learn.microsoft.com/en-us/azure/ai-services/speech-service/regions
REGION_CAPABILITIES: dict[str, set[str]] = {
    "eastus2": {
        "azure_openai", "azure_speech_stt", "azure_speech_tts",
        "azure_avatar", "azure_openai_realtime", "azure_voice_live",
        "azure_content",
    },
    "swedencentral": {
        "azure_openai", "azure_speech_stt", "azure_speech_tts",
        "azure_avatar", "azure_openai_realtime", "azure_voice_live",
        "azure_content",
    },
    "westeurope": {
        "azure_openai", "azure_speech_stt", "azure_speech_tts",
        "azure_avatar", "azure_voice_live", "azure_content",
    },
    # ... more regions
}

• Building a full execute() adapter for frontend-primary services: Avatar, Realtime, and Voice Live are frontend-direct. The backend should NOT try to proxy WebSocket or WebRTC streams.
• Making region capabilities a live Azure API call: The Azure Management REST API is complex, requires subscription-level auth, and has different endpoints per service. A hardcoded map (updated manually) is correct per user decision.
• Auto-fallback between services: The user explicitly decided NO fallback chain. Each service reports its own status independently.
• Merging azure_openai_realtime into azure_openai: These are completely different APIs (REST chat completion vs WebSocket real-time audio). They need separate config entries.

Key insight: The 3 new services (Content Understanding, Realtime, Voice Live) each have different API patterns but none require new Python packages. Content Understanding is REST (httpx), Realtime is an openai SDK feature, and Voice Live is a WebSocket the frontend connects to directly.

• Adapter: AzureOpenAIAdapter in backend/app/services/agents/adapters/azure_openai.py
• Connection test: test_azure_openai() makes a minimal chat completion call
• No changes needed

• Adapter: AzureSTTAdapter in backend/app/services/agents/stt/azure.py
• Connection test: test_azure_speech() lists available voices
• No changes needed

• Adapter: AzureTTSAdapter in backend/app/services/agents/tts/azure.py
• Connection test: Shares test_azure_speech() (same endpoint)
• No changes needed

• Current: Stub adapter with is_available()=False
• Regions: eastus2, northeurope, southcentralus, southeastasia, swedencentral, westeurope, westus2
• Real-time synthesis uses WebRTC (frontend, Phase 08 scope)
• Backend for THIS phase: store config, validate, test connectivity via REST
• Connection test: Hit the ICE token endpoint GET /cognitiveservices/avatar/relay/token/v1 with Ocp-Apim-Subscription-Key header
• Endpoint format: https://{region}.tts.speech.microsoft.com
• Confidence: HIGH (verified from official docs)

• API version: 2025-11-01 (GA)
• Endpoint: {foundry_endpoint}/contentunderstanding/analyzers/{analyzer-id}:analyze?api-version=2025-11-01
• Auth header: Ocp-Apim-Subscription-Key: {key}
• Pattern: Async -- POST returns 202 + Operation-Location, poll until status: "Succeeded"
• Prebuilt analyzers: prebuilt-invoice, prebuilt-imageSearch, prebuilt-audioSearch, prebuilt-videoSearch
• Requires a Microsoft Foundry Resource (not just a Speech resource)
• Supported file types: PDF, TIFF, DOCX, XLSX, PPTX, images, audio, video
• Connection test: List analyzers or attempt a lightweight analysis
• Regional availability: Runs on Foundry resource -- available wherever Foundry resources can be created (broad availability)
• Confidence: HIGH (verified from official docs updated 2026-03-27)

• Uses the openai SDK with WebSocket transport
• Endpoint format: wss://{resource}.openai.azure.com/openai/v1
• IMPORTANT: Uses /openai/v1 GA endpoint, NOT date-based api-version parameter
• Auth: api-key header or Microsoft Entra Bearer token
• Models: gpt-4o-realtime-preview (2024-12-17), gpt-realtime (2025-08-28), gpt-realtime-mini, gpt-realtime-1.5
• Token limits: 32K input, 4K output
• Features: VAD, session config, real-time audio streaming, transcription
• Connection test: Attempt WebSocket handshake or validate endpoint format + try REST model list
• The frontend connects directly; backend stores config and provides credentials
• Confidence: HIGH (verified from official docs)

• WebSocket endpoint: wss://{resource}.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01&model={model}
• Alternate endpoint (older): wss://{resource}.cognitiveservices.azure.com/voice-live/realtime?api-version=2025-10-01
• Auth: api-key query param or header, OR Microsoft Entra Bearer token with scope https://ai.azure.com/.default
• Agent mode: Add agent_id and project_id query params instead of model
• Model mode: Add model query param (e.g., gpt-realtime, gpt-4o, gpt-4.1)
• Supported models: gpt-realtime, gpt-realtime-mini, gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-5, phi4-mm-realtime
• Regions with Voice Live: Very broad -- eastus, eastus2, swedencentral, westeurope, westus, westus2, australiaeast, uksouth, francecentral, etc. (expanded significantly from earlier Phase 08 assumption of only eastus2/swedencentral)
• Agent support regions: australiaeast, brazilsouth, canadaeast, eastus, eastus2, francecentral, germanywestcentral, italynorth, japaneast, norwayeast, southafricanorth, southcentralus, southeastasia, swedencentral, switzerlandnorth, uksouth, westeurope, westus, westus2, westus3
• Avatar integration: Via avatar parameter in session.update with WebRTC (ICE servers)
• Features: noise suppression, echo cancellation, semantic VAD, filler word removal, viseme for avatar lip sync
• Connection test: HTTP probe to the endpoint (already partially implemented)
• Confidence: HIGH (verified from official docs updated 2026-03-16)

CRITICAL UPDATE: The existing SUPPORTED_REGIONS in voice_live_service.py is {"eastus2", "swedencentral"} which is now OUTDATED. Voice Live supports many more regions. This needs updating.

Based on official Azure documentation (verified 2026-03-27), here is the comprehensive region map:

eastus2, northeurope, southcentralus, southeastasia, swedencentral, westeurope, westus2

Almost all major regions support at least some Voice Live models. Key regions with full support including Agent mode: australiaeast, brazilsouth, canadaeast, eastus, eastus2, francecentral, germanywestcentral, italynorth, japaneast, norwayeast, southafricanorth, southcentralus, southeastasia, swedencentral, switzerlandnorth, uksouth, westeurope, westus, westus2, westus3

Available in 30+ regions. Nearly universal Azure coverage.

Available wherever Azure OpenAI is deployed. Check Azure OpenAI model availability docs.

Runs on Foundry resources. Available wherever Foundry resources exist (broad).

GPT Realtime models are available as global deployments (broad availability).

# Services that have LIMITED regional availability -- only these need region checks
AVATAR_REGIONS = {
    "eastus2", "northeurope", "southcentralus", "southeastasia",
    "swedencentral", "westeurope", "westus2",
}

# Voice Live has broad availability but Agent mode is more restricted
VOICE_LIVE_AGENT_REGIONS = {
    "australiaeast", "brazilsouth", "canadaeast", "eastus", "eastus2",
    "francecentral", "germanywestcentral", "italynorth", "japaneast",
    "norwayeast", "southafricanorth", "southcentralus", "southeastasia",
    "swedencentral", "switzerlandnorth", "uksouth", "westeurope",
    "westus", "westus2", "westus3",
}

# For services with universal availability, don't restrict by region
# azure_openai, azure_speech_stt, azure_speech_tts, azure_content,
# azure_openai_realtime: available in most regions -- no restriction needed

What goes wrong: The frontend has SERVICE_KEY_MAP with realtime: "azure_openai_realtime" but the backend SERVICE_DISPLAY_NAMES in azure_config.py does NOT include azure_openai_realtime -- only 6 services are listed. Why it happens: Phase 07 v1 was scoped to fewer services. How to avoid: Add "azure_openai_realtime": "Azure OpenAI Realtime" to SERVICE_DISPLAY_NAMES. Warning signs: Frontend save for Realtime card returns 400 "Unknown service".

What goes wrong: voice_live_service.py has SUPPORTED_REGIONS = {"eastus2", "swedencentral"} but the actual Voice Live API now supports 20+ regions. Why it happens: The original Phase 08 implementation was conservative. How to avoid: Update SUPPORTED_REGIONS from the official docs or refactor to use the new region_capabilities module. Warning signs: Users in valid regions get "Unsupported region" errors.

What goes wrong: Content Understanding won't work with a regular Cognitive Services key. Why it happens: Content Understanding is a Foundry Tool, requiring a Microsoft Foundry Resource. How to avoid: Document this in the config UI tooltip. Connection test should verify the resource type. Warning signs: 401/403 errors on Content Understanding endpoint with valid Speech/OpenAI keys.

What goes wrong: Connection test fails because it uses ?api-version=2024-xx-xx query param. Why it happens: Azure OpenAI standard API uses api-version, but Realtime GA uses /openai/v1 path. How to avoid: Realtime connection test must construct URL as wss://{endpoint}/openai/v1 or verify deployment via REST. Warning signs: 404 or upgrade-required errors on connection test.

What goes wrong: Agent mode requires agent_id + project_id instead of model param. May also need Azure AD token instead of API key. Why it happens: Agent service uses Foundry AI Agent framework with different auth requirements. How to avoid: ServiceConfig model_or_deployment field can encode mode with convention like "agent:{agent_id}:{project_id}" or frontend sends mode info in the config update. Warning signs: 401 errors when using API key with Agent mode, missing agent_id param.

What goes wrong: The ServiceConfig model only has: endpoint, api_key, model_or_deployment, region. Voice Live Agent mode needs additional fields: project_name, agent_id. Why it happens: The DB model was designed for simpler services. How to avoid: Either add nullable columns to ServiceConfig, or store agent config as JSON in a text field, or encode in model_or_deployment with a convention. Warning signs: Cannot save Agent mode configuration.

# Source: https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/quickstart/use-rest-api
async def test_azure_content_understanding(
    endpoint: str, api_key: str,
) -> tuple[bool, str]:
    """Test Content Understanding by listing prebuilt analyzers."""
    try:
        async with httpx.AsyncClient(timeout=10.0) as client:
            url = (
                f"{endpoint.rstrip('/')}/contentunderstanding"
                f"/analyzers?api-version=2025-11-01"
            )
            response = await client.get(
                url,
                headers={"Ocp-Apim-Subscription-Key": api_key},
            )
            if response.status_code == 200:
                return (True, "Connection successful")
            return (False, f"HTTP {response.status_code}: {response.text[:200]}")
    except Exception as e:
        return (False, f"Connection failed: {e!s}")

# Source: https://learn.microsoft.com/en-us/azure/ai-services/speech-service/text-to-speech-avatar/real-time-synthesis-avatar
async def test_azure_avatar_real(
    api_key: str, region: str,
) -> tuple[bool, str]:
    """Test Avatar by fetching ICE relay token."""
    try:
        async with httpx.AsyncClient(timeout=10.0) as client:
            url = (
                f"https://{region}.tts.speech.microsoft.com"
                f"/cognitiveservices/avatar/relay/token/v1"
            )
            response = await client.get(
                url,
                headers={"Ocp-Apim-Subscription-Key": api_key},
            )
            if response.status_code == 200:
                return (True, "Avatar service reachable (ICE token retrieved)")
            return (False, f"Avatar test failed: HTTP {response.status_code}")
    except Exception as e:
        return (False, f"Avatar connection failed: {e!s}")

# Source: https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/realtime-audio
async def test_azure_realtime(
    endpoint: str, api_key: str, deployment: str,
) -> tuple[bool, str]:
    """Test Realtime API by verifying deployment exists via REST."""
    try:
        base = endpoint.rstrip("/")
        async with httpx.AsyncClient(timeout=10.0) as client:
            url = f"{base}/openai/deployments/{deployment}?api-version=2024-06-01"
            response = await client.get(
                url,
                headers={"api-key": api_key},
            )
            if response.status_code == 200:
                return (True, "Realtime deployment found")
            elif response.status_code in (401, 403):
                return (False, f"Authentication failed: HTTP {response.status_code}")
            elif response.status_code == 404:
                return (False, f"Deployment '{deployment}' not found")
            return (False, f"HTTP {response.status_code}: {response.text[:200]}")
    except Exception as e:
        return (False, f"Connection failed: {e!s}")

# New endpoint in azure_config.py
from app.services.region_capabilities import get_region_capabilities

@router.get("/region-capabilities/{region}")
async def get_capabilities(
    region: str,
    _admin: User = Depends(require_role("admin")),
) -> dict:
    """Return which Azure AI services are available in the given region."""
    return get_region_capabilities(region)

# Convention: store agent config in model_or_deployment
# Model mode: just the model name like "gpt-realtime"
# Agent mode: "agent:{agent_id}:{project_name}"
def parse_voice_live_config(model_or_deployment: str) -> dict:
    if model_or_deployment.startswith("agent:"):
        parts = model_or_deployment.split(":", 2)
        return {
            "mode": "agent",
            "agent_id": parts[1],
            "project_name": parts[2] if len(parts) > 2 else "",
        }
    return {
        "mode": "model",
        "model": model_or_deployment or "gpt-4o-realtime-preview",
    }

Deprecated/outdated:

• SUPPORTED_REGIONS = {"eastus2", "swedencentral"} in voice_live_service.py -- needs expansion
• Date-based api-version for Realtime API -- GA uses /openai/v1 endpoint

1. ServiceConfig Extra Fields for Agent Mode

   • What we know: Voice Live Agent mode needs project_name and agent_id beyond what ServiceConfig stores
   • What's unclear: Best storage strategy -- add DB columns vs encode in existing field vs JSON blob
   • Recommendation: Use model_or_deployment field with convention encoding ("agent:{agent_id}:{project_name}" vs "gpt-realtime"). Avoids DB migration for a simple config difference. Frontend can render different form fields based on a radio button (Agent/Model mode).

2. Content Understanding Regional Availability

   • What we know: It is a Foundry Tool running on Foundry Resources
   • What's unclear: Exact region list for Content Understanding (docs don't enumerate specific regions)
   • Recommendation: Mark as available everywhere for now. If connection test fails, the error message will indicate the issue. Flag as LOW confidence in the region map.

3. Azure AD Token Auth for Voice Live Agent Mode

   • What we know: Agent mode recommends Microsoft Entra (Azure AD) auth with scope https://ai.azure.com/.default
   • What's unclear: Whether API key works for Agent mode or ONLY Entra tokens
   • Recommendation: Support API key first (simpler). Add Azure AD as a future enhancement. The connection test will reveal if API key works.

No external tools required beyond what is already installed. Phase 07 expanded scope adds backend Python code and minor frontend updates. All dependencies (openai, httpx, cryptography) are already in pyproject.toml.

• Async everywhere: All new adapter methods must be async def
• Conditional imports: Use try/except ImportError pattern inside constructors (matching azure_openai.py convention)
• Service layer holds logic: Connection testing logic in service, router only handles HTTP
• Pydantic v2: New schemas use model_config = ConfigDict(from_attributes=True)
• Alembic for schema changes: If adding columns to ServiceConfig, must use Alembic migration with batch operations for SQLite
• No raw SQL: Use SQLAlchemy ORM
• Route ordering: Static routes before parameterized (/region-capabilities/{region} before /{id})
• Create returns 201, Delete returns 204
• ruff check + format must pass
• Tests required: pytest with >=95% coverage per project convention
• Conventional commits: feat:, fix:, test:

• Azure Content Understanding Overview - GA service, Foundry Tool, REST API
• Azure Content Understanding REST API Quickstart - Endpoint patterns, auth header, API version 2025-11-01
• Azure Content Understanding Service Limits - File types, rate limits, analyzer limits
• Azure OpenAI Realtime API - WebSocket protocol, /openai/v1 GA endpoint, supported models
• Azure Voice Live API Overview - Model support, pricing tiers, regions
• Azure Voice Live API How-To - WebSocket endpoint, auth, session config, avatar integration
• Azure Speech Service Regions - Complete region tables for Avatar, Voice Live, STT, TTS
• Azure TTS Avatar Overview - Avatar capabilities, real-time synthesis
• Azure Real-time Avatar Synthesis - WebRTC setup, ICE servers, Speech SDK

• Existing codebase: backend/app/services/connection_tester.py, azure_config.py, voice_live_service.py - Current implementation patterns
• Existing codebase: frontend/src/pages/admin/azure-config.tsx - 7 service cards with SERVICE_KEY_MAP

Confidence breakdown:

• Standard stack: HIGH - no new packages, all verified in existing pyproject.toml
• Architecture (service classification): HIGH - verified each service's API pattern against official docs
• Region capabilities: MEDIUM - Avatar and Voice Live regions verified from official tables; Content Understanding availability unclear
• Connection test patterns: HIGH - verified endpoint URLs and auth headers from official docs
• Voice Live Agent mode: MEDIUM - docs confirm agent_id/project_id params but API key vs Entra auth unclear
• Pitfalls: HIGH - identified from analyzing existing code gaps vs official API requirements

Research date: 2026-03-27 Valid until: 2026-04-27 (Azure services evolve; region tables should be re-verified monthly)

Visual and interaction contract for the Azure AI Service Integration & Voice/Avatar phase. This phase is predominantly backend-focused (new adapters, connection testers, region capabilities). Frontend changes are surgical extensions to the existing Azure Config admin page: region availability hints per service, Agent/Model mode selector for Voice Live, updated region warnings, and real connection status display. No new pages are created. Generated by gsd-ui-researcher, verified by gsd-ui-checker.

Source: Phase 1 UI-SPEC (established design system); no changes for Phase 7.

Note: Phase 7 introduces no new UI primitive dependencies from Radix/shadcn. All frontend changes are extensions to existing components (azure-config.tsx, service-config-card.tsx) and minor additions to the admin i18n namespace. The only new UI construct is a region availability indicator and an Agent/Model radio toggle inside the Voice Live config card.

Declared values (inherited from Phase 1, multiples of 4):

Component Dimensions (not spacing tokens):

• Region availability hint bar height: 40px (5 * 8px) -- inline informational bar below region input field
• Service config card collapsed height: 72px (9 * 8px) -- icon (48px) + vertical padding, matching existing pattern
• Agent/Model mode radio group width: fills parent grid cell (col-span-2 within the existing 2-column grid)

Source: Phase 1 UI-SPEC spacing scale; existing service-config-card.tsx layout measurements

Font stack: 'Inter', 'Noto Sans SC', sans-serif

Phase 7 supplementary text -- inherited Tailwind utility classes (not part of the design system type scale):

Phase 7 uses text-xs (12px) and text-sm (14px) from Tailwind's default utility classes for supplementary and secondary text within config cards. These are NOT additions to the Phase 7 type scale -- they are pre-existing framework defaults applied to lower-emphasis elements:

• text-xs (12px, weight 500): Region availability tag badges (uppercase), config card masked key hint (already exists)
• text-sm (14px, weight 400): Region availability hint text (text-muted-foreground), service status text (color per status)
• text-sm (14px, weight 500): Agent/Model mode radio labels

Sizes declared (3 total, unchanged): 16px, 18px, 24px Weights declared (2 total, unchanged): 400 (normal), 500 (medium)

Source: Phase 1 UI-SPEC typography; existing service-config-card.tsx and azure-config.tsx patterns

Inherited from Phase 1 reserved list, plus:

1. Save Configuration button (bg-primary)
2. Active service status dot (bg-green-500) -- note: this uses green, not accent blue
3. Region "Available" badge text
4. Agent/Model mode active radio indicator

NOT used for: region availability hint background (use orange/purple/gray semantic colors), config card borders (use --border), test connection button (use variant="outline").

Source: Phase 1 UI-SPEC color contract; existing service-config-card.tsx STATUS_DOT pattern; CONTEXT.md region availability design direction

Primary visual anchor: The expanded service config card with its colored status dot (green/red/purple) and region availability badge draws the eye first; the status dot and badge provide immediate at-a-glance service health.

Secondary visual anchor: The page heading ("Azure Service Configuration") paired with the "Test All Connections" button in the top-right corner, establishing the page context and primary bulk action.

Phase 7 does not create new pages. All UI changes occur within the existing azure-config.tsx page and service-config-card.tsx component.

+-------------------------------------------------------------------+
| Azure Service Configuration (h1)           [Test All Connections]  |
+-------------------------------------------------------------------+
| max-w-4xl, space-y-4                                               |
|                                                                    |
| +--------------------------------------------------------------+  |
| | [icon] Azure OpenAI           (green dot) Active      [^/v]  |  |
| |        GPT-4o for AI coaching...                              |  |
| |        [Available in eastus2] (green badge)                   |  |
| | (expanded: endpoint, apiKey, model, region fields + buttons)  |  |
| +--------------------------------------------------------------+  |
|                                                                    |
| +--------------------------------------------------------------+  |
| | [icon] Azure Speech (STT)     (gray dot) Inactive    [^/v]   |  |
| |        Speech-to-text for voice input...                      |  |
| |        [Available in eastus2] (green badge)                   |  |
| +--------------------------------------------------------------+  |
|                                                                    |
| +--------------------------------------------------------------+  |
| | [icon] Azure Speech (TTS)     (gray dot) Inactive    [^/v]   |  |
| |        Text-to-speech for HCP voice...                        |  |
| |        [Available in eastus2] (green badge)                   |  |
| +--------------------------------------------------------------+  |
|                                                                    |
| +--------------------------------------------------------------+  |
| | [icon] Azure AI Avatar        (purple dot) Unavailable [^/v] |  |
| |        Digital human avatar for HCP...                        |  |
| |        [Not available in westus] (purple badge)               |  |
| +--------------------------------------------------------------+  |
|                                                                    |
| +--------------------------------------------------------------+  |
| | [icon] Azure Content Understanding  (gray dot) Inactive[^/v] |  |
| |        Multimodal evaluation for training...                  |  |
| |        [Available] (green badge)                              |  |
| +--------------------------------------------------------------+  |
|                                                                    |
| +--------------------------------------------------------------+  |
| | [icon] Azure OpenAI Realtime  (gray dot) Inactive    [^/v]   |  |
| |        Real-time audio streaming...                           |  |
| |        [Available] (green badge)                              |  |
| +--------------------------------------------------------------+  |
|                                                                    |
| +--------------------------------------------------------------+  |
| | [icon] Azure Voice Live API   (green dot) Active     [^/v]   |  |
| |        Real-time voice coaching with GPT-4o Realtime          |  |
| |        [Available in eastus2] (green badge)                   |  |
| | (expanded: endpoint, apiKey, region fields                    |  |
| |  + Agent/Model mode radio                                    |  |
| |  + model field (Model mode) OR agent_id + project fields     |  |
| |  + Save + Test Connection buttons)                            |  |
| +--------------------------------------------------------------+  |
|                                                                    |
| +--------------------------------------------------------------+  |
| | [icon] Azure Database         (gray dot) Inactive    [^/v]   |  |
| |        Managed PostgreSQL for production data                 |  |
| +--------------------------------------------------------------+  |
+-------------------------------------------------------------------+

Added below the service description line, before the expand/collapse chevron area:

+--------------------------------------------------------------+
| [48px icon bg] Service Name       (status dot) Status  [^/v] |
|                Service description text                       |
|                [Region Badge] Available in eastus2            |
+--------------------------------------------------------------+

The region badge appears ONLY when:

1. A region is configured in the saved config for this service, AND
2. Region capability data has been fetched

Badge variants:

• Green: [check-icon] Available in {region} -- text-green-700 bg-green-50 border border-green-200
• Purple: [x-icon] Not available in {region} -- text-purple-700 bg-purple-50 border border-purple-200
• Gray: [info-icon] Region availability unknown -- text-gray-600 bg-gray-50 border border-gray-200

When the Voice Live card is expanded, display a radio group ABOVE the standard form fields:

+--------------------------------------------------------------+
| Voice Live API Mode                                           |
|                                                               |
| (o) Model Mode  -- Direct Azure OpenAI model connection      |
| ( ) Agent Mode  -- Azure AI Agent Service with pre-configured |
|                    HCP persona agent                          |
+--------------------------------------------------------------+
| (standard 2-col grid: endpoint, apiKey, region)               |
|                                                               |
| Model Mode fields:                                            |
| [Model/Deployment: gpt-realtime   ] [Region: eastus2       ] |
|                                                               |
| -- OR (if Agent Mode selected) --                             |
|                                                               |
| Agent Mode fields:                                            |
| [Agent ID: ____________          ] [Project Name: _________ ] |
+--------------------------------------------------------------+
| [Save Configuration]  [Test Connection]                       |
+--------------------------------------------------------------+

The radio group toggles which additional fields are shown:

• Model mode (default): Standard model_or_deployment + region fields
• Agent mode: agent_id + project_name fields (stored encoded in model_or_deployment as agent:{agent_id}:{project_name})

No changes to responsive behavior. The existing Azure Config page is within the admin layout which handles responsive breakpoints. The config cards stack vertically at all breakpoints. The 2-column form grid within expanded cards collapses to single column below 640px (existing behavior).

Source: CONTEXT.md decisions (7 equal modes, region availability hints); RESEARCH.md architecture patterns (service classification, Voice Live Agent/Model modes); existing azure-config.tsx and service-config-card.tsx implementation

All copy delivered via react-i18next admin namespace (extend existing). English canonical copy below.

Source: CONTEXT.md decisions (7 equal modes, region availability); RESEARCH.md (region capability map, connection test patterns, Agent/Model mode); existing admin.json i18n structure

Phase 7 does NOT create new component files. All changes are modifications to existing components.

Existing "Test All Connections" button behavior is unchanged. Tests are run sequentially for all services that have an endpoint configured. Each result shows a toast. Services unavailable in the configured region still attempt the connection test -- unavailability is informational, not blocking.

Inherited from Phase 1, plus Phase 7 additions:

Note: Phase 7 makes no additions to the UI component library. All changes are extensions to existing admin page components using existing primitives (Card, Input, Label, Button, Badge). No new Radix primitives or shadcn/ui base components are required.

All admin config copy uses useTranslation("admin"). Voice error copy update uses useTranslation("voice").

Phase 7 does NOT implement dark mode. Dark tokens are preserved in CSS. Region availability badges use semantic color classes (bg-green-50, bg-purple-50, bg-orange-50) that have no dark mode variants defined. If dark mode is added later, these badges will need dark-aware color tokens.

• Dimension 1 Copywriting: PASS
• Dimension 2 Visuals: PASS
• Dimension 3 Color: PASS
• Dimension 4 Typography: PASS
• Dimension 5 Spacing: PASS
• Dimension 6 Registry Safety: PASS

Approval: pending

Phase Goal: Full Azure AI service integration -- all 7 service modes (OpenAI, Speech STT, Speech TTS, Avatar, Content Understanding, OpenAI Realtime, Voice Live) configurable, testable, and registered. Backend adapters, connection testers, region capabilities, frontend config UI with region badges and Voice Live Agent/Model mode toggle. Verified: 2026-03-27T15:00:00Z Status: PASSED Re-verification: Yes -- previous verification covered plans 01-04 only (6/6 truths). Plans 05-07 executed after that verification, adding 7 new truths for a total of 13.

Score: 13/13 truths verified

No blockers or warnings found.

Test: Log in as admin, navigate to Azure Config, configure at least one service with a region (e.g., "eastus2"), expand other service cards. Expected: Green check badge ("Available in eastus2") on OpenAI, Speech, Avatar. Purple X badge on services not available in region. Gray info badge if API call fails. Why human: Requires running frontend+backend, visual confirmation of badge colors, icons, and text.

Test: Expand Voice Live card, select Agent mode, fill agent_id and project_name, click Save. Then select Model mode and save again. Expected: Agent mode saves JSON {"mode":"agent","agent_id":"...","project_name":"..."} in model_or_deployment. Model mode saves plain string. Validation prevents saving Agent mode with empty fields. Why human: Requires running services and verifying saved payload format.

Test: Enter real Azure credentials for each service, click Test Connection. Expected: OpenAI: chat completion test. Speech: voice list. Avatar: ICE relay token. Content Understanding: list analyzers. Realtime: verify deployment. Voice Live: endpoint probe. Each shows success/failure status with specific message. Why human: Requires real Azure credentials and network connectivity.

Test: Configure all 7 services, stop backend, restart, verify configs load from DB. Expected: All configs persist. Adapters re-register on startup. No manual reconfiguration needed. Why human: Requires server lifecycle management and manual observation.

No gaps found. All 13 observable truths verified through code inspection and automated testing:

1. Plans 01-04 (previously verified): ServiceConfig model, encryption, config service, Azure OpenAI adapter, API CRUD, connection testing, dynamic provider switching, frontend config page -- all re-confirmed with 41 original tests passing.

2. Plan 05 (new adapters): Content Understanding adapter with bounded polling (30 attempts, 2s), Realtime and Voice Live as config-only frontend-direct services, region capabilities module with 7 services across 20+ regions -- 4 new files, verified substantive and passing ruff check.

3. Plan 06 (wiring): Connection tester upgraded to real API calls for all 7 services, SSRF prevention via AZURE_HOST_PATTERN, region-capabilities endpoint, azure_openai_realtime accepted by PUT, SUPPORTED_REGIONS expanded to 20+, new adapters register on startup and save -- 50 new tests pass.

4. Plan 07 (frontend UX): Region badges with accessible icon+text (Check/X/Info), Voice Live Agent/Model radio toggle with JSON encoding and field validation, purple unavailable status dot, hardcoded region warning removed, all text externalized in en-US and zh-CN i18n -- TypeScript compiles, all UI patterns verified in code.

Note on build: npm run build fails due to unresolved rt-client import in use-voice-live.ts, which was introduced by Phase 08 commit (744b449), not Phase 07. TypeScript compilation (tsc --noEmit) passes cleanly.

Verified: 2026-03-27T15:00:00Z Verifier: Claude (gsd-verifier)