# nkmr-jp/zl architecture

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

- Interactive diagram: https://gitdiagram.com/nkmr-jp/zl
- Repository: https://github.com/nkmr-jp/zl

## Overview

##### Project type and purpose
- This is an open-source Go logging library (“zl”) built as a wrapper around Uber’s zap.
- Its goal is to provide developer-friendly log formatting (console, JSON, rotated files) and rich features (error aggregation, stack traces, custom fields).

##### File structure
- Top-level files:
- zl.go, logger.go, rotate.go, pretty.go, options.go, field.go – core package source files
- *_test.go – unit tests for each module
- Makefile, .github/workflows, go.mod, go.sum, CI configs – build, test, and release orchestration
- examples/ directory: demonstrates integration in various contexts (basic app, HTTP server, Google Cloud Functions)
- testdata/: sample JSONL logs used by tests

##### README for additional insights
- Describes four main output strategies: PrettyOutput, ConsoleOutput, FileOutput, ConsoleAndFileOutput
- Shows initialization steps (SetLevel, SetOmitKeys, Init, Sync) and usage patterns (Info, Warn, Err)
- Mentions underlying dependency on zap and log‐file rotation support

##### Main components of the system
a. Public API layer (zl package)
– Init(), Sync(), SetLevel(), SetOmitKeys(), Info(), Warn(), Debug(), Err()
b. Configuration & options
– Options struct, default values, keys to omit
c. Output strategy implementations
– PrettyOutput
– ConsoleOutput
– FileOutput (incorporating rotate.go)
– ConsoleAndFileOutput
d. Underlying zap core
– zap.Logger, zapcore.Core, zap.Fields
e. External outputs/services
– Stdout/stderr (console)
– Log file with rotation
– Third-party log collectors (e.g. Google Cloud Logging)

##### Relationships and interactions
- The consumer calls Public API → zl package
- zl package reads configuration & selects one OutputStrategy
- Strategy creates/configures a zap.Logger instance
- Calls to Info/Err/etc. flow into zapcore, then out to destinations: console and/or file
- rotate.go handles file rotation under the FileOutput strategy
- Examples (in examples/) act as external clients showing integration

##### Architectural patterns and design principles
- Strategy pattern for pluggable output strategies
- Configuration-driven initialization
- Wrapper/facade over zap to simplify and standardize logging calls
- Separation of concerns: formatting (pretty vs JSON) separated from output (console vs file)

##### Technologies, frameworks, and libraries
- Go (golang) modules
- zap (Uber’s high-performance logger)
- lumberjack or custom rotate.go for file rotation
- GitHub Actions for CI/CD
- jq recommended for JSON log filtering

## Diagram (Mermaid)

```mermaid
graph TD
    Consumer["Consumer Application"]:::external
    Consumer -->|"calls"| PublicAPI

    PublicAPI["zl Public API\n(Init, Sync, SetLevel,\nSetOmitKeys, Info, Warn,\nDebug, Err)"]:::api
    click PublicAPI "https://github.com/nkmr-jp/zl/blob/main/zl.go"
    click PublicAPI "https://github.com/nkmr-jp/zl/blob/main/logger.go"

    PublicAPI -->|"reads"| Config
    Config["Configuration & Options"]:::api
    click Config "https://github.com/nkmr-jp/zl/blob/main/options.go"

    Config -->|"defines"| FieldDefs
    FieldDefs["Field Definitions"]:::api
    click FieldDefs "https://github.com/nkmr-jp/zl/blob/main/field.go"

    Config -->|"selects"| Selector
    Selector["Strategy Selector"]:::api

    subgraph "Output Strategies"
        PrettyOutput["PrettyOutput"]:::strategy
        click PrettyOutput "https://github.com/nkmr-jp/zl/blob/main/pretty.go"

        ConsoleOutput["ConsoleOutput"]:::strategy

        FileOutput["FileOutput"]:::strategy
        click FileOutput "https://github.com/nkmr-jp/zl/blob/main/rotate.go"

        ConsoleAndFile["ConsoleAndFileOutput"]:::strategy
    end

    Selector -->|"uses"| PrettyOutput
    Selector -->|"uses"| ConsoleOutput
    Selector -->|"uses"| FileOutput
    Selector -->|"uses"| ConsoleAndFile

    PrettyOutput -->|"formats & writes"| ZapCore
    ConsoleOutput -->|"formats & writes"| ZapCore
    FileOutput -->|"formats & writes"| ZapCore
    ConsoleAndFile -->|"formats & writes"| ZapCore

    ZapCore["zap Core\n(zap.Logger,\nzapcore.Core)"]:::core

    ZapCore -->|"writes"| ConsoleSink
    ZapCore -->|"writes"| FileSink
    ZapCore -->|"writes"| CloudSink

    ConsoleSink["Console (stdout/stderr)"]:::sink
    FileSink["Log File (rotated)"]:::sink
    CloudSink["Cloud Logging Endpoint"]:::sink

    subgraph "Extras"
        Examples["Examples"]:::external
        click Examples "https://github.com/nkmr-jp/zl/tree/main/examples/"

        TestData["Test Data Samples"]:::external
        click TestData "https://github.com/nkmr-jp/zl/tree/main/testdata/"

        Tests["Unit Tests"]:::external
        click Tests "https://github.com/nkmr-jp/zl/blob/main/pretty_test.go"
        click Tests "https://github.com/nkmr-jp/zl/blob/main/rotate_test.go"
        click Tests "https://github.com/nkmr-jp/zl/blob/main/options_test.go"
        click Tests "https://github.com/nkmr-jp/zl/blob/main/field_test.go"
        click Tests "https://github.com/nkmr-jp/zl/blob/main/logger_test.go"

        ModuleDef["Module & Dependencies"]:::external
        click ModuleDef "https://github.com/nkmr-jp/zl/blob/main/go.mod"
        click ModuleDef "https://github.com/nkmr-jp/zl/blob/main/go.sum"

        CI["Build & CI Orchestration"]:::external
        click CI "https://github.com/nkmr-jp/zl/tree/main/Makefile"
        click CI "https://github.com/nkmr-jp/zl/tree/main/.github/workflows/"
    end

    classDef api fill:#a0c4ff,stroke:#0366d6,color:#000
    classDef strategy fill:#d4f4dd,stroke:#2d6a4f,color:#000
    classDef core fill:#e0e0e0,stroke:#666,color:#000
    classDef sink fill:#ffe5b4,stroke:#d97706,color:#000
    classDef external fill:#f0f0f0,stroke:#444,color:#000
```
