# google/uuid architecture

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

- Interactive diagram: https://gitdiagram.com/google/uuid
- Repository: https://github.com/google/uuid

## Overview

##### Project type and purpose (what you’re diagramming)
This repository is a **single Go library/package** (`github.com/google/uuid`) that:
- **Generates** UUIDs for multiple versions (notably v1, v4, v6, v7 per RFC 9562 + DCE 1.1)
- **Parses/inspects** UUIDs
- Provides **interop adapters** for common ecosystems (JSON marshal/unmarshal, `database/sql`, time utilities)

##### Read the file tree as architecture boundaries
At top-level, there’s no `cmd/`, no `internal/`, no subpackages—this is a **flat package** organized by concern:

##### Core type + utilities
- `uuid.go` (likely primary type + constructors)
- `util.go` (helpers)
- `hash.go` (name-based / hashing support, or hashing utilities used by versions)
- `null.go` (nullable UUID support)
- `marshal.go` (text/binary/JSON marshal helpers)
- `json_test.go`, `null_test.go`, etc.

##### UUID version implementations
- `version1.go`, `version4.go`, `version6.go`, `version7.go` (+ `version6_test.go`)
- `dce.go` (DCE security-related bits for v1 / node / clock sequence contexts)

##### Platform/environment-specific node identifier acquisition
- `node.go` (shared node logic)
- `node_net.go` (node from network interfaces / MAC; typical for v1)
- `node_js.go` (node acquisition in JS/WebAssembly environment)

##### Time + external integration
- `time.go` (+ `time_test.go`) (timestamp conversions, epoch offsets for v1/v6/v7)
- `sql.go` (+ `sql_test.go`) (`database/sql` Scanner/Valuer support)

##### Meta/build/release hygiene
- `go.mod` (dependencies)
- `.github/workflows/tests.yaml`, `apidiff.yaml`, `release-please.yml` (CI/release automation)
- `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, etc.

Shows internal components (grouped by files/concerns) and their dependencies.

- “Generate UUID v1” (node + clock sequence + timestamp)
- “Generate UUID v4” (random)
- “Generate UUID v6/v7” (time-ordered variants; time source + random/sequence)
- “Parse/Marshal” (string/binary ↔ UUID)
- “SQL/JSON integration path”

##### Platform-conditional build view (optional but valuable here)
Highlights that `node_js.go` vs `node_net.go` are chosen by build tags/target environment.

**data dependencies** and **control flow**.

##### UUID generation flows (control + data)
- **v1**:
- v1 engine → gets **timestamp** (time.go)
- v1 engine → gets **node ID** (node.go → node_net.go OR node_js.go)
- v1 engine → uses **clock sequence / DCE rules** (dce.go)
- Output → UUID core representation

- **v4**:
- v4 engine → pulls **random bytes** (entropy source)
- Output → UUID core

- **v6**:
- v6 engine → time.go timestamp → reorders for sortability
- may use random/sequence bits depending on implementation
- Output → UUID core

- **v7**:
- v7 engine → unix time (ms/nsec) from time.go
- plus random bytes
- Output → UUID core

##### Parse/format/marshal flows (bidirectional)
- Caller → Parse/String → UUID core + util.go
- Caller ↔ marshal.go ↔ encoding/json (and text/binary interfaces)
- Caller ↔ sql.go ↔ database/sql

##### Platform selection (build-time dependency)
- node.go depends on either:
- node_net.go (non-JS)
- node_js.go (JS/WASM)

##### Important architectural patterns/design principles visible here

- **Single-package cohesion**: many concerns, but tight scope; separation is by file/module responsibility.
- **Provider pattern by build target**: node acquisition differs by environment (net vs JS).
- **Interop adapters**: explicit integration points for Go stdlib ecosystems (`encoding/json`, `database/sql`).
- **Deterministic core representation**: UUID as fixed `[16]byte` (improves performance & avoids “invalid UUID” state; NIL UUID used instead).

##### Generators
- v1 (`version1.go`, `dce.go`, `node.go`, `time.go`)
- v4 (`version4.go`)
- v6 (`version6.go`, `time.go`)
- v7 (`version7.go`, `time.go`)
##### Providers
- Randomness (Go stdlib)
- Time (Go stdlib + `time.go`)
- Node (build-specific `node_net.go` / `node_js.go`)
##### Interop adapters
- JSON/Text/Binary (`marshal.go`)
- SQL (`sql.go`)
##### Quality/Release (non-runtime)
- Tests (`*_test.go`)
- CI workflows + API diff + release automation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External callers
    %% =========================
    Caller["Applications / Callers"]:::external

    %% =========================
    %% uuid package (single Go package)
    %% =========================
    subgraph uuidPkg["uuid Package (github.com/google/uuid)"]
        direction TB

        %% --- Public API surface ---
        subgraph pubAPI["Public API Surface"]
            direction TB
            Doc["Package docs (doc.go)"]:::docs
            API["Public API (UUID type, constructors, Parse/String)"]:::api
        end

        %% --- Core model & helpers ---
        subgraph coreHelpers["Core Model & Shared Helpers"]
            direction TB
            Core["UUID core & basic ops (uuid.go)"]:::core
            Util["Utilities/helpers (util.go)"]:::core
            Hash["Hashing/name-based utils (hash.go)"]:::core
            TimeUtil["Time utilities (time.go)"]:::provider
        end

        %% --- Generators (version engines) ---
        subgraph gens["Generators (Version Engines)"]
            direction TB
            V1["v1 generator (version1.go)"]:::gen
            DCE["DCE 1.1 bits (dce.go)"]:::gen
            V4["v4 generator (version4.go)"]:::gen
            V6["v6 generator (version6.go)"]:::gen
            V7["v7 generator (version7.go)"]:::gen
        end

        %% --- Providers (inputs) ---
        subgraph providers["Environment Providers (Inputs)"]
            direction TB
            Node["Node provider coordinator (node.go)"]:::provider
            NodeNet["Node acquisition (node_net.go)"]:::provider
            NodeJS["Node acquisition (node_js.go)"]:::provider
        end

        %% --- Interop adapters ---
        subgraph interop["Interop Adapters"]
            direction TB
            Marshal["Marshaling (text/binary/JSON) (marshal.go)"]:::interop
            NullUUID["Nullable UUID (null.go)"]:::interop
            SQL["SQL adapter (sql.go)"]:::interop
        end

        %% --- Quality/Release (non-runtime) ---
        subgraph quality["Quality & Release (Non-runtime)"]
            direction TB

            subgraph unitTests["Unit Tests"]
                direction TB
                TUuid["uuid_test.go"]:::test
                TJson["json_test.go"]:::test
                TNull["null_test.go"]:::test
                TSeq["seq_test.go"]:::test
                TSql["sql_test.go"]:::test
                TTime["time_test.go"]:::test
                TV6["version6_test.go"]:::test
            end

            subgraph ciAuto["CI / Automation"]
                direction TB
                CITests["GitHub Actions: tests.yaml"]:::ci
                CIApiDiff["GitHub Actions: apidiff.yaml"]:::ci
                ReleasePlease["Release automation: release-please.yml"]:::ci
            end
        end
    end

    %% =========================
    %% Go stdlib / runtime dependencies
    %% =========================
    subgraph stdlib["Go stdlib / Runtime"]
        direction TB
        StdTime["time (stdlib)"]:::external
        StdRand["crypto/rand (stdlib)"]:::external
        StdNet["net (stdlib)"]:::external
        StdJSON["encoding/json (stdlib)"]:::external
        StdSQL["database/sql (stdlib)"]:::external
        StdDriver["database/sql/driver (stdlib)"]:::external
        StdFmt["encoding/text + encoding/binary (stdlib)"]:::external
        JSRuntime["JS/WASM environment APIs"]:::external
    end

    %% =========================
    %% Top-level call direction
    %% =========================
    Caller -->|"calls"| API

    %% Public API composition/delegation
    Doc -->|"documents"| API
    API -->|"uses"| Core
    API -->|"uses"| Util

    %% Parse/format/marshal flows (bidirectional usage)
    API <-->|"string/[]byte"| Marshal
    Marshal -->|"uses"| Util
    Marshal -->|"uses"| Core
    Marshal -->|"integrates"| StdJSON
    Marshal -->|"integrates"| StdFmt

    %% Nullable UUID integration
    API <-->|"optional UUID"| NullUUID
    NullUUID -->|"wraps"| Core
    NullUUID -->|"uses"| Util
    NullUUID -->|"uses"| Marshal

    %% SQL adapter integration
    API <-->|"Scanner/Valuer"| SQL
    SQL -->|"wraps"| Core
    SQL -->|"integrates"| StdSQL
    SQL -.->|"implements"| StdDriver

    %% Hashing/name-based utilities (shared)
    API -->|"uses"| Hash
    Hash -->|"uses"| Util
    Hash -->|"uses"| Core

    %% =========================
    %% Generator flows
    %% =========================
    API -->|"generates v1"| V1
    API -->|"generates v4"| V4
    API -->|"generates v6"| V6
    API -->|"generates v7"| V7

    %% v1 dependencies
    V1 -->|"timestamp"| TimeUtil
    V1 -->|"node ID"| Node
    V1 -->|"clock seq / DCE rules"| DCE
    V1 -->|"build UUID [16]byte"| Core
    V1 -->|"uses"| Util

    %% v4 dependencies
    V4 -->|"random bytes"| StdRand
    V4 -->|"build UUID [16]byte"| Core
    V4 -->|"uses"| Util

    %% v6 dependencies
    V6 -->|"timestamp (reordered)"| TimeUtil
    V6 -->|"build UUID [16]byte"| Core
    V6 -->|"uses"| Util
    V6 -->|"may use random/seq"| StdRand

    %% v7 dependencies
    V7 -->|"unix time"| TimeUtil
    V7 -->|"random bytes"| StdRand
    V7 -->|"build UUID [16]byte"| Core
    V7 -->|"uses"| Util

    %% time utilities -> stdlib time
    TimeUtil -->|"time.Now + conversions"| StdTime

    %% =========================
    %% Node provider selection (build-time)
    %% =========================
    Node -.->|"build constraint"| NodeNet
    Node -.->|"build constraint"| NodeJS
    NodeNet -->|"reads interfaces/MAC"| StdNet
    NodeJS -->|"queries"| JSRuntime
    Node -->|"provides node ID"| V1

    %% =========================
    %% Non-runtime connections
    %% =========================
    TUuid -.->|"tests"| API
    TUuid -.->|"tests"| Core
    TUuid -.->|"tests"| Util

    TJson -.->|"tests"| Marshal
    TNull -.->|"tests"| NullUUID
    TSeq -.->|"tests"| V1
    TSql -.->|"tests"| SQL
    TTime -.->|"tests"| TimeUtil
    TV6 -.->|"tests"| V6

    CITests -.->|"runs go test"| TUuid
    CITests -.->|"runs go test"| TJson
    CITests -.->|"runs go test"| TNull
    CITests -.->|"runs go test"| TSeq
    CITests -.->|"runs go test"| TSql
    CITests -.->|"runs go test"| TTime
    CITests -.->|"runs go test"| TV6

    CIApiDiff -.->|"checks API compatibility"| API
    ReleasePlease -.->|"drives releases"| API

    %% =========================
    %% Click events (component_mapping)
    %% =========================
    click API "https://github.com/google/uuid/blob/master/uuid.go"
    click Core "https://github.com/google/uuid/blob/master/uuid.go"
    click Doc "https://github.com/google/uuid/blob/master/doc.go"
    click Util "https://github.com/google/uuid/blob/master/util.go"
    click Hash "https://github.com/google/uuid/blob/master/hash.go"
    click Marshal "https://github.com/google/uuid/blob/master/marshal.go"
    click NullUUID "https://github.com/google/uuid/blob/master/null.go"
    click SQL "https://github.com/google/uuid/blob/master/sql.go"
    click TimeUtil "https://github.com/google/uuid/blob/master/time.go"
    click V1 "https://github.com/google/uuid/blob/master/version1.go"
    click DCE "https://github.com/google/uuid/blob/master/dce.go"
    click V4 "https://github.com/google/uuid/blob/master/version4.go"
    click V6 "https://github.com/google/uuid/blob/master/version6.go"
    click V7 "https://github.com/google/uuid/blob/master/version7.go"
    click Node "https://github.com/google/uuid/blob/master/node.go"
    click NodeNet "https://github.com/google/uuid/blob/master/node_net.go"
    click NodeJS "https://github.com/google/uuid/blob/master/node_js.go"
    click TUuid "https://github.com/google/uuid/blob/master/uuid_test.go"
    click TJson "https://github.com/google/uuid/blob/master/json_test.go"
    click TNull "https://github.com/google/uuid/blob/master/null_test.go"
    click TSeq "https://github.com/google/uuid/blob/master/seq_test.go"
    click TSql "https://github.com/google/uuid/blob/master/sql_test.go"
    click TTime "https://github.com/google/uuid/blob/master/time_test.go"
    click TV6 "https://github.com/google/uuid/blob/master/version6_test.go"
    click CITests "https://github.com/google/uuid/blob/master/.github/workflows/tests.yaml"
    click CIApiDiff "https://github.com/google/uuid/blob/master/.github/workflows/apidiff.yaml"
    click ReleasePlease "https://github.com/google/uuid/blob/master/.github/release-please.yml"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#F3F4F6,stroke:#6B7280,color:#111827,stroke-width:1px
    classDef api fill:#DBEAFE,stroke:#2563EB,color:#0B1B3A,stroke-width:1.5px
    classDef docs fill:#E0E7FF,stroke:#4338CA,color:#111827,stroke-width:1px
    classDef core fill:#DCFCE7,stroke:#16A34A,color:#052e16,stroke-width:1.2px
    classDef gen fill:#FFEDD5,stroke:#F97316,color:#3A1A00,stroke-width:1.2px
    classDef provider fill:#FEF9C3,stroke:#CA8A04,color:#3A2A00,stroke-width:1.2px
    classDef interop fill:#FCE7F3,stroke:#DB2777,color:#3B0A1E,stroke-width:1.2px
    classDef test fill:#E5E7EB,stroke:#374151,color:#111827,stroke-dasharray: 3 3
    classDef ci fill:#E0F2FE,stroke:#0284C7,color:#0B1B3A,stroke-dasharray: 5 3
```
