# googlecloudplatform/dotnet-docs-samples architecture

> Architecture diagram of the GitHub repository googlecloudplatform/dotnet-docs-samples, 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/googlecloudplatform/dotnet-docs-samples
- Repository: https://github.com/googlecloudplatform/dotnet-docs-samples

## Overview

##### Project type and purpose
- This repo is a **collection of C# sample applications and tests** for many Google Cloud services.
- It is organized as a **monorepo** of independent .NET solutions (.sln), each demonstrating a different API (e.g., BigQuery, Pub/Sub, Cloud Storage), plus shared build/test infrastructure.

##### Top-level components
- **GitHub Repository** (source code host)
- **CI/CD Orchestration**
- Kokoro scripts under `.kokoro/` and `.kokoro-windows/`
- buildAndRunTests.ps1, GitHub actions settings, Renovate config, Blunderbuss bot
- **Common Build Files**
- `Directory.Build.props`, `BuildTools.psm1`
- `testutil/` library for reusable test helpers
- **Service-Specific Folders**
Each folder named after a Google Cloud product (e.g., `bigquery/`, `pubsub/`, `storage/`, …) contains:
- Sub-folders `api/` or `appengine/` with a solution file (.sln)
- C# sample projects (`*.csproj`) and corresponding `Samples` code
- `*Tests` projects containing NUnit/xUnit tests
- `runTests.ps1`: per-folder test harness
- `README.md`: usage instructions

##### Developer workflow
- **Local Developer Machine**
- Clone GitHub repo
- Open a specific `.sln` in Visual Studio 2017+ or VS Code
- Restore NuGet packages, build projects
- Run `runTests.ps1` or use Test Explorer to execute tests
- **CI Pipeline**
- Commit triggers Kokoro or GitHub Actions
- Scripts iterate service folders, invoke `build-local-docker.ps1` or Dockerfiles to build containers
- Run `runTests.ps1` in each folder under Linux/Windows environments
- Collect and publish test results

##### Important patterns & principles
- **Monorepo with modular solutions**: each API’s samples are self-contained under its own folder.
- **Separation of concerns**: samples vs. tests vs. CI config vs. shared tooling.
- **Convention-over-configuration**: uniform structure (`api/`, `Samples`, `*.Tests`, `runTests.ps1`) across modules.
- **Cross-platform CI**: Windows (PowerShell) and Linux (bash) paths scripted under `.kokoro` and Dockerfiles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    Dev["Local Developer Machine"]:::dev
    Dev -->|"push"| GitHub
    Dev -->|"run build"| BuildPS

    %% GitHub Repo
    GitHub["GitHub Repository"]:::code
    click GitHub "https://github.com/googlecloudplatform/dotnet-docs-samples/tree/main//"

    %% CI Systems
    subgraph "CI/CD Orchestration" 
        KokoroL["Kokoro CI (Linux)"]:::ci
        click KokoroL "https://github.com/googlecloudplatform/dotnet-docs-samples/tree/main//.kokoro/"
        KokoroW["Kokoro CI (Windows)"]:::ci
        click KokoroW "https://github.com/googlecloudplatform/dotnet-docs-samples/tree/main//.kokoro-windows/"
        GHAction["GitHub Actions & Bots"]:::ci
        click GHAction "https://github.com/googlecloudplatform/dotnet-docs-samples/tree/main//.github/"
    end
    GitHub -->|trigger| KokoroL
    GitHub -->|trigger| KokoroW
    GitHub -->|trigger| GHAction

    %% CI Helpers
    DockerPS["build-local-docker.ps1"]:::script
    click DockerPS "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//.kokoro/build-local-docker.ps1"
    Dockerfile["Dockerfile"]:::script
    click Dockerfile "https://github.com/googlecloudplatform/dotnet-docs-samples/tree/main//.kokoro/docker/Dockerfile"
    KokoroL --> DockerPS
    KokoroL --> Dockerfile

    %% Common Build Layer
    subgraph "Common Build & Test Infrastructure"
        Props["Directory.Build.props"]:::script
        click Props "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//Directory.Build.props"
        Tools["BuildTools.psm1"]:::script
        click Tools "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//BuildTools.psm1"
        TestUtil["testutil/"]:::code
        click TestUtil "https://github.com/googlecloudplatform/dotnet-docs-samples/tree/main//testutil/"
        SkipTestsPS["skipTests.ps1"]:::script
        click SkipTestsPS "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//powershell/skipTests.ps1"
        BuildPS["buildAndRunTests.ps1"]:::script
        click BuildPS "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//buildAndRunTests.ps1"
    end
    KokoroL -->|uses| Props
    KokoroL -->|uses| Tools
    KokoroL -->|uses| TestUtil
    KokoroW -->|uses| Props
    KokoroW -->|uses| Tools
    GHAction -->|uses| Props
    GHAction -->|uses| Tools
    Dev -->|use| Props
    Dev -->|use| Tools

    %% Sample Modules
    subgraph "Sample Modules"
        subgraph "BigQuery API Module" 
            BQSLN["BigQuery.sln"]:::code
            click BQSLN "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//bigquery/api/BigQuery.sln"
            BQSnippets["Snippets/*.csproj & *.cs"]:::code
            BQRun["runTests.ps1"]:::script
            click BQRun "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//bigquery/api/runTests.ps1"
        end
        subgraph "Pub/Sub API Module"
            PSsln["Pubsub.sln"]:::code
            click PSsln "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//pubsub/api/Pubsub.sln"
            PSSamples["Pubsub.Samples/*.csproj & *.cs"]:::code
            PSTests["Pubsub.Samples.Tests/*.csproj"]:::code
            PSTestRun["runTest.ps1"]:::script
            click PSTestRun "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//pubsub/api/runTest.ps1"
        end
        subgraph "Cloud Storage API Module"
            CSSln["Storage.sln"]:::code
            click CSSln "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//storage/api/Storage.sln"
            CSSamples["Storage.Samples/*.csproj & *.cs"]:::code
            CSTests["Storage.Samples.Tests/*.csproj"]:::code
            CSTestRun["runTests.ps1"]:::script
            click CSTestRun "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//storage/api/runTests.ps1"
        end
        subgraph "AI Platform API Module"
            AISln["AIPlatform.sln"]:::code
            click AISln "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//aiplatform/api/AIPlatform.sln"
            AISamples["AIPlatform.Samples/*.csproj & *.cs"]:::code
            AITests["AIPlatform.Samples.Tests.csproj"]:::code
            AITestRun["runTests.ps1"]:::script
            click AITestRun "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//aiplatform/api/runTests.ps1"
        end
        subgraph "AppEngine Flexible Module"
            AEFsln["CloudStorage.sln"]:::code
            click AEFsln "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//appengine/flexible/CloudStorage/CloudStorage.sln"
            AEFSamples["CloudStorage.Sample/*.csproj & *.cs"]:::code
            AEFTests["CloudStorage.Tests/*.csproj"]:::code
            AEFTestRun["runTests.ps1"]:::script
            click AEFTestRun "https://github.com/googlecloudplatform/dotnet-docs-samples/blob/main//appengine/flexible/CloudStorage/runTests.ps1"
        end
    end

    %% Build & Test Flow
    Props -->|configures| BQSLN
    Tools -->|scripts| BQRun
    TestUtil -->|helpers| BQRun
    BuildPS -->|invokes| BQRun

    Props --> CSSln
    Tools --> CSTestRun
    TestUtil --> CSTestRun
    BuildPS --> CSTestRun

    Props --> PSsln
    Tools --> PSTestRun
    TestUtil --> PSTestRun
    BuildPS --> PSTestRun

    Props --> AISln
    Tools --> AITestRun
    TestUtil --> AITestRun
    BuildPS --> AITestRun

    Props --> AEFsln
    Tools --> AEFTestRun
    TestUtil --> AEFTestRun
    BuildPS --> AEFTestRun

    %% Test Results Feedback
    BQRun -->|results| KokoroL
    CSTestRun -->|results| KokoroL
    PSTestRun -->|results| KokoroL
    AITestRun -->|results| KokoroL
    AEFTestRun -->|results| KokoroL
    KokoroL -->|status| Dev

    %% Legend
    classDef code fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef script fill:#C8E6C9,stroke:#2E7D32,color:#2E7D32
    classDef ci fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef dev fill:#E0E0E0,stroke:#424242,color:#424242
```
