# azure-samples/azure-devops-copilot-extension architecture

> Architecture diagram of the GitHub repository azure-samples/azure-devops-copilot-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure-samples/azure-devops-copilot-extension
- Repository: https://github.com/azure-samples/azure-devops-copilot-extension

## Overview

##### Project Type and Purpose
– Azure DevOps Co-Pilot is a full-stack proof-of-concept extension for Azure DevOps that leverages Azure OpenAI + Semantic Kernel.
– It comprises three layers:
- A TypeScript/React Azure DevOps extension (the “frontend”)
- A .NET Core Web API backend that orchestrates Semantic Kernel and OpenAI calls
- An Azure infrastructure layer (Bicep/ARM) that hosts and secures the services

##### High-Level Components
a. Azure DevOps Extension (azdo folder)
- UI Components (React/TSX) – dialogs for user stories, test cases, configuration
- Services (CopilotService.ts, ConfigurationService.ts) – wrap calls to the backend via REST
- Azure DevOps SDK client (azure-devops-extension-api)

b. API Backend (api/src & api/Mapache.PromptEvalDotNet)
- Controllers – AzDoController, TestCaseController, UserStoryController
- Middleware – API key validation, exception filters
- Prompt evaluation libraries (Mapache.PromptEvalDotNet) – implement Coherence, Relevance, Groundedness evaluators using Semantic Kernel
- Azure OpenAI / Semantic Kernel integration

c. Azure Infrastructure (infra folder)
- Bicep modules for Container Apps, Managed Environments, RBAC locks, Resource Groups
- CI/CD definitions (GitHub Actions workflows, azure-deploy.json)

d. External Services
- Azure OpenAI / Semantic Kernel
- Azure DevOps REST API
- Azure Container Apps / Managed Environment

##### Relationships and Data Flows
– User interacts with the Azure DevOps UI extension → extension calls backend via HTTPS (CopilotService)
– Backend Controller receives HTTP request → Middleware authenticates (ApiKeyValidator)
– Controller invokes PromptEvaluatorFactory / Semantic Kernel → issues prompts to Azure OpenAI
– Results returned to Controller → JSON response sent back to extension
– Extension updates Azure DevOps work items via Azure DevOps SDK calls

##### Architectural Patterns & Design Principles
– Clear separation of concerns: Extension UI vs Backend API vs Infra-as-Code
– Modular prompt evaluators (factory pattern) to add new AI evaluation metrics
– Middleware pipeline in ASP.NET Core for authentication and exception handling
– IaC idempotency via Bicep modules and nested role assignments

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Azure DevOps Extension"
    direction TB
    UI["UI Components\n(React/TSX)"]:::frontend
    CopService["CopilotService.ts"]:::frontend
    ConfigService["ConfigurationService.ts"]:::frontend
    SDK["Azure DevOps SDK"]:::frontend
  end

  subgraph "API Backend"
    direction TB
    subgraph Controllers
      direction TB
      AzDoCtrl["AzDoController"]:::backend
      TestCaseCtrl["TestCaseController"]:::backend
      UserStoryCtrl["UserStoryController"]:::backend
    end
    subgraph Middleware
      ApiKeyVal["ApiKeyValidator"]:::backend
      ExFilter["GlobalExceptionFilter"]:::backend
    end
    subgraph "Prompt Eval Library"
      Coherence["CoherenceEvaluator"]:::backend
      Grounded["GroundednessEvaluator"]:::backend
      Relevance["RelevanceEvaluator"]:::backend
      PEFactory["PromptEvaluatorFactory"]:::backend
    end
    subgraph "Semantic Kernel Integration"
      IPFactory["IPromptsFactory"]:::backend
      SKFactory["PrompsFactory"]:::backend
      UserSkill["UserStorySkill"]:::backend
      SK["Azure OpenAI / Semantic Kernel"]:::external
    end
  end

  subgraph Infra
    direction TB
    GHActions["GitHub Actions"]:::infra
    BicepRoot["main.bicep\napi.bicep\nopenai.bicep\nlogworkspace.bicep"]:::infra
    AzureDeploy["azure-deploy.json"]:::infra
    subgraph Modules
      direction TB
      ContAppMod["container-app"]:::infra
      ManagedEnv["managed-environment"]:::infra
      RBAC["RBAC Locks"]:::infra
      RG["Resource Groups"]:::infra
    end
    ContainerApp["Azure Container App"]:::infra
    AzureAD["Azure AD"]:::infra
  end

  subgraph External
    direction TB
    AZDO["Azure DevOps Services"]:::external
    OpenAI["Azure OpenAI"]:::external
  end

  UI -->|uses| CopService
  UI -->|uses| ConfigService
  CopService -->|HTTPS| AzDoCtrl
  ConfigService -->|HTTPS| AzDoCtrl
  SDK -->|SDK REST| AZDO
  AzDoCtrl -->|pipeline| ApiKeyVal
  ApiKeyVal -->|pipeline| ExFilter
  ExFilter -->|calls| PEFactory
  PEFactory -->|"uses"| Coherence
  PEFactory -->|"uses"| Grounded
  PEFactory -->|"uses"| Relevance
  PEFactory -->|"factory"| IPFactory
  IPFactory -->|creates| SKFactory
  SKFactory -->|invokes| UserSkill
  UserSkill -->|calls| SK
  SK -->|responds| UserSkill
  UserSkill -->|returns| PEFactory
  PEFactory -->|returns| AzDoCtrl
  AzDoCtrl -->|JSON| CopService
  CopService -->|updates| SDK
  SDK -->|REST SDK| AZDO

  GHActions -.->|deploy| BicepRoot
  BicepRoot -->|module| ContAppMod
  BicepRoot -->|module| ManagedEnv
  BicepRoot -->|module| RBAC
  BicepRoot -->|module| RG
  ContAppMod -->|provisions| ContainerApp
  ManagedEnv -->|configures| ContainerApp
  RBAC -->|applies| AzureAD
  ContainerApp -->|hosts| AzDoCtrl

  click UI "https://github.com/azure-samples/azure-devops-copilot-extension/tree/main/azdo/src/Components/"
  click CopService "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/azdo/src/Services/CopilotService.ts"
  click ConfigService "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/azdo/src/Services/ConfigurationService.ts"
  click AzDoCtrl "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/src/Controllers/AzDoController.cs"
  click TestCaseCtrl "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/src/Controllers/TestCaseController.cs"
  click UserStoryCtrl "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/src/Controllers/UserStoryController.cs"
  click ApiKeyVal "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/src/Middleware/ApiKeyValidator.cs"
  click ExFilter "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/src/Filters/GlobalExceptionFilter.cs"
  click IPFactory "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/src/SK/IPromptsFactory.cs"
  click SKFactory "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/src/SK/PrompsFactory.cs"
  click UserSkill "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/src/SK/UserStorySkill.cs"
  click Coherence "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/Mapache.PromptEvalDotNet/CoherenceEvaluator.cs"
  click Grounded "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/Mapache.PromptEvalDotNet/GroundednessEvaluator.cs"
  click Relevance "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/Mapache.PromptEvalDotNet/RelevanceEvaluator.cs"
  click PEFactory "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/api/Mapache.PromptEvalDotNet/PromptEvaluatorFactory.cs"
  click BicepRoot "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/infra/main.bicep"
  click ContAppMod "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/infra/modules/carml/app/container-app/main.bicep"
  click AzureDeploy "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/infra/azure-deploy.json"
  click GHActions "https://github.com/azure-samples/azure-devops-copilot-extension/blob/main/.github/workflows/bicep-to-arm.yaml"

  classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
  classDef backend fill:#d4edda,stroke:#155724,color:#155724
  classDef infra fill:#fff3cd,stroke:#856404,color:#856404
  classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
  classDef hidden fill:none,stroke:none,color:none
```
