# go-uber/zap architecture

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

- Interactive diagram: https://gitdiagram.com/go-uber/zap
- Repository: https://github.com/go-uber/zap

## Overview

##### Project type and purpose
- This is an open-source Go library for blazing-fast, structured, leveled logging (zap).
- It provides two main APIs: a zero-allocation, type-safe Logger and a more ergonomic SugaredLogger.

##### File structure
- Top-level files: array.go, buffer, config.go, encoder.go, error.go, field.go, flag.go, global.go, http_handler.go, logger.go, options.go, sink.go, sugar.go, writer.go, zapcore (subpackage), zapgrpc, zaptest, zapio, internal, exp (experimental exports), benchmarks, assets.
- zapcore subpackage implements the core interfaces: Core, Encoder, WriteSyncer, Entry, Field handling, hooks, samplers, etc.
- zapgrpc, zapio, zaptest, zaptest/observer provide integrations and testing utilities.
- exp holds experimental packages (zapfield, zapslog).
- Benchmarks folder contains performance tests against other libraries.

##### README for additional insights
- The README emphasizes performance-oriented design: zero-allocation JSON encoder, reflection-free core.
- Two distinct APIs (Logger and SugaredLogger).
- Extensions (http, grpc, testing).

##### Interactions and data flow
- API call → Logger/SugaredLogger → constructs zapcore.Entry + []Field → passes to zapcore.Core
- zapcore.Core → serializes entry via Encoder → writes bytes to WriteSyncer (possibly via buffered pool)
- WriteSyncer → flushes to destination (stdout, file, network)
- Extensions wrap or decorate these steps (e.g., http handler captures request data into Fields, zapgrpc builds Fields from gRPC context)

##### Architectural patterns & design principles
- Separation of concerns: API vs core vs IO vs utils
- Interfaces for core components (Core, Encoder, WriteSyncer) enable pluggability
- Zero-allocation focus: buffer pools, reflection-free JSON
- Decorator pattern: Hooks, Tee, Sampler, buffered writers
- Experimental packages under exp for unstable APIs

##### Elements
- Clear labels: “Public API (zap)”, “Core (zapcore)”, “Buffer & IO”, “Internal utils”, “Extensions”
- From Public API to Core
- Core → Encoder → WriteSyncer → Destination
- Internal utils feeding Core and IO (bufferpool, pool, stacktrace)
- Extensions hooking into API/Core
- Green for core (zapcore)
- Gray for internal utilities
- Orange for IO layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Public API Layer
    subgraph "Public API (zap)"
        direction TB
        API_Logger["Logger"]:::public
        API_Sugar["SugaredLogger"]:::public
        API_GlobalLogger["Global Logger"]:::public
        API_Flag["Flag Handling"]:::public
        API_Config["Config & Options"]:::public
        API_Field["Field Builders"]:::public
        API_Error["Error Wrappers"]:::public
        API_Sink["Sink Abstraction"]:::public
        API_EncoderSel["Encoder Helpers"]:::public
        API_WriterHelper["Writer Helpers"]:::public
    end

    %% Core Layer
    subgraph "Core (zapcore)"
        direction TB
        Core_Core["Core Interface"]:::core
        Core_Entry["Entry Lifecycle"]:::core
        Core_FieldCore["Field Handling"]:::core
        Core_Hook["Hooks"]:::core
        Core_Sampler["Samplers"]:::core
        Core_Tee["Tee Logger"]:::core
        Core_JSONEnc["JSONEncoder"]:::core
        Core_ConsoleEnc["ConsoleEncoder"]:::core
        Core_MemoryEnc["MemoryEncoder"]:::core
        Core_ReflectedEnc["ReflectedEncoder"]:::core
        Core_WriteSync["WriteSyncer"]:::core
        Core_BufferedWS["BufferedWriteSyncer"]:::core
    end

    %% IO & Buffer Management
    subgraph "IO & Buffer"
        direction TB
        IO_BufferPoolInternal["Buffer Pool (internal)"]:::io
        IO_BufferTop["Top-level Buffer"]:::io
        IO_ZapIOWriter["zapio Writer"]:::io
        IO_SinkRoot["Sink Abstraction"]:::io
        IO_WriterRoot["Writer Helpers"]:::io
    end

    %% Internal Utilities
    subgraph "Internal Utilities"
        direction TB
        Util_Color["Color Output"]:::util
        Util_Exit["Exit Helpers"]:::util
        Util_Pool["Pool Utilities"]:::util
        Util_Stack["Stacktrace"]:::util
        Util_TestUtils["Test Utilities"]:::util
    end

    %% Extensions & Experimental
    subgraph "Extensions & Experimental"
        direction TB
        Ext_HTTP["HTTP Middleware"]:::ext
        Ext_gRPC["gRPC Adapter"]:::ext
        Ext_TestLogger["Testing Logger"]:::ext
        Ext_Observer["Observer"]:::ext
        Exp_Field["exp/zapfield"]:::exp
        Exp_SLog["exp/zapslog"]:::exp
    end

    %% Connections: API to Core
    API_Logger -->|"logs"| Core_Core
    API_Sugar -->|"logs"| Core_Core
    API_GlobalLogger --> Core_Core
    API_Flag --> Core_Core
    API_Config --> Core_Core
    API_Field --> Core_FieldCore
    API_Error --> Core_Core
    API_Sink --> IO_SinkRoot
    API_EncoderSel --> Core_JSONEnc
    API_WriterHelper --> IO_WriterRoot

    %% Core internal flow
    Core_Core --> Core_Entry
    Core_Entry --> Core_JSONEnc
    Core_Entry --> Core_ConsoleEnc
    Core_Entry --> Core_MemoryEnc
    Core_Entry --> Core_ReflectedEnc
    Core_JSONEnc --> Core_WriteSync
    Core_ConsoleEnc --> Core_WriteSync
    Core_MemoryEnc --> Core_WriteSync
    Core_ReflectedEnc --> Core_WriteSync
    Core_WriteSync --> IO_SinkRoot
    Core_BufferedWS --> IO_BufferPoolInternal
    Core_BufferedWS --> IO_SinkRoot

    %% IO & Buffer flow
    IO_SinkRoot --> IO_WriterRoot
    IO_SinkRoot --> IO_ZapIOWriter
    IO_SinkRoot --> IO_BufferTop

    %% Utilities feeding into Core and IO
    Util_Color --> Core_ConsoleEnc
    Util_Pool --> Core_BufferedWS
    Util_Pool --> IO_BufferPoolInternal
    Util_Stack --> Core_Core
    Util_Exit --> Core_Core
    Util_TestUtils --> Ext_TestLogger
    Util_TestUtils --> Ext_Observer

    %% Extensions integration
    Ext_HTTP --> API_Logger
    Ext_gRPC --> API_Logger
    Ext_TestLogger --> API_Logger
    Ext_Observer --> API_Logger
    Exp_Field --> API_Field
    Exp_SLog --> API_Sugar

    %% Click Events for Public API
    click API_Logger "https://github.com/go-uber/zap/blob/master/logger.go"
    click API_Sugar "https://github.com/go-uber/zap/blob/master/sugar.go"
    click API_GlobalLogger "https://github.com/go-uber/zap/blob/master/global.go"
    click API_Flag "https://github.com/go-uber/zap/blob/master/flag.go"
    click API_Config "https://github.com/go-uber/zap/blob/master/config.go"
    click API_Config "https://github.com/go-uber/zap/blob/master/options.go"
    click API_Field "https://github.com/go-uber/zap/blob/master/field.go"
    click API_Field "https://github.com/go-uber/zap/blob/master/array.go"
    click API_Error "https://github.com/go-uber/zap/blob/master/error.go"
    click API_Sink "https://github.com/go-uber/zap/blob/master/sink.go"
    click API_EncoderSel "https://github.com/go-uber/zap/blob/master/encoder.go"
    click API_WriterHelper "https://github.com/go-uber/zap/blob/master/writer.go"

    %% Click Events for Core
    click Core_Core "https://github.com/go-uber/zap/blob/master/zapcore/core.go"
    click Core_Entry "https://github.com/go-uber/zap/blob/master/zapcore/entry.go"
    click Core_FieldCore "https://github.com/go-uber/zap/blob/master/zapcore/field.go"
    click Core_Hook "https://github.com/go-uber/zap/blob/master/zapcore/hook.go"
    click Core_Sampler "https://github.com/go-uber/zap/blob/master/zapcore/sampler.go"
    click Core_Tee "https://github.com/go-uber/zap/blob/master/zapcore/tee.go"
    click Core_JSONEnc "https://github.com/go-uber/zap/blob/master/zapcore/json_encoder.go"
    click Core_ConsoleEnc "https://github.com/go-uber/zap/blob/master/zapcore/console_encoder.go"
    click Core_MemoryEnc "https://github.com/go-uber/zap/blob/master/zapcore/memory_encoder.go"
    click Core_ReflectedEnc "https://github.com/go-uber/zap/blob/master/zapcore/reflected_encoder.go"
    click Core_WriteSync "https://github.com/go-uber/zap/blob/master/zapcore/write_syncer.go"
    click Core_BufferedWS "https://github.com/go-uber/zap/blob/master/zapcore/buffered_write_syncer.go"

    %% Click Events for IO & Buffer
    click IO_BufferPoolInternal "https://github.com/go-uber/zap/blob/master/internal/bufferpool/bufferpool.go"
    click IO_BufferTop "https://github.com/go-uber/zap/blob/master/buffer/buffer.go"
    click IO_BufferTop "https://github.com/go-uber/zap/blob/master/buffer/pool.go"
    click IO_ZapIOWriter "https://github.com/go-uber/zap/blob/master/zapio/writer.go"
    click IO_SinkRoot "https://github.com/go-uber/zap/blob/master/sink.go"
    click IO_WriterRoot "https://github.com/go-uber/zap/blob/master/writer.go"

    %% Click Events for Internal Utils
    click Util_Color "https://github.com/go-uber/zap/blob/master/internal/color/color.go"
    click Util_Exit "https://github.com/go-uber/zap/blob/master/internal/exit/exit.go"
    click Util_Pool "https://github.com/go-uber/zap/blob/master/internal/pool/pool.go"
    click Util_Stack "https://github.com/go-uber/zap/blob/master/internal/stacktrace/stack.go"

    %% Click Events for Extensions
    click Ext_HTTP "https://github.com/go-uber/zap/blob/master/http_handler.go"
    click Ext_gRPC "https://github.com/go-uber/zap/blob/master/zapgrpc/zapgrpc.go"
    click Ext_TestLogger "https://github.com/go-uber/zap/blob/master/zaptest/logger.go"
    click Ext_Observer "https://github.com/go-uber/zap/blob/master/zaptest/observer/observer.go"
    click Exp_Field "https://github.com/go-uber/zap/blob/master/exp/zapfield/zapfield.go"
    click Exp_SLog "https://github.com/go-uber/zap/blob/master/exp/zapslog/handler.go"

    %% Styles
    classDef public fill:#AEC6CF,stroke:#000,stroke-width:1px
    classDef core fill:#77DD77,stroke:#000,stroke-width:1px
    classDef io fill:#ffb347,stroke:#000,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef ext fill:#FF6961,stroke:#000,stroke-width:1px
    classDef exp fill:#FDFD96,stroke:#000,stroke-width:1px
```
