# irdaislakhuafa/go-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/irdaislakhuafa/go-sdk
- Repository: https://github.com/irdaislakhuafa/go-sdk

## Overview

##### Project type and purpose
- This is a Go Software Development Kit (SDK): a collection of reusable Go packages (libraries) providing utilities for context management, error handling, cryptography, data structures, file I/O, database access, caching, logging, concurrency control, SMTP/email, string formatting, and more.
- It is not a running service or full-stack app, but an open-source toolkit that application developers import to accelerate common tasks in Go projects.

##### File structure
- Every top-level directory corresponds to an independent Go package:
- appcontext
- auth
- caches
- codes
- collections
- concurrency
- convert
- cryptography
- datastructure
- db
- errors
- files
- header
- language
- log
- operator
- querybuilder
- random
- smtp
- sorter
- storage
- strformat
- Each package ends in `.go` files and has associated `_test.go` files.
- Configuration files exist for the `querybuilder/sqlc` sub-tool, demonstrating code generation from SQL schemas.

##### README
- Confirms the SDK’s purpose: “code collection” for common Go development tasks.
- Documents each package’s functionality and external dependencies (e.g., zerolog, gomail, text/template).
- Points out extensibility (e.g., TODO to implement disk storage).

##### Main components & relationships
a. Core utility packages
- codes → errors (error codes inform error package)
- errors → any package needing standardized errors
- collections, datastructure, convert, operator, random, sorter → general-purpose utilities
- strformat, header, language → string & i18n helpers
b. Infrastructure packages
- db (MySQL, PostgreSQL, SQLite)
- caches (in-memory, SQLite)
- storage (MinIO, future disk)
- files → file system helpers
- querybuilder/sqlc → code generation layer on top of db
c. Security & auth
- cryptography (AES-GCM, Argon2, bcrypt, SHA256)
- auth/jwt → JSON Web Token generation & validation
d. Concurrency
- concurrency (goroutine pool, semaphore)
e. Communication
- smtp (gomail wrapper)
- log (zerolog wrapper)
f. appcontext
- Carries request-scoped data across all layers

- An application at the top importing “Go SDK”
- smtp → SMTP server
- log → external zerolog library
- cryptography.argon2 → node-argon2-compatible format (interoperability)

##### Architectural patterns & design principles
- Modular single-responsibility packages
- Clear layering: core utilities vs. infrastructure vs. security vs. communication
- Dependency inversion: high-level modules depend on abstractions in low-level (e.g., caches interface vs. memory/sqlite implementations)
- Extensibility points: storage disk implementation placeholder, querybuilder codegen

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application
    Application["Application"]:::external

    %% SDK Container
    subgraph "Go SDK"
        direction TB

        %% Context
        AppContext["appcontext"]:::context

        %% Utilities (Green)
        subgraph "Utilities" 
            direction TB
            Codes["codes"]:::utilities
            Errors["errors"]:::utilities
            Collections["collections"]:::utilities
            Convert["convert"]:::utilities
            Operator["operator"]:::utilities
            Random["random"]:::utilities
            Sorter["sorter"]:::utilities
            StrFormat["strformat"]:::utilities
            Header["header"]:::utilities
            Language["language"]:::utilities
        end

        %% Infrastructure (Blue)
        subgraph "Infrastructure"
            direction TB
            DB["db"]:::infrastructure
            Caches["caches"]:::infrastructure
            Storage["storage"]:::infrastructure
            Files["files"]:::infrastructure
            QueryBuilder["querybuilder/sqlc"]:::infrastructure
        end

        %% Security & Auth (Red)
        subgraph "Security/Auth"
            direction TB
            Crypto["cryptography"]:::security
            AuthJWT["auth"]:::security
        end

        %% Concurrency (Purple)
        Concurrency["concurrency"]:::concurrency

        %% Communication (Orange)
        SMTPpkg["smtp"]:::communication
        LogPkg["log"]:::communication
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        MySQL["MySQL"]:::external
        PostgreSQL["PostgreSQL"]:::external
        SQLiteExt["SQLite"]:::external
        MinIO["MinIO"]:::external
        SMTPServer["SMTP Server"]:::external
        ZeroLog["zerolog"]:::external
        TextTemplate["text/template"]:::external
        SQLSchema["SQL Schema"]:::external
    end

    %% Connections from Application to SDK
    Application -->|imports| AppContext
    Application -->|imports| Codes
    Application -->|imports| DB
    Application -->|imports| AuthJWT
    Application -->|imports| SMTPpkg

    %% Core dependencies
    Codes -->|"defines codes"| Errors
    Errors -->|used by| Codes
    Errors -->|used by| Collections
    Collections -->|utilities| Convert
    Collections -->|utilities| Operator
    Collections -->|utilities| Random
    Collections -->|utilities| Sorter
    StrFormat -->|formats strings| Header
    Header -->|manages| Language

    %% Infrastructure dependencies
    DB -->|"SQL driver"| MySQL
    DB -->|"SQL driver"| PostgreSQL
    DB -->|"SQL driver"| SQLiteExt
    DB -->|supports| QueryBuilder
    Caches -->|in-memory| SQLiteExt
    Caches -->|implements| Caches
    Storage -->|"MinIO API"| MinIO
    Files -->|"filesystem"| Storage
    QueryBuilder -->|reads| SQLSchema
    QueryBuilder -->|generates code| DB

    %% Security & Auth
    Crypto -->|AES-GCM, Argon2| Crypto
    Crypto -->|bcrypt, SHA256| Crypto
    Crypto -->|interoperability| NodeArgon["node-argon2 format"]:::external
    AuthJWT -->|generates/validates| Crypto

    %% Concurrency
    Concurrency -->|goroutine pool| Collections
    Concurrency -->|semaphore| Collections

    %% Communication
    SMTPpkg -->|SMTP client| SMTPServer
    LogPkg -->|wrapper| ZeroLog
    LogPkg -->|templating| TextTemplate

    %% Context
    AppContext -->|carries data| Codes
    AppContext -->|carries data| DB
    AppContext -->|carries data| AuthJWT
    AppContext -->|carries data| SMTPpkg

    %% Click Events
    click AppContext "https://github.com/irdaislakhuafa/go-sdk/blob/master/appcontext/appcontext.go"
    click AuthJWT "https://github.com/irdaislakhuafa/go-sdk/blob/master/auth/jwt.go"
    click Caches "https://github.com/irdaislakhuafa/go-sdk/blob/master/caches/caches.go"
    click Caches "https://github.com/irdaislakhuafa/go-sdk/blob/master/caches/memory.go"
    click Caches "https://github.com/irdaislakhuafa/go-sdk/blob/master/caches/sqlite.go"
    click Codes "https://github.com/irdaislakhuafa/go-sdk/blob/master/codes/codes.go"
    click Codes "https://github.com/irdaislakhuafa/go-sdk/blob/master/codes/code_func.go"
    click Codes "https://github.com/irdaislakhuafa/go-sdk/blob/master/codes/code_messages.go"
    click Errors "https://github.com/irdaislakhuafa/go-sdk/blob/master/errors/errors.go"
    click Errors "https://github.com/irdaislakhuafa/go-sdk/blob/master/errors/errors_stacktrace.go"
    click Collections "https://github.com/irdaislakhuafa/go-sdk/blob/master/collections/map.go"
    click Collections "https://github.com/irdaislakhuafa/go-sdk/blob/master/collections/slice.go"
    click Collections "https://github.com/irdaislakhuafa/go-sdk/blob/master/collections/reduce.go"
    click Concurrency "https://github.com/irdaislakhuafa/go-sdk/blob/master/concurrency/concurrency.go"
    click Concurrency "https://github.com/irdaislakhuafa/go-sdk/blob/master/concurrency/semaphore.go"
    click Convert "https://github.com/irdaislakhuafa/go-sdk/blob/master/convert/ptr.go"
    click Crypto "https://github.com/irdaislakhuafa/go-sdk/blob/master/cryptography/aes256gcm.go"
    click Crypto "https://github.com/irdaislakhuafa/go-sdk/blob/master/cryptography/argon2.go"
    click Crypto "https://github.com/irdaislakhuafa/go-sdk/blob/master/cryptography/bcrypt.go"
    click Crypto "https://github.com/irdaislakhuafa/go-sdk/blob/master/cryptography/sha256.go"
    click DB "https://github.com/irdaislakhuafa/go-sdk/blob/master/db/db.go"
    click DB "https://github.com/irdaislakhuafa/go-sdk/blob/master/db/mysql.go"
    click DB "https://github.com/irdaislakhuafa/go-sdk/blob/master/db/postgresql.go"
    click DB "https://github.com/irdaislakhuafa/go-sdk/blob/master/db/sqlite.go"
    click Files "https://github.com/irdaislakhuafa/go-sdk/blob/master/files/files.go"
    click Header "https://github.com/irdaislakhuafa/go-sdk/blob/master/header/header.go"
    click Language "https://github.com/irdaislakhuafa/go-sdk/blob/master/language/language.go"
    click Language "https://github.com/irdaislakhuafa/go-sdk/blob/master/language/text_en.go"
    click Language "https://github.com/irdaislakhuafa/go-sdk/blob/master/language/text_id.go"
    click LogPkg "https://github.com/irdaislakhuafa/go-sdk/blob/master/log/log.go"
    click Operator "https://github.com/irdaislakhuafa/go-sdk/blob/master/operator/ternary.go"
    click QueryBuilder "https://github.com/irdaislakhuafa/go-sdk/blob/master/querybuilder/sqlc/sqlc.go"
    click QueryBuilder "https://github.com/irdaislakhuafa/go-sdk/blob/master/querybuilder/sqlc/sqlc_builder.go"
    click QueryBuilder "https://github.com/irdaislakhuafa/go-sdk/blob/master/querybuilder/sqlc/sqlc_wrapped.go"
    click Random "https://github.com/irdaislakhuafa/go-sdk/blob/master/random/randomint.go"
    click SMTPpkg "https://github.com/irdaislakhuafa/go-sdk/blob/master/smtp/smtp.go"
    click SMTPpkg "https://github.com/irdaislakhuafa/go-sdk/blob/master/smtp/gomail.go"
    click Sorter "https://github.com/irdaislakhuafa/go-sdk/blob/master/sorter/sorter.go"
    click Storage "https://github.com/irdaislakhuafa/go-sdk/blob/master/storage/storage.go"
    click Storage "https://github.com/irdaislakhuafa/go-sdk/blob/master/storage/minio.go"
    click Storage "https://github.com/irdaislakhuafa/go-sdk/blob/master/storage/helper.go"
    click StrFormat "https://github.com/irdaislakhuafa/go-sdk/blob/master/strformat/strformat.go"

    %% Styles
    classDef utilities fill:#ccffcc,stroke:#008000,color:#000;
    classDef infrastructure fill:#cce5ff,stroke:#005cbf,color:#000;
    classDef security fill:#f8d7da,stroke:#721c24,color:#000;
    classDef communication fill:#ffe5b4,stroke:#ff8c00,color:#000;
    classDef concurrency fill:#e2e0f8,stroke:#4b0082,color:#000;
    classDef context fill:#fff3cd,stroke:#856404,color:#000;
    classDef external fill:#f0f0f0,stroke:#666666,color:#000;
```
