# nebius/gosdk architecture

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

- Interactive diagram: https://gitdiagram.com/nebius/gosdk
- Repository: https://github.com/nebius/gosdk

## Overview

##### Main Components
- SDK Core: At the center, represent the overall SDK initialization and options (as seen in sdk.go, Makefile, and README examples). This module encapsulates core functions (e.g. creating a new SDK client, closing resources).
- Authentication Module: Show the authentication layer (directory “auth”) where different credential providers (IAM token and Service Account approaches) reside. Include submodules like “service_account.go”, “bearer.go”, and “cache.go” to denote how credentials and tokens are handled.
- Connection Management: Represent the “conn” package responsible for various connection utilities (dialing, idempotency, retries, parsing, etc.). This forms the network communication backbone.
- Service Layer: Illustrate the “services” package which is organized into numerous subdirectories (e.g. nebius/compute, nebius/iam, nebius/mk8s, etc.). Each service module (along with its versions, such as v1, v1alpha1, and v2) provides an interface to interact with different Nebius APIs.
- Protocol and API Definitions: Outline the “proto” directory as a central component where all gRPC interface definitions, message formats, and helper utilities (e.g., field masks) reside.
- Error and Utility Handling: Include the “serviceerror” module and other internal libraries (like “iter”) that provide error handling, iterators, and common shared functions.
- Mocks and Testing: Optionally note the “mocks” and “tests” directories as support components for ensuring the SDK functionality, which are important for quality assurance and integration but may be abstracted away in the high-level design.

##### Architectural Patterns and Design Principles
- Layered Architecture: Show layers (client core, authentication, network communication, service abstraction, and external gRPC endpoints) that indicate a clear flow from user calls to remote API interactions.
- Extensibility: Indicate that the “services” module is broken down into various API version submodules (v1, v1alpha1, and v2) to support multiple service interactions.

##### Relevant Technologies and Frameworks
- Point out that JWT is generated via the Service Account module and that IAM tokens are managed manually or automatically.
- In the Connection section, note techniques such as retries and timeouts which are implemented (as seen in “conn/retries.go” and “conn/inner_timeout.go”).
- Mention use of Go (minimum Go version 1.22) and how modules such as the “iter” package help with iterative resource listing (filtering) in a Go idiomatic way.

- Clear labels for each component (e.g., SDK Core, Auth Module, Connection Manager, Service Layer, gRPC/Proto Definitions, Error Handling).
- Callouts or annotations for key configurations found in README (like credential options and operational flows for Create, Get, Update, and Delete resource calls).
- Optionally, include a “CI/Build & Testing” block representing how the code is integrated and tested via GitHub workflows and mocks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    SDK_Core["SDK Core"]:::sdk
    Auth_Module["Authentication Module"]:::auth
    Conn_Management["Connection Management"]:::conn
    Service_Layer["Service Layer"]:::svc
    Proto_Def["Protocol Definitions"]:::proto
    Remote_gRPC["Remote gRPC Server"]:::external

    %% Error & Utility Handling Subgraph
    subgraph "Error & Utility Handling"
        Service_Error["Service Error Handling"]:::error
        Iter_Util["Iterator Utilities"]:::error
    end

    %% Mocks & Testing Subgraph
    subgraph "Mocks & Testing"
        Mocks["Mocks"]:::test
        Testing["Testing"]:::test
    end

    %% Primary Relationships
    SDK_Core -->|"initializes"| Auth_Module
    SDK_Core -->|"initializes"| Conn_Management
    SDK_Core -->|"initializes"| Service_Layer
    SDK_Core -->|"uses"| Proto_Def

    Auth_Module -->|"validates"| Conn_Management
    Conn_Management -->|"establishes"| Service_Layer

    Service_Layer -->|"calls"| Remote_gRPC
    Remote_gRPC -->|"responds"| Service_Layer

    Service_Layer <-->|"handles"| Service_Error
    Service_Layer <-->|"iterates"| Iter_Util

    SDK_Core -.->|"CItest"| Testing

    %% Styles
    classDef sdk fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef auth fill:#90EE90,stroke:#000,stroke-width:2px
    classDef conn fill:#FFFF99,stroke:#000,stroke-width:2px
    classDef svc fill:#FFA500,stroke:#000,stroke-width:2px
    classDef proto fill:#DDA0DD,stroke:#000,stroke-width:2px
    classDef external fill:#F0E68C,stroke:#000,stroke-width:2px
    classDef error fill:#FF6347,stroke:#000,stroke-width:2px
    classDef test fill:#D3D3D3,stroke:#000,stroke-width:2px

    %% Click Events
    click SDK_Core "https://github.com/nebius/gosdk/blob/main/sdk.go"
    click Auth_Module "https://github.com/nebius/gosdk/tree/main/auth/"
    click Conn_Management "https://github.com/nebius/gosdk/tree/main/conn/"
    click Service_Layer "https://github.com/nebius/gosdk/tree/main/services/"
    click Proto_Def "https://github.com/nebius/gosdk/tree/main/proto/"
    click Service_Error "https://github.com/nebius/gosdk/tree/main/serviceerror/"
    click Iter_Util "https://github.com/nebius/gosdk/tree/main/iter/"
    click Mocks "https://github.com/nebius/gosdk/tree/main/mocks/"
    click Testing "https://github.com/nebius/gosdk/tree/main/tests/"
```
