# stark-tech-group/stg-sdk-golang architecture

> Architecture diagram of the GitHub repository stark-tech-group/stg-sdk-golang, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stark-tech-group/stg-sdk-golang
- Repository: https://github.com/stark-tech-group/stg-sdk-golang

## Overview

##### Project type and purpose
- Type: Go-SDK + CLI wrapper (open-source tool)
- Purpose: Provide Go bindings around Stark Platform’s REST APIs, plus a CLI entrypoint (`cmd/stg-sdk-golang/main.go`).
- Context: Includes a `docker-compose.yml` and a suite of Dockerfiles to spin up a sandbox of all backend microservices, data stores, and message buses for local testing of the SDK.

##### Main components
1. SDK/CLI Layer
– **CLI Executable** (`cmd/stg-sdk-golang`)
– **starkapi Client** (in `pkg/starkapi`) exposing sub-APIs: AssetApi, PointApi, AuthApi, etc.
– **Domain Models** (in `pkg/domain`) representing JSON payloads
– **HTTP Layer** (in `pkg/http`) handling requests, errors, response parsing
– **Context & Env** (in `pkg/context`, `pkg/env`) managing configuration and auth tokens
2. Docker-Compose “Local Platform”
– **API Gateway** (container from `docker/api.Dockerfile`)
– **Auth Service** (`docker/auth-service.Dockerfile`)
– **Microservices** (e.g., `tag-api`, `stark-asset-api`, `reporting`, `finance`, `geo`, etc.)
– **Data Stores**: Redis, Elasticsearch, TimescaleDB
– **Message Buses**: event-message-bus, iot-message-bus, telemetry-bus
– **Auxiliary Services**: migrations, notification, search, diagnostics, etc.
3. External Dependencies
– **Azure Event Hub** (via `pkg/azure/eventhub_api.go`)
– **Stark Platform Hosted Endpoints** (remote API host when not using Docker)

##### Relationships & Data Flows
- **CLI/SDK → API Gateway**:
– `Client.Init(host)` & `Client.Login(un,pw)`
– HTTP(S) calls bearing auth token in header
– Request paths map to microservices via the API Gateway
- **API Gateway → Microservices**:
– REST calls dispatched internally
– Each microservice communicates with its datastore or publishes/subscribes on a message bus
- **Microservices → Data Stores / Buses**
– e.g., Telemetry data → telemetry-bus → telemetry-data service → TimescaleDB
– Audit logs in Redis or Elastic for search
- **SDK Internal**:
– `starkapi.Client` holds HTTP client + auth state
– Sub-API methods call shared request builder → unmarshal into `domain` structs → return to user

##### Architectural Patterns & Principles
– **Clean/Hexagonal Architecture** inside the SDK: separation of domain, transport (HTTP), and external API client layers
– **Microservices** pattern for backend sandbox: each service is single-responsibility, independently containerized
– **Environment-driven configuration**: `pkg/env` reads OS vars; Docker Compose injects `.my.env`

##### Technologies, Frameworks & Libraries
– Go Modules (`go.mod`, `go.sum`)
– Docker & Docker Compose
– Redis, Elasticsearch, TimescaleDB
– Azure Event Hub
– Sonar (quality checks) in CI workflows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% SDK/CLI Layer
    subgraph "SDK/CLI Layer"
        direction TB
        CLI["CLI Executable\ncmd/stg-sdk-golang/main.go"]:::sdk
        Client["starkapi.Client"]:::sdk
        HTTP["HTTP Layer"]:::sdk
        Domain["Domain Models"]:::sdk
        Context["Context Management"]:::sdk
        Env["Env Loader\npkg/env/env.go"]:::sdk
        AzureSDK["Azure Event Hub Integration"]:::external
        GoMod["Go Modules\n(go.mod, go.sum)"]:::sdk
    end

    %% Docker Compose Sandbox
    subgraph "Local Stark Platform Sandbox"
        direction TB
        DC["docker-compose.yml"]:::infrastructure
        APIGW["API Gateway"]:::micro
        AuthS["Auth Service"]:::micro
        subgraph "Microservices"
            direction TB
            TagAPI["Tag API"]:::micro
            AssetAPI["Stark Asset API"]:::micro
            Reporting["Reporting"]:::micro
            Finance["Finance"]:::micro
            Geo["Geo Service"]:::micro
            Issue["Issue Service"]:::micro
            Subscription["Subscription Service"]:::micro
            Search["Search Service"]:::micro
            Notification["Notification Service"]:::micro
            Diagnostics["Diagnostics Service"]:::micro
            Babbage["Babbage Service"]:::micro
            CloudFDD["CloudFDD Service"]:::micro
        end
        subgraph "Data Stores & Buses"
            direction TB
            Redis["Redis"]:::datastore
            ES["Elasticsearch"]:::datastore
            TSDB["TimescaleDB"]:::datastore
            EventBus["Event Message Bus"]:::datastore
            IoTBus["IoT Message Bus"]:::datastore
            TelemetryBus["Telemetry Bus"]:::datastore
        end
        subgraph "Auxiliary Services"
            direction TB
            ConnectInit["Connect Init Script"]:::infrastructure
            Migrations["Migrations Service"]:::infrastructure
            Scripts["Entry Scripts\nstart.sh, dcd.sh, dcu.sh"]:::infrastructure
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AzureEH["Azure Event Hub"]:::external
        RemoteSTG["Stark Platform Hosted"]:::external
    end

    %% Connections
    CLI -->|"calls Init/Login"| Client
    Client -->|"builds HTTP request"| HTTP
    Client -->|"uses domain types"| Domain
    Client -->|"uses context"| Context
    Client -->|"reads config"| Env
    Client -->|"can call"| AzureSDK
    HTTP -->|"HTTPS"| APIGW
    APIGW -->|"dispatch"| TagAPI
    APIGW --> AssetAPI
    APIGW --> Reporting
    APIGW --> Finance
    APIGW --> Geo
    APIGW --> Issue
    APIGW --> Subscription
    APIGW --> Search
    APIGW --> Notification
    APIGW --> Diagnostics
    APIGW --> Babbage
    APIGW --> CloudFDD

    TagAPI --> Redis
    AssetAPI --> ES
    Reporting --> TSDB
    Finance --> EventBus
    Geo --> IoTBus
    Diagnostics --> TelemetryBus
    TelemetryBus --> TSDB

    AzureSDK -.->|AMQP| AzureEH
    HTTP -.->|remote| RemoteSTG

    DC --> APIGW
    DC --> AuthS
    DC --> TagAPI
    DC --> AssetAPI
    DC --> Reporting
    DC --> Finance
    DC --> Geo
    DC --> Issue
    DC --> Subscription
    DC --> Search
    DC --> Notification
    DC --> Diagnostics
    DC --> Babbage
    DC --> CloudFDD
    DC --> Redis
    DC --> ES
    DC --> TSDB
    DC --> EventBus
    DC --> IoTBus
    DC --> TelemetryBus
    DC --> ConnectInit
    DC --> Migrations
    DC --> Scripts

    GoMod --> CLI

    %% Click Events
    click CLI "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/cmd/stg-sdk-golang/main.go"
    click Client "https://github.com/stark-tech-group/stg-sdk-golang/tree/dev/pkg/starkapi"
    click Domain "https://github.com/stark-tech-group/stg-sdk-golang/tree/dev/pkg/domain"
    click HTTP "https://github.com/stark-tech-group/stg-sdk-golang/tree/dev/pkg/http"
    click Context "https://github.com/stark-tech-group/stg-sdk-golang/tree/dev/pkg/context"
    click Env "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/pkg/env/env.go"
    click AzureSDK "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/pkg/azure/eventhub_api.go"
    click GoMod "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/go.mod"
    click GoMod "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/go.sum"
    click DC "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker-compose.yml"
    click APIGW "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/api.Dockerfile"
    click AuthS "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/auth-service.Dockerfile"
    click TagAPI "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/tag-api.Dockerfile"
    click AssetAPI "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/stark-asset-api.Dockerfile"
    click Reporting "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/reporting.Dockerfile"
    click Finance "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/finance.Dockerfile"
    click Geo "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/geo.Dockerfile"
    click Issue "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/issue-service.Dockerfile"
    click Subscription "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/subscription.Dockerfile"
    click Search "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/search.Dockerfile"
    click Notification "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/notification.Dockerfile"
    click Diagnostics "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/diagnostics.Dockerfile"
    click Babbage "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/babbage.Dockerfile"
    click CloudFDD "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/cloudfdd-service.Dockerfile"
    click Redis "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/redis.Dockerfile"
    click ES "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/elasticsearch.Dockerfile"
    click TSDB "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/timescaledb.Dockerfile"
    click EventBus "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/event-message-bus.Dockerfile"
    click IoTBus "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/iot-message-bus.Dockerfile"
    click TelemetryBus "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/telemetry-bus.Dockerfile"
    click ConnectInit "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/connect-init.Dockerfile"
    click Migrations "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/migrations.Dockerfile"
    click Scripts "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/start.sh"
    click Scripts "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/dcd.sh"
    click Scripts "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/docker/dcu.sh"
    click AzureEH "https://github.com/stark-tech-group/stg-sdk-golang/blob/dev/pkg/azure/eventhub_api.go"

    %% Styles
    classDef sdk fill:#E0F7FA,stroke:#006064,color:#006064
    classDef micro fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef datastore fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef external fill:#F3E5F5,stroke:#4A148C,color:#4A148C
    classDef infrastructure fill:#ECEFF1,stroke:#37474F,color:#37474F
```
