# azure-samples/semantic-kernel-advanced-usage architecture

> Architecture diagram of the GitHub repository azure-samples/semantic-kernel-advanced-usage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure-samples/semantic-kernel-advanced-usage
- Repository: https://github.com/azure-samples/semantic-kernel-advanced-usage

## Overview

##### Project type and purpose
- This is not a single application but a collection of self-contained “scenario” templates demonstrating advanced features of the Microsoft Semantic Kernel framework.
- Each folder under `templates/` is an independent example (e.g., Dapr orchestration, authentication context, Copilot Studio skill, natural-language-to-SQL, Opentelemetry, etc.).
- The README lists the scenarios and explains their goals: showcasing orchestration patterns, hosting (Dapr), state machines, telemetry, Copilot integration, MS Graph APIs, and custom multi-agent strategies.

##### File structure
- Root level: repository metadata (LICENSE, CONTRIBUTING, CI, linter configs).
- `templates/`: contains directories for each scenario, each with its own source (`src`), infra (Bicep templates), Dockerfiles, requirements, and README.
- Patterns per scenario:
- An `infra/` folder with Azure Bicep files provisioning resources (Cosmos DB, ACR, App Service, Actor hosting, OpenAI keys, UAMI).
- A `src/` folder with Python modules organized by feature (agents, chat, API, process steps, utilities).
- Dockerfiles and `.env.sample` for local/docker deployments.
- Some scenarios include external clients (Chainlit, Flask/Starlette server, Copilot/Teams Bot, front-end HTML, Jupyter notebooks).

##### README for additional insights
- High-level overview of SK capabilities demonstrated.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client / UX"
        direction TB
        Browser["Browser Client"]:::client
        Jupyter["Jupyter Notebook"]:::client
        SpeakerNB["Speaker Selection Notebook"]:::client
        NL_SQL_FE["NL-to-SQL Frontend"]:::client
    end

    subgraph "Front End" 
        direction TB
        ChainlitUI["Chainlit Chat UI"]:::frontend
        SQLServer["NL-to-SQL Server"]:::frontend
        GraphServer["Copilot-Agent MS Graph Server"]:::frontend
        StudioChainlit["Copilot Studio Chainlit UI"]:::frontend
    end

    subgraph "Semantic Kernel" 
        direction TB
        KernelCore["Semantic Kernel Core"]:::kernel
        ScenarioModules["Scenario Modules"]:::kernel
        ProcessEngine["State Machine Engine"]:::kernel
    end

    subgraph "Dapr & State" 
        direction TB
        DaprSidecar["Dapr Sidecar & Actor Runtime"]:::infra
        InMemoryState["InMemory State Store"]:::datastore
    end

    subgraph "External Cloud Services"
        direction TB
        OpenAI["OpenAI Service"]:::cloud
        CosmosDB["Cosmos DB"]:::datastore
        MSGraph["Microsoft Graph API"]:::cloud
        ACR["Azure Container Registry"]:::cloud
        AppService["Azure App Service"]:::cloud
    end

    subgraph "Infrastructure (IaC)"
        direction TB
        InfraAO["Advanced Orchestration Infra"]:::infra
        InfraGraph["Copilot-Agent MS Graph Infra"]:::infra
        InfraStudio["Copilot Studio Skill Infra"]:::infra
    end

    subgraph "Telemetry"
        direction TB
        OTELCollector["OpenTelemetry Collector & Examples"]:::telemetry
    end

    %% Connections
    Browser -->|"HTTP/WebSocket"| ChainlitUI
    Browser -->|HTTP| SQLServer
    Browser -->|HTTP| StudioChainlit
    Jupyter -->|Notebook| OTELCollector
    Jupyter -->|Notebook| SpeakerNB

    ChainlitUI -->|"calls"| KernelCore
    SQLServer -->|"calls"| ProcessEngine
    SQLServer -->|"calls"| KernelCore
    GraphServer -->|"calls"| KernelCore
    StudioChainlit -->|"calls"| KernelCore

    KernelCore -->|"loads skills in"| ScenarioModules
    KernelCore -->|"executes processes in"| ProcessEngine
    KernelCore -->|"publishes/invokes"| DaprSidecar
    DaprSidecar -->|"state access"| InMemoryState
    KernelCore -->|"LLM calls"| OpenAI
    KernelCore -->|"state read/write"| CosmosDB
    KernelCore -->|"Graph calls"| MSGraph

    InfraAO -->|deploys resources| CosmosDB
    InfraAO -->|deploys services| AppService
    InfraGraph -->|deploys| MSGraph
    InfraStudio -->|deploys| AppService
    InfraStudio -->|deploys| ACR

    KernelCore -. traces .-> OTELCollector
    ScenarioModules -. trace spans .-> OTELCollector
    ProcessEngine -. metrics .-> OTELCollector

    %% Click Events
    click KernelCore "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/advanced_orchestration_dapr/src/agents/sk_ext/basic_kernel.py"
    click ScenarioModules "https://github.com/azure-samples/semantic-kernel-advanced-usage/tree/main/templates/advanced_orchestration_dapr/src/agents/"
    click DaprSidecar "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/advanced_orchestration_dapr/dapr.yaml"
    click InMemoryState "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/advanced_orchestration_dapr/src/agents/.dapr/state_inmemory.yml"
    click ChainlitUI "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/advanced_orchestration_dapr/src/chat/chat.py"
    click SQLServer "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/natural_language_to_SQL/src/server.py"
    click GraphServer "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/copilot-agent-ms-graph/server.py"
    click StudioChainlit "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/copilot_studio/src/chat.py"
    click InfraAO "https://github.com/azure-samples/semantic-kernel-advanced-usage/tree/main/templates/advanced_orchestration_dapr/infra/"
    click InfraGraph "https://github.com/azure-samples/semantic-kernel-advanced-usage/tree/main/templates/copilot-agent-ms-graph/infra/"
    click InfraStudio "https://github.com/azure-samples/semantic-kernel-advanced-usage/tree/main/templates/copilot_studio_skill/infra/"
    click OTELCollector "https://github.com/azure-samples/semantic-kernel-advanced-usage/tree/main/templates/opentelemetry/"
    click SpeakerNB "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/speaker_selection_strategy/playground.ipynb"
    click NL_SQL_FE "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/natural_language_to_SQL/frontend/index.html"
    click GraphAgent "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/copilot-agent-ms-graph/src/graph_agent.py"
    click ProcessEngine "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/natural_language_to_SQL/src/process/sql_process.py"
    click StudioChainlit "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/copilot_studio_skill/src/api/adapter.py"
    click ScenarioModules "https://github.com/azure-samples/semantic-kernel-advanced-usage/tree/main/templates/authentication_context/src/telco/"
    click ScenarioModules "https://github.com/azure-samples/semantic-kernel-advanced-usage/tree/main/templates/speaker_selection_strategy/telco/"
    click GraphAgent "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/copilot-agent-ms-graph/src/graph_agent_plugin.py"
    click ProcessSteps "https://github.com/azure-samples/semantic-kernel-advanced-usage/tree/main/templates/natural_language_to_SQL/src/steps/"
    click CopilotSkillAPI "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/copilot_studio_skill/src/api/app.py"
    click SKConversation "https://github.com/azure-samples/semantic-kernel-advanced-usage/blob/main/templates/copilot_studio_skill/src/api/sk_conversation_agent.py"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#1E88E5,color:#1E88E5,stroke-width:1px;
    classDef frontend fill:#FCE4EC,stroke:#C2185B,color:#C2185B,stroke-width:1px;
    classDef kernel fill:#E8F5E9,stroke:#43A047,color:#43A047,stroke-width:1px;
    classDef infra fill:#FFF3E0,stroke:#FB8C00,color:#FB8C00,stroke-width:1px;
    classDef datastore fill:#EDE7F6,stroke:#5E35B1,color:#5E35B1,stroke-width:1px;
    classDef cloud fill:#FFE0B2,stroke:#FB8C00,color:#FB8C00,stroke-width:1px;
    classDef telemetry fill:#ECEFF1,stroke:#546E7A,color:#546E7A,stroke-width:1px;
```
