# clerk/clerk-sdk-csharp architecture

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

- Interactive diagram: https://gitdiagram.com/clerk/clerk-sdk-csharp
- Repository: https://github.com/clerk/clerk-sdk-csharp

## Overview

##### Project type and purpose
- This is a generated .NET (C#) client SDK for the Clerk REST Backend API.
- Purpose: provide a type-safe, idiomatic C# wrapper around Clerk’s HTTP endpoints so backend servers can easily call user-management operations (Users, Sessions, OAuth, SAML, etc.).

##### File structure
- Top-level:
- .github/workflows – CI/CD pipelines (codegen, test, publish)
- .speakeasy – code generation config (OpenAPI → C# models & operations)
- docs/ – static markdown API references and per-SDK README fragments
- src/Clerk/BackendAPI – C# project containing:
– ClerkBackendApi.cs (Facade client entry point)
– Operations (resource-grouped API methods)
– Models (Components & Operations request/response types)
– Helpers & Hooks (authentication, request interception)
– Utils (HTTP client wrapper, serialization, retry logic)
- tests/ – unit tests for hooks, JWT validation, request auth
- GitHub Actions (sdk_generation.yaml, sdk_publish.yaml) orchestrate generation and deployment to NuGet

##### README for additional insights
- Describes authentication (BearerAuth), retry configuration, server URL override
- Illustrates how applications consume the SDK: instantiate `new ClerkBackendApi(...)`, call `sdk.Users.GetAsync(...)`, handle models & errors

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GHGen["GitHub Actions\n(sdk_generation)"]:::ci
        GHPub["GitHub Actions\n(sdk_publish)"]:::ci
        SpeakeasyGen["Speakeasy Generator"]:::ci
        GHGen -->|triggers| SpeakeasyGen
        SpeakeasyGen -->|generates C# code| Src
        GHGen -->|runs tests & build| GHPub
        GHPub -->|publishes to| NuGet
    end

    %% Source Code
    subgraph "SDK Library Source" 
        direction TB
        Src["src/Clerk/BackendAPI"]:::source
        ClerkApi["ClerkBackendApi"]:::source
        Operations["Operations"]:::source
        Models["Models"]:::source
        Helpers["Helpers/Hooks"]:::source
        Utils["Utils"]:::source

        Src --> ClerkApi
        Src --> Operations
        Src --> Models
        Src --> Helpers
        Src --> Utils
    end

    %% Runtime Flow
    subgraph "Runtime Usage"
        direction TB
        App["Application"]:::app
        App -->|"instantiates"| ClerkApi
        ClerkApi -->|"calls operations"| Operations
        Operations -->|"builds request"| Utils
        Utils -->|"sends HTTP"| HttpClient
        HttpClient["SpeakeasyHttpClient"]:::source -->|"to"| ClerkAPIExt
        Helpers -->|intercept| HttpClient
        ClerkAPIExt["Clerk REST API"]:::ext
        ClerkAPIExt -->|"JSON response"| Utils
        Utils --> Models
        Models --> App
    end

    %% Test Suite
    subgraph "Test Suite"
        direction TB
        Tests["tests/"]:::test
        Tests --> BeforeReqTests["BeforeRequestHookTests"]:::test
        Tests --> AuthReqTests["AuthenticateRequestTests"]:::test
        Tests --> ClaimsTests["OrganizationClaimsProcessorTests"]:::test
        Tests --> VerifyTests["VerifyTokenTests"]:::test
    end

    %% External Systems
    NuGet["NuGet Registry"]:::ext

    %% Connections
    GHPub --> NuGet

    %% Click Events
    click GHGen "https://github.com/clerk/clerk-sdk-csharp/blob/main/.github/workflows/sdk_generation.yaml"
    click GHPub "https://github.com/clerk/clerk-sdk-csharp/blob/main/.github/workflows/sdk_publish.yaml"
    click SpeakeasyGen "https://github.com/clerk/clerk-sdk-csharp/blob/main/.speakeasy/workflow.yaml"
    click SpeakeasyGen "https://github.com/clerk/clerk-sdk-csharp/blob/main/.speakeasy/gen.yaml"
    click ClerkApi "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/ClerkBackendApi.cs"
    click ClerkApi "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Clerk.BackendAPI.csproj"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Users.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Sessions.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/OauthApplications.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/SamlConnections.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/ActorTokens.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/AllowlistIdentifiers.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/BlocklistIdentifiers.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Domains.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/EmailAddresses.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/EmailAndSmsTemplates.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/EmailSMSTemplates.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/ExperimentalAccountlessApplications.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/InstanceSettings.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Invitations.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Jwks.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/JwtTemplates.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Miscellaneous.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/OrganizationDomains.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/OrganizationInvitations.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/OrganizationMemberships.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Organizations.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/PhoneNumbers.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/ProxyChecks.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/RedirectUrls.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/SignInTokens.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/SignUps.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Templates.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/TestingTokens.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/WaitlistEntries.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Webhooks.cs"
    click Operations "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Clients.cs"
    click Models "https://github.com/clerk/clerk-sdk-csharp/tree/main/src/Clerk/BackendAPI/Models/Components"
    click Models "https://github.com/clerk/clerk-sdk-csharp/tree/main/src/Clerk/BackendAPI/Models/Errors"
    click Models "https://github.com/clerk/clerk-sdk-csharp/tree/main/src/Clerk/BackendAPI/Models/Operations"
    click Helpers "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Helpers/AuthenticateRequest.cs"
    click Helpers "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Helpers/AuthenticateRequestOptions.cs"
    click Helpers "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Helpers/AuthenticateRequestException.cs"
    click Helpers "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Helpers/VerifyToken.cs"
    click Helpers "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Helpers/VerifyTokenOptions.cs"
    click Helpers "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Helpers/OrganizationClaimsProcessor.cs"
    click Helpers "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Helpers/ErrorReason.cs"
    click Helpers "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Helpers/RequestState.cs"
    click Helpers "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Helpers/TokenVerificationException.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/SpeakeasyHttpClient.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/URLBuilder.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/RequestBodySerializer.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/ResponseBodyDeserializer.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/HeaderSerializer.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/IsoDateTimeSerializer.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/EnumConverter.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/Retries/RetryConfig.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/Retries/BackoffStrategy.cs"
    click Utils "https://github.com/clerk/clerk-sdk-csharp/blob/main/src/Clerk/BackendAPI/Utils/Retries/Retries.cs"
    click Tests "https://github.com/clerk/clerk-sdk-csharp/blob/main/tests/Tests.csproj"
    click BeforeReqTests "https://github.com/clerk/clerk-sdk-csharp/blob/main/tests/Hooks/BeforeRequestHookTests.cs"
    click AuthReqTests "https://github.com/clerk/clerk-sdk-csharp/blob/main/tests/JwksHelpers/AuthenticateRequestTests.cs"
    click ClaimsTests "https://github.com/clerk/clerk-sdk-csharp/blob/main/tests/JwksHelpers/OrganizationClaimsProcessorTests.cs"
    click VerifyTests "https://github.com/clerk/clerk-sdk-csharp/blob/main/tests/JwksHelpers/VerifyTokenTests.cs"

    %% Styles
    classDef ci fill:#ccf,stroke:#66f,stroke-width:1px;
    classDef source fill:#cce5ff,stroke:#004085,stroke-width:1px;
    classDef app fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;
    classDef ext fill:#fff3cd,stroke:#856404,stroke-width:1px,stroke-dasharray: 5 5;
    classDef test fill:#d4edda,stroke:#155724,stroke-width:1px;
```
