# ory/hydra-client-dotnet architecture

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

- Interactive diagram: https://gitdiagram.com/ory/hydra-client-dotnet
- Repository: https://github.com/ory/hydra-client-dotnet

## Overview

##### Project type and purpose
- This is a .NET SDK (client library) for Ory Hydra, auto-generated from an OpenAPI spec.
- It exposes REST API bindings (Api classes), model types, and authentication utilities for developers to integrate with a self-hosted Ory Hydra server.

##### File structure
- Top-level folders and files:
- `.github/` – CI/CD and issue/pr templates via GitHub Actions.
- `.bin/` – helper scripts for license management.
- `api/openapi.yaml` – the API definition driving code generation.
- `docs/` – per-endpoint markdown docs generated from the spec.
- `src/Ory.Hydra.Client` – main SDK project:
– `Api/` – generated service clients (JwkApi.cs, OAuth2Api.cs, etc.).
– `Client/` – shared HTTP client, auth, configuration, exception handling.
– `Model/` – data types matching Hydra’s request/response schemas.
- `src/Ory.Hydra.Client.Test` – unit tests for each Api and Model class.
- `README.md`, `LICENSE`, “.openapi-generator-ignore” – metadata and generator config.

##### README for additional insights
- Confirms:
- Fully auto-generated via OpenAPI Generator.
- Intended for self-hosted Ory Hydra only.
- Packaged as a NuGet library.

##### Main components
a. Code-generation pipeline
– Component: OpenAPI Generator
– Input: `api/openapi.yaml` + generator templates
– Output: `src/Ory.Hydra.Client` code + `docs/`
b. SDK runtime modules
– Api Layer (JwkApi, OAuth2Api, OidcApi, MetadataApi, WellknownApi)
– Client Core (ApiClient, Auth/OAuthAuthenticator, Configuration, ExceptionFactory)
– Model Layer (Hydra* POCOs)
c. Test harness
– Unit Tests project invoking Api and validating Model serialization
d. CI/CD & Packaging
– GitHub Actions workflows (build, test, license checks, NuGet publication)
e. External service
– Ory Hydra Server (REST endpoints, OAuth2/OIDC flows)

##### Relationships and interactions
- The OpenAPI Generator reads `openapi.yaml` → produces code modules and docs.
- SDK Api classes invoke HTTP calls via the Client Core to the Hydra server.
- Models are used for request payloads and response deserialization.
- Unit tests drive Api/Model code to validate correctness.
- GitHub workflows orchestrate generation, building, testing, and publishing to NuGet.

##### Architectural patterns and principles
- Client–Server: clear separation between SDK (client) and Hydra (server).
- Layered design:
- API interfaces → Client infrastructure → Model definitions.
- Single-responsibility: each subfolder/package has a distinct concern.
- Configuration and Auth are centralized in `Client/Configuration` and `Client/Auth`.
- Synchronous and asynchronous calls supported via interfaces (ISynchronousClient / IAsynchronousClient).

##### Technologies, frameworks, and libraries
- OpenAPI Generator (codegen)
- .NET 6+ / C#
- NuGet package management
- GitHub Actions for CI/CD
- xUnit / NUnit (or similar) for testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Code-Generation Pipeline
    subgraph "Code-Generation Pipeline"
        direction TB
        OpenAPISpec["OpenAPI Spec Input"]:::codegen
        GeneratorConfig["Generator Configuration"]:::codegen
        Generator["OpenAPI Generator"]:::codegen
        SDKCode["Generated SDK Code"]:::sdk
        Docs["Generated Docs"]:::docs
        OpenAPISpec --> Generator
        GeneratorConfig --> Generator
        Generator --> SDKCode
        Generator --> Docs
    end

    %% SDK Runtime
    subgraph "SDK Runtime"
        direction TB
        subgraph "API Layer"
            direction TB
            JwkApi["JwkApi"]:::api
            OAuth2Api["OAuth2Api"]:::api
            OidcApi["OidcApi"]:::api
            MetadataApi["MetadataApi"]:::api
            WellknownApi["WellknownApi"]:::api
        end
        subgraph "Client Core"
            direction TB
            ApiClient["ApiClient"]:::client
            Auth["OAuthAuthenticator"]:::client
            Config["Configuration"]:::client
            ExceptionFactory["ExceptionFactory"]:::client
        end
        subgraph "Model Layer"
            direction TB
            Model["POCO Models"]:::model
        end
        %% Relationships
        JwkApi -->|uses| ApiClient
        OAuth2Api -->|uses| ApiClient
        OidcApi -->|uses| ApiClient
        MetadataApi -->|uses| ApiClient
        WellknownApi -->|uses| ApiClient
        ApiClient -->|"calls REST"| HydraServer
        JwkApi -->|uses| Model
        OAuth2Api -->|uses| Model
        OidcApi -->|uses| Model
        MetadataApi -->|uses| Model
        WellknownApi -->|uses| Model
        Model -->|serialize/deserialize| ApiClient
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        ApiTests["API Tests"]:::test
        ModelTests["Model Tests"]:::test
        ApiTests --> JwkApi
        ApiTests --> OAuth2Api
        ModelTests --> Model
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        direction TB
        Workflows["GitHub Actions Workflows"]:::cicd
        License["License Scripts"]:::cicd
        Workflows --> Generator
        Workflows --> SDKCode
        Workflows --> Docs
        Workflows --> ApiTests
        Workflows --> ModelTests
        Workflows -->|"package to NuGet"| SDKCode
        License --> Workflows
    end

    %% External Service
    HydraServer["Ory Hydra Server"]:::external

    %% Click Events
    click OpenAPISpec "https://github.com/ory/hydra-client-dotnet/blob/master/api/openapi.yaml"
    click GeneratorConfig "https://github.com/ory/hydra-client-dotnet/blob/master/.openapi-generator-ignore"
    click SDKCode "https://github.com/ory/hydra-client-dotnet/blob/master/src/Ory.Hydra.Client"
    click Docs "https://github.com/ory/hydra-client-dotnet/tree/master/docs/"
    click JwkApi "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client/Api"
    click OAuth2Api "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client/Api"
    click OidcApi "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client/Api"
    click MetadataApi "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client/Api"
    click WellknownApi "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client/Api"
    click ApiClient "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client/Client"
    click Auth "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client/Client/Auth"
    click Config "https://github.com/ory/hydra-client-dotnet/blob/master/src/Ory.Hydra.Client/Client/Configuration.cs"
    click ExceptionFactory "https://github.com/ory/hydra-client-dotnet/blob/master/src/Ory.Hydra.Client/Client/ExceptionFactory.cs"
    click Model "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client/Model"
    click ApiTests "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client.Test/Api"
    click ModelTests "https://github.com/ory/hydra-client-dotnet/tree/master/src/Ory.Hydra.Client.Test/Model"
    click Workflows "https://github.com/ory/hydra-client-dotnet/tree/master/.github/workflows"
    click License "https://github.com/ory/hydra-client-dotnet/blob/master/.bin/license-engine.sh"

    %% Styles
    classDef codegen fill:#E0E0E0,stroke:#333,stroke-width:1px;
    classDef sdk fill:#D0E8FF,stroke:#005B9F,stroke-width:1px;
    classDef api fill:#B0D4FF,stroke:#005B9F,stroke-width:1px;
    classDef client fill:#FFD9B3,stroke:#D97706,stroke-width:1px;
    classDef model fill:#D0FFD6,stroke:#19692C,stroke-width:1px;
    classDef docs fill:#F0FFE0,stroke:#7A7A00,stroke-width:1px;
    classDef test fill:#FFE0E0,stroke:#9F1D1D,stroke-width:2px,stroke-dasharray: 5 5;
    classDef cicd fill:#EAD1DC,stroke:#9B0056,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#7A7A7A,stroke-width:1px,stroke-dasharray: 2 2;
```
