# aws/smithy-go architecture

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

- Interactive diagram: https://gitdiagram.com/aws/smithy-go
- Repository: https://github.com/aws/smithy-go

## Overview

##### Project type and purpose
- This is an open‑source tool that combines:
- A code generator (Java‑based Smithy build plugins under codegen/smithy‑go‑codegen)
- A Go runtime library (all other Go packages: auth, transport, middleware, document, encoding, endpoints, metrics, tracing, etc.)
- Purpose: Given a Smithy model and protocol definition, generate Go client (and server) code, and support it with a rich runtime for HTTP transport, serialization, authentication, metrics, tracing, error handling, and more.

##### File structure
- Top‑level “codegen” directory: a Gradle/Java plugin project implementing two Smithy build plugins (`go-codegen` and `go-server-codegen`), including template resources and Java source/test.
- Root Go modules (go.mod, go.sum) and directories for the runtime:
- auth, aws-http-auth – credential providers and request signing (SigV4, bearer tokens)
- transport/http – HTTP client, middleware for headers, checksums, content-length, logging
- middleware – HTTP request/response pipeline abstraction and built‑in steps
- document, encoding – JSON, XML, CBOR, HTTP‑binding serializers/deserializers
- endpoints – endpoint resolution rules and data
- metrics, tracing – OpenTelemetry integrations
- other utilities: context, container/cache, io, logging, rand, ptr, sync, time, validation, waiter, testing
- Build/config files: Makefile, .github workflows, Travis, CHANGELOG, CONTRIBUTING, etc.

##### README for additional insights
- The README describes:
- Two Smithy build plugins: go-codegen and go-server-codegen
- Plugin configuration keys (service, module, generateGoMod, goDirective)
- Supported protocols (currently rpcv2Cbor; AWS protocols forthcoming)
- Minimum Go version and warning that interfaces are unstable

a. Main components
1. Smithy CLI & Build System
– Inputs: .smithy model files + smithy-build.json + plugin JARs
– Java plugin: codegen/smithy-go-codegen
– Output: generated Go source code (client, server stubs)
2. Generated Go code
– Model-specific client API, service operations, types
3. smithy-go runtime library
– Core layers:
- transport layer (HTTP client, request/response)
- middleware pipeline (initialize, serialize, build, finalize, deserialize steps)
- auth (SigV4, bearer token, identity resolution)
- document & encoding (serde for JSON, XML, CBOR, HTTP bindings)
- endpoints (rules engine lookup)
- metrics & tracing (OpenTelemetry adapters)
- utilities (context propagation, caching, pointers, sync, validation, waiters)
4. External dependencies/services
– HTTP endpoints (AWS, other services)
– OpenTelemetry collector (for metrics/traces)

b. Relationships and interactions
- Smithy CLI invokes Java plugin → reads model → produces Go code + templates
- Generated Go code imports and uses the smithy‑go runtime packages
- At runtime: client call → construct middleware stack → serialize input (document/encoding) → apply auth → sign HTTP request → send via transport/http → receive response → deserialize → run response middleware → return output or error
- Metrics/tracing layers wrap around transport/middleware pipeline and emit telemetry

c. Architectural patterns and design principles
- Plugin architecture (Smithy build plugins for extensibility)
- Layered architecture (separate concerns: generation, transport, middleware, serde, auth)
- Middleware pipeline (chain‑of‑responsibility for request/response processing)
- Code‑generation + runtime separation (strongly decoupled)
- Rule‑driven endpoint resolution (data + function code in endpoints/private)

d. Key technologies, frameworks, libraries
- Smithy CLI and Smithy build plugins (Java/Gradle)
- Go 1.20+
- Templates in codegen Java plugin (MUSTACHE or text templates under resources)
- Go modules (go.mod)
- OpenTelemetry (smithyotelmetrics, smithyoteltracing)
- Go standard library (net/http, context, encoding/json, xml, sync)

##### Detail
- Break the runtime into as many logical sub‑components as possible (auth, transport, middleware, serde, endpoints, metrics, tracing, utilities).
- Plugin internals at a high level: source → templates → output.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Code Generation Phase
    subgraph "Code Generation Phase"
        direction TB
        SmithyCLI["Smithy CLI"]:::generator
        GoCodegenPlugin["Smithy Go Codegen Plugin"]:::generator
        GoServerCodegenPlugin["Smithy Go Server Codegen Plugin"]:::generator
    end

    SmithyCLI -->|"invokes"| GoCodegenPlugin
    SmithyCLI -->|"invokes"| GoServerCodegenPlugin
    GoCodegenPlugin -->|"generates Go client code"| GeneratedCode
    GoServerCodegenPlugin -->|"generates Go server stubs"| GeneratedCode

    %% Compile-time Artifacts
    subgraph "Compile-time Artifacts"
        direction TB
        GeneratedCode["Generated Go Client Code"]:::generated
        subgraph "smithy-go Runtime Library"
            direction TB
            Auth["Authentication"]:::runtime
            Transport["HTTP Transport Layer"]:::runtime
            Middleware["Middleware Pipeline"]:::runtime
            DocumentModel["Document Model (CBOR/JSON)"]:::runtime
            Encoding["Encoding (JSON, XML, CBOR, HTTP-binding)"]:::runtime
            Endpoints["Endpoint Resolution Rules Engine"]:::runtime
            Metrics["Metrics (OpenTelemetry)"]:::runtime
            Tracing["Tracing (OpenTelemetry)"]:::runtime
            subgraph "Utilities"
                direction TB
                Context["Context Propagation"]:::runtime
                Cache["Container/Cache"]:::runtime
                IO["IO Utilities"]:::runtime
                Logging["Logging"]:::runtime
                Rand["Random ID Generation"]:::runtime
                Ptr["Pointer Helpers"]:::runtime
                Sync["Sync Primitives"]:::runtime
                Time["Time Utilities"]:::runtime
                Validation["Validation Helpers"]:::runtime
                Waiter["Waiters"]:::runtime
                Testing["Testing Helpers"]:::runtime
            end
        end
    end

    GeneratedCode -->|"imports"| Auth
    GeneratedCode -->|"imports"| Transport
    GeneratedCode -->|"imports"| Middleware
    GeneratedCode -->|"imports"| DocumentModel
    GeneratedCode -->|"imports"| Encoding
    GeneratedCode -->|"imports"| Endpoints
    GeneratedCode -->|"imports"| Metrics
    GeneratedCode -->|"imports"| Tracing
    GeneratedCode -->|"imports"| Context
    GeneratedCode -->|"imports"| Cache
    GeneratedCode -->|"imports"| IO
    GeneratedCode -->|"imports"| Logging
    GeneratedCode -->|"imports"| Rand
    GeneratedCode -->|"imports"| Ptr
    GeneratedCode -->|"imports"| Sync
    GeneratedCode -->|"imports"| Time
    GeneratedCode -->|"imports"| Validation
    GeneratedCode -->|"imports"| Waiter
    GeneratedCode -->|"imports"| Testing

    %% Runtime Execution Flow
    subgraph "Runtime Execution"
        direction TB
        ClientCall["Client Call"]:::external
        ClientCall -->|"builds middleware stack"| Middleware
        Middleware -->|"serialize input"| DocumentModel
        DocumentModel -->|"apply encoding"| Encoding
        Encoding -->|"apply auth"| Auth
        Auth -->|"sign request"| Transport
        Transport -->|"send HTTP request"| ExternalService
        ExternalService["AWS/Other HTTP Endpoints"]:::external
        Transport -->|"receive response"| Middleware
        Middleware -->|"deserialize"| DocumentModel
        DocumentModel -->|"return output or error"| ClientCall
        Metrics -->|"wraps"| Transport
        Tracing -->|"wraps"| Transport
    end

    %% External systems
    OpenTelemetry["OpenTelemetry Collector"]:::external
    Metrics -->|"emit metrics to"| OpenTelemetry
    Tracing -->|"emit traces to"| OpenTelemetry

    %% Click Events
    click GoCodegenPlugin "https://github.com/aws/smithy-go/tree/main/codegen/smithy-go-codegen"
    click GoServerCodegenPlugin "https://github.com/aws/smithy-go/tree/main/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/server"
    click Auth "https://github.com/aws/smithy-go/tree/main/auth/"
    click Auth "https://github.com/aws/smithy-go/tree/main/aws-http-auth/"
    click Transport "https://github.com/aws/smithy-go/tree/main/transport/http/"
    click Middleware "https://github.com/aws/smithy-go/tree/main/middleware/"
    click DocumentModel "https://github.com/aws/smithy-go/tree/main/document/"
    click DocumentModel "https://github.com/aws/smithy-go/tree/main/document/cbor/"
    click Encoding "https://github.com/aws/smithy-go/tree/main/encoding/"
    click Endpoints "https://github.com/aws/smithy-go/tree/main/endpoints/"
    click Endpoints "https://github.com/aws/smithy-go/tree/main/endpoints/private/"
    click Metrics "https://github.com/aws/smithy-go/tree/main/metrics/"
    click Metrics "https://github.com/aws/smithy-go/tree/main/metrics/smithyotelmetrics/"
    click Tracing "https://github.com/aws/smithy-go/tree/main/tracing/"
    click Tracing "https://github.com/aws/smithy-go/tree/main/tracing/smithyoteltracing/"
    click Context "https://github.com/aws/smithy-go/tree/main/context/"
    click Cache "https://github.com/aws/smithy-go/tree/main/container/private/cache/"
    click IO "https://github.com/aws/smithy-go/tree/main/io/"
    click Logging "https://github.com/aws/smithy-go/tree/main/logging/"
    click Rand "https://github.com/aws/smithy-go/tree/main/rand/"
    click Ptr "https://github.com/aws/smithy-go/tree/main/ptr/"
    click Sync "https://github.com/aws/smithy-go/tree/main/internal/sync/"
    click Sync "https://github.com/aws/smithy-go/tree/main/sync/"
    click Time "https://github.com/aws/smithy-go/tree/main/time/"
    click Validation "https://github.com/aws/smithy-go/blob/main/validation.go"
    click Waiter "https://github.com/aws/smithy-go/tree/main/waiter/"
    click Testing "https://github.com/aws/smithy-go/tree/main/testing/"

    %% Styles
    classDef generator fill:#FFDDC1,stroke:#333,stroke-width:1px;
    classDef generated fill:#E5FFE5,stroke:#333,stroke-width:1px;
    classDef runtime fill:#C1E1FF,stroke:#333,stroke-width:1px;
    classDef external fill:#FFD1FF,stroke:#333,stroke-width:1px;
```
