# azure-ai-foundry/foundry-samples architecture

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

- Interactive diagram: https://gitdiagram.com/azure-ai-foundry/foundry-samples
- Repository: https://github.com/azure-ai-foundry/foundry-samples

## Overview

##### Project type and purpose
- This is an open-source documentation sample repository for Azure AI Foundry.
- It contains end-to-end examples, language-specific sample code (Python, Java, C#, JavaScript), infrastructure-as-code modules (Bicep), notebooks, and supporting test plugins.

##### High-level components in the file tree
- **.github/** – CI/CD workflows and helper scripts (pre-commit, PR checks, file-size diff summary).
- **.infra/** – Infrastructure-as-code modules (Bicep templates) and custom pytest plugins.
- **doc-samples/** – Language-specific “getting started” tutorials (Java, Python, .NET) and notebooks.
- **samples/** – A large catalog of prebuilt agent examples (3p-agent SDKs, MSFT-agent SDKs, Semantic Kernel SDK, VSCode extensions).
- **libs/** and **archive/** – Built wheel packages for distribution and historical artifacts.
- **dev-requirements.txt**, **tox.ini**, **pre-commit-config.yaml** – Developer toolchain and test configurations.
- **README.md**, **CONTRIBUTING.md**, **LICENSE**, **SECURITY.md** – Project documentation.

##### Key relationships and flows
- **Developer workflow**: clone repo → install dev requirements → run pre-commit hooks → run pytest with custom plugin → explore or run samples locally.
- **CI/CD (GitHub Actions)**: on PR/pre-commit → lint & format checks (pre-commit) → run tests (pytest + changed_samples plugin) → build wheel packages → validate Bicep deployments in infra folder.
- **Infra provisioning**: Bicep modules in **.infra/deployment/** and samples’ deploy.bicep scripts define Azure resources (AI projects, container registry, key vault, storage accounts, Function Apps, etc.).
- **Documentation**: markdown files and notebooks link to sample code.

##### Important architectural patterns and principles
- **Monorepo**: All sample code, infra, CI, and packaging coexist in one repository.
- **Modular infra**: Bicep modules encapsulate Azure resource concerns (storage, key vault, role assignments, AI workspace).
- **Language-agnostic samples**: Patterns repeated across languages for parity in documentation.
- **Plugin-driven testing**: A custom pytest plugin (`pytest_changed_samples`) to run only changed samples for faster feedback.
- **CI as code**: GitHub workflows guard code quality and packaging.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Local Development Environment
    subgraph "Local Development" 
        direction TB
        Dev["Developer Workstation"]:::process
        PreCommitConfig["pre-commit-config.yaml"]:::tooling
        DevReqs["dev-requirements.txt"]:::tooling
        ToxConfig["tox.ini"]:::tooling
        Conftest["conftest.py"]:::tooling

        Dev -->|"runs hooks/tests"| PreCommitConfig
        Dev -->|uses dev deps| DevReqs
        Dev -->|runs tests| ToxConfig
        Dev -->|pytest plugin| Conftest
    end

    %% Repository
    subgraph "GitHub Repository" 
        direction TB
        GHWorkflows[".github/workflows"]:::code
        PreCommitYML["pre-commit.yml"]:::code
        PRChecksYML["pull-request-checks.yml"]:::code
        GHScript["commit-filesize-diff-summary.py"]:::code
        InfraModules["Bicep Modules"]:::code
        SampleModules["Sample Code Modules"]:::code
        TestPlugin["pytest_changed_samples"]:::code
        DocSamples["Documentation Samples"]:::docs
        BuildArtifacts["libs & archive"]:::code

        GHWorkflows --> PreCommitYML
        GHWorkflows --> PRChecksYML
        .githubScripts[".github/scripts"]:::code --> GHScript
    end

    Dev -->|clone/pull| GHWorkflows
    Dev -->|explore docs| DocSamples

    %% CI/CD Pipeline
    subgraph "CI/CD (GitHub Actions)" 
        direction TB
        CI["GitHub Actions CI/CD"]:::process
        LintFmt["Lint & Format (pre-commit)"]:::process
        RunTests["Run Tests (pytest_changed_samples)"]:::process
        Build["Build Wheel Packages"]:::process
        DeployInfra["Deploy Bicep"]:::process

        CI -->|lint/test| LintFmt
        CI -->|run plugin| RunTests
        CI -->|build| Build
        CI -->|deploy| DeployInfra
    end

    GHWorkflows --> CI
    TestPlugin -->|executes| RunTests
    SampleModules -.->|tested by| RunTests
    Build --> BuildArtifacts
    DeployInfra --> InfraModules
    DeployInfra --> Cloud

    %% Azure Cloud
    subgraph "Azure Cloud" 
        direction TB
        Azure["Azure Resources"]:::external
        AzureProjects["AI Projects"]:::external
        ContainerReg["Container Registry"]:::external
        KeyVault["Key Vault"]:::external
        Storage["Storage Accounts"]:::external
        FunctionApps["Function Apps"]:::external

        Azure --> AzureProjects
        Azure --> ContainerReg
        Azure --> KeyVault
        Azure --> Storage
        Azure --> FunctionApps
    end

    DeployInfra -->|provisions| Azure
    Dev -->|run samples| Azure

    %% Documentation
    subgraph "Documentation" 
        direction TB
        README["README.md"]:::docs
        Contrib["CONTRIBUTING.md"]:::docs
        License["LICENSE"]:::docs
        Security["SECURITY.md"]:::docs
    end

    GHWorkflows --> README

    %% Click Events
    click GHWorkflows "https://github.com/azure-ai-foundry/foundry-samples/tree/main/.github/workflows"
    click PreCommitYML "https://github.com/azure-ai-foundry/foundry-samples/blob/main/.github/workflows/pre-commit.yml"
    click PRChecksYML "https://github.com/azure-ai-foundry/foundry-samples/blob/main/.github/workflows/pull-request-checks.yml"
    click GHScript "https://github.com/azure-ai-foundry/foundry-samples/blob/main/.github/scripts/commit-filesize-diff-summary.py"
    click PreCommitConfig "https://github.com/azure-ai-foundry/foundry-samples/blob/main/.pre-commit-config.yaml"
    click DevReqs "https://github.com/azure-ai-foundry/foundry-samples/blob/main/dev-requirements.txt"
    click ToxConfig "https://github.com/azure-ai-foundry/foundry-samples/blob/main/tox.ini"
    click Conftest "https://github.com/azure-ai-foundry/foundry-samples/blob/main/conftest.py"
    click InfraModules "https://github.com/azure-ai-foundry/foundry-samples/blob/main/.infra/deployment/main.bicep"
    click TestPlugin "https://github.com/azure-ai-foundry/foundry-samples/blob/main/.infra/pytest_plugins/changed_samples/src/pytest_changed_samples/plugin.py"
    click DocSamples "https://github.com/azure-ai-foundry/foundry-samples/blob/main/doc-samples/getting-started/java/README.md"
    click BuildArtifacts "https://github.com/azure-ai-foundry/foundry-samples/tree/main/libs"
    click README "https://github.com/azure-ai-foundry/foundry-samples/blob/main/README.md"
    click Contrib "https://github.com/azure-ai-foundry/foundry-samples/blob/main/CONTRIBUTING.md"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#005B96
    classDef process fill:#DFF2BF,stroke:#4F8A10
    classDef external fill:#FFE4B5,stroke:#FF8C00
    classDef docs fill:#F0F0F0,stroke:#AAAAAA,stroke-dasharray: 5 5
    classDef tooling fill:#E8D0FF,stroke:#660099
```
