# tallpress/zap architecture

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

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

## Overview

##### Main Components

a) Core Logging Components:
- Logger (Primary fast path)
- SugaredLogger (Convenience wrapper)
- ZapCore (The underlying implementation)
- Encoders (JSON and Console)

b) Supporting Systems:
- Buffer Pool System
- Field System
- Level Management
- Sampling System

##### Architectural Layers (from top to bottom)

Layer 1 - Public APIs:
- Global functions and configuration options

Layer 2 - Core Processing:
- ZapCore interface implementation
- Entry processing pipeline
- Level filtering
- Hook system

Layer 3 - Encoding Layer:
- JSON Encoder
- Console Encoder
- Memory Encoder (for testing)

Layer 4 - Output Layer:
- WriteSyncer interface
- Buffer management
- Output synchronization

##### Key Relationships to Highlight

- Data flow from Logger → ZapCore → Encoder → WriteSyncer
- Buffer pool interactions
- Field encoding paths
- Sampling decision flow

##### Additional Details

Callouts for:
- Zero-allocation paths
- Goroutine-safe components
- Sampling decision points
- Configuration options

##### Testing Infrastructure

In a separate section:
- Observer pattern for testing
- Timeout mechanisms
- Test helpers

##### The buffer management and pooling mechanisms

Keep the focus on the performance-critical paths while showing how the convenience layers (like SugaredLogger) build on top of the core system.

This structure will effectively communicate both the architectural sophistication and the performance-focused design of Zap.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Public_APIs
        Logger["Logger (Fast Path)"]
        Sugar["SugaredLogger (Convenience)"]
        Global["Global Functions"]
        Config["Configuration"]
    end

    subgraph Core_Processing
        ZapCore["ZapCore Interface"]
        Entry["Entry Processing"]
        Level["Level Management"]
        Hook["Hook System"]
        Field["Field System"]
        Sample["Sampling System"]
    end

    subgraph Encoding_Layer
        Encoder["Encoder Interface"]
        JSON["JSON Encoder"]
        Console["Console Encoder"]
        Memory["Memory Encoder"]
    end

    subgraph Output_Layer
        WriteSyncer["WriteSyncer Interface"]
        BufferMgmt["Buffer Management"]
        BufferPool["Buffer Pool"]
    end

    subgraph Testing
        TestInfra["Testing Infrastructure"]
        Observer["Observer Pattern"]
    end

    %% Relationships
    Logger --> ZapCore
    Sugar --> Logger
    Global --> Logger
    Config --> Logger

    ZapCore --> Entry
    ZapCore --> Level
    ZapCore --> Hook
    ZapCore --> Field
    ZapCore --> Sample

    Entry --> Encoder
    Encoder --> JSON
    Encoder --> Console
    Encoder --> Memory

    JSON --> WriteSyncer
    Console --> WriteSyncer
    Memory --> WriteSyncer

    WriteSyncer --> BufferMgmt
    BufferMgmt --> BufferPool

    TestInfra --> Observer
    Observer --> ZapCore

    %% Styling
    classDef core fill:#2374ab
    classDef perf fill:#57a773
    classDef ext fill:#ffc857
    classDef test fill:#929292

    %% Apply styles
    class Logger,ZapCore,Entry core
    class BufferPool,BufferMgmt,Sample perf
    class Hook,Encoder ext
    class TestInfra,Observer,Memory test

    %% Click events
    click Logger "https://github.com/tallpress/zap/blob/master/logger.go"
    click Sugar "https://github.com/tallpress/zap/blob/master/sugar.go"
    click ZapCore "https://github.com/tallpress/zap/blob/master/zapcore/core.go"
    click JSON "https://github.com/tallpress/zap/blob/master/zapcore/json_encoder.go"
    click Console "https://github.com/tallpress/zap/blob/master/zapcore/console_encoder.go"
    click BufferPool "https://github.com/tallpress/zap/blob/master/buffer/pool.go"
    click BufferMgmt "https://github.com/tallpress/zap/blob/master/buffer/buffer.go"
    click Field "https://github.com/tallpress/zap/blob/master/zapcore/field.go"
    click Level "https://github.com/tallpress/zap/blob/master/zapcore/level.go"
    click Sample "https://github.com/tallpress/zap/blob/master/zapcore/sampler.go"
    click Encoder "https://github.com/tallpress/zap/blob/master/zapcore/encoder.go"
    click Hook "https://github.com/tallpress/zap/blob/master/zapcore/hook.go"
    click TestInfra "https://github.com/tallpress/zap/tree/master/zaptest/"
    click Observer "https://github.com/tallpress/zap/tree/master/zaptest/observer/"
    click Entry "https://github.com/tallpress/zap/blob/master/zapcore/entry.go"
    click WriteSyncer "https://github.com/tallpress/zap/blob/master/zapcore/write_syncer.go"
    click Memory "https://github.com/tallpress/zap/blob/master/zapcore/memory_encoder.go"
    click Global "https://github.com/tallpress/zap/blob/master/global.go"
    click Config "https://github.com/tallpress/zap/blob/master/config.go"

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Performance Systems"]:::perf
        L3["Extension Points"]:::ext
        L4["Testing Components"]:::test
    end
```
