Advanced Services External Capability Framework

Add a new Advanced Services framework to SimpleChat that allows administrators to register and manage external container based microservices. These services will run independently from the primary Flask App Service and will be invoked securely using managed identity. This feature establishes the foundation for future advanced workloads without embedding heavy runtime dependencies in the main application.

This work item only delivers the framework and management plane. Individual advanced services will be delivered as separate features.

---

Goals

• Provide a standardized pattern for external container based services.
• Allow admins to configure external services through the Admin UI.
• Authenticate service to service calls using App Service managed identity.
• Store shared configuration in the existing Cosmos settings container.
• Provide a reusable FastAPI service template for future advanced services.
• Enable CI/CD for advanced service containers using existing ACR patterns.

---

Non Goals

• Implement any specific advanced service such as LaTeX, R, or real time processing.
• Introduce new infrastructure decisions beyond existing repo conventions.
• Add deep technology specific design choices where existing patterns can be reused.

---

High Level Architecture

[ SimpleChat Flask App ]
        |
 Managed Identity Token
        |
        v
[ Advanced Service Container ]
        |
   Shared Cosmos Settings

---

Proposed Implementation Plan

1. Advanced Services Service Template

Create folder:

application/advanced_services/_template/

Template contents:

• FastAPI application skeleton
• Shared Cosmos configuration helper
• Auth middleware for validating managed identity tokens
• Example environment file
• Dockerfile and requirements
• README with usage guidance

Purpose:
Provide a reusable starting point for future advanced service containers.

---

2. Shared Configuration Module

Add _template/config.py to:

• Connect to Cosmos DB using managed identity or key based on environment.
• Read primary app settings from settings container with id app_settings.
• Provide helpers for reading and writing per service settings.

---

3. Auth Middleware Module

Add _template/auth_middleware.py:

• Extract Bearer token from Authorization header.
• Validate JWT against Entra ID tenant and expected audience.
• Support managed identity and user delegated tokens.
• Expose FastAPI dependency for protected endpoints.

---

4. Template FastAPI App

Add _template/main.py:

• /health endpoint for probe and test connection.
• /api/v1/* protected routes using auth middleware.
• Example route reading shared settings.

---

5. CI/CD for Advanced Services

Add workflow:

.github/workflows/advanced_services_publish.yml

• Discover service folders under application/advanced_services/.
• Build and push each container to ACR.
• Follow existing image tagging and publishing conventions.

---

6. Admin UI Integration

Add new Admin tab:

• Label: Advanced Services
• Global enable toggle enable_advanced_services.
• Table of configured services.
• Add, edit, delete service configuration.
• Per service Test Connection button.
• Visible status message area.

Add setup guide modal:

• Template: application/single_app/templates/_advanced_services_info.html
• Provide high level setup guidance for container deployment and managed identity configuration.

---

7. Settings Schema

Extend functions_settings.py defaults:

• enable_advanced_services: False
• advanced_services: []

Store service definitions using existing settings persistence patterns.

---

8. Test Connection Handler

Extend routes_admin.py:

• New test handler type advanced_service.
• Acquire managed identity token.
• Call configured {service_endpoint}/health.
• Return success or error message to UI.
• Also test the

Plan: Advanced Services Feature with FastAPI External Containers

Build a framework for FastAPI-based microservices running in separate App Service containers. All services share Cosmos DB for configuration via the same settings container. The primary app authenticates to Advanced Services using managed identity, and each service validates tokens using a shared auth middleware module.

Steps

1. Create advanced services folder structure at application/advanced_services/ with:

   • _template/ containing: Dockerfile, main.py, requirements.txt, devcontainer.json, config.py, auth_middleware.py, example.env, and README.md.

2. Create shared config module in _template/config.py that:

   • Connects to Cosmos DB using same pattern as config.py (managed identity or key).
   • Reads from settings container with id='app_settings' to get primary app configuration.
   • Provides get_app_settings() and get_service_settings(service_name) / save_service_settings(service_name, data) helper functions.
   • Supports AZURE_ENVIRONMENT variable for public/usgovernment/custom clouds.

3. Create auth middleware module in _template/auth_middleware.py providing FastAPI dependency injection for token validation:

   • validate_token() dependency that extracts Bearer token from Authorization header.
   • Validates JWT signature against Azure AD/Entra ID using TENANT_ID and CLIENT_ID (primary app's client ID as the expected audience).
   • Supports both managed identity tokens and user-delegated tokens.
   • Returns decoded claims on success, raises HTTPException(401) on failure.
   • Includes helper require_app_role(role_name) for future role-based access control.

4. Create template FastAPI app in _template/main.py:

   • FastAPI app with /health endpoint (unprotected, for load balancer probes).
   • /api/v1/... protected routes using Depends(validate_token).
   • Example endpoint demonstrating reading from app_settings and service-specific settings.

5. Add GitHub Actions workflow at .github/workflows/advanced_services_publish.yml using matrix strategy to build each service folder under application/advanced_services/ (excluding _template), tagging as simple-chat-{service-name}:latest to the same ACR.

6. Add "Advanced Services" tab in admin_settings.html after existing tabs, containing: global enable_advanced_services toggle, dynamic service list table, Add/Edit/Delete modal, per-row Test Connection button with status badge.

7. Create setup guide modal at templates/_advanced_services_info.html documenting: architecture overview, container deployment, required environment variables, managed identity role assignments between apps, and how to create new services from template.

8. Extend settings schema in functions_settings.py adding enable_advanced_services: False and advanced_services: [] to default_settings.

9. Add test connection handler in routes_admin.py with test_type: 'advanced_service' that uses DefaultAzureCredential() to acquire token scoped to the Advanced Service's App URI and calls {endpoint}/health. Also test some api in the service to confirm it performs a task as expected to ensure the service is not just running but executes.

Template example.env Contents

# Cosmos DB (REQUIRED - same as primary app)
AZURE_COSMOS_ENDPOINT="<your-cosmosdb-account-uri>"
AZURE_COSMOS_AUTHENTICATION_TYPE="managed_identity"
AZURE_COSMOS_KEY=""  # Only if using key auth

# Azure Environment
AZURE_ENVIRONMENT="public"  # public, usgovernment, custom

# Auth - Primary App Identity (for token validation)
TENANT_ID="<your-azure-ad-tenant-id>"
PRIMARY_APP_CLIENT_ID="<simplechat-app-client-id>"  # Audience for incoming tokens

# Service Identity (this service's managed identity, if different)
ADVANCED_SERVICE_NAME="my_service_name"

Auth Middleware Pattern (auth_middleware.py)

# Validates tokens from primary SimpleChat app
# Uses TENANT_ID + PRIMARY_APP_CLIENT_ID as expected audience
# Supports AZURE_ENVIRONMENT for correct OIDC endpoint

async def validate_token(authorization: str = Header(...)) -> dict:
    # Extract Bearer token
    # Fetch OIDC config from Azure AD based on AZURE_ENVIRONMENT
    # Validate JWT signature, audience, issuer, expiry
    # Return decoded claims or raise HTTPException(401)

Shared Configuration Architecture

Component	Cosmos Document ID	Purpose
Primary App (SimpleChat)	app_settings	All admin-configured settings
Advanced Service X	Reads app_settings	Gets shared config (GPT endpoints, feature flags, etc.)
Advanced Service X	{service_name}_settings	Service-specific state/config if needed

Implementation Files Summary

Location	Purpose
application/advanced_services/_template/	Reusable FastAPI service template
application/advanced_services/_template/.devcontainer/	Per-service dev container config
application/advanced_services/_template/config.py	Cosmos DB connection + settings helpers
application/advanced_services/_template/auth_middleware.py	Token validation FastAPI dependency
application/advanced_services/_template/main.py	FastAPI app with health + protected routes
application/advanced_services/_template/example.env	Environment variable template
.github/workflows/advanced_services_publish.yml	CI/CD for all advanced services
admin_settings.html	New "Advanced Services" tab
application/single_app/templates/_advanced_services_info.html	Setup guide modal
functions_settings.py	Settings schema additions
application/single_app/routes_admin.py	Test connection API handler