How google/uuid works
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