# gokselkucuksahin/zlog architecture

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

- Interactive diagram: https://gitdiagram.com/gokselkucuksahin/zlog
- Repository: https://github.com/gokselkucuksahin/zlog

## Overview

##### Project type and purpose
- Type: Go library for structured logging
- Purpose: Provide a standardized, extensible logging API and output pipeline for Go applications

##### File structure
- Top-level files:
– zlog.go: contains the main API (Logger type, methods, configuration)
– go.mod: module definition and dependencies
– Makefile / .goreleaser.yaml / GitHub workflows: build, test, release pipelines
- No “frontend” or “backend”—this is a library that gets imported into consumer code

##### README
- Very brief—its core promise is “standardized structured logging in go” with minimal overhead.

##### Main components
a. Consumer application
– Imports “github.com/yourorg/zlog”
– Calls zlog.NewLogger(), sets up fields/context
b. zlog API layer (zlog.go)
– Configuration object (log level, output format, timestamp options)
– Logger struct with methods (Debug, Info, Warn, Error, etc.)
c. Encoder / Formatter
– JSON encoder, text encoder, or custom encoder interface
– Implementations that turn structured events into byte streams
d. Output Sink(s)
– Stdout / Stderr
– Files (via io.Writer)
– Hooked external systems (e.g., remote HTTP endpoint, syslog)
e. Extension Points
– Hooks: before/after hooks that users can register (e.g., to add trace IDs)
– Custom encoders / sinks

##### Relationships and data flow
1. Application code → calls Logger.Method(...)
2. API layer:
- Gathers structured fields + message → builds Event object
- Passes Event to Encoder
3. Encoder: serializes Event → byte[] payload
4. Sink: writes payload to configured io.Writer or external service
5. Optional Hooks: can plug into steps 2–4 to enrich or filter events

##### Architectural patterns or principles
- Dependency Inversion: Logger depends on abstract Encoder and Sink interfaces
- Single Responsibility: separate components for event construction, encoding, and output
- Open/Closed: users can add new encoders or sinks without modifying core

##### Technologies / frameworks
- Go standard library (io.Writer, context)
- No external frameworks—zlog is zero-dependency
- Build & CI: Makefile, GoReleaser, GitHub Actions

##### Essential elements
- Component labels (e.g., “Logger”, “JSONEncoder”, “StdoutSink”)
- Interfaces vs. implementations (use stereotype labels like «interface»)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "External Application"
    App["Consumer Application"]:::external
  end

  subgraph "zlog Core Components"
    ZlogAPI["Logger API «interface»"]:::core
    Event["Event Builder"]:::core
    EncoderIface["Encoder Interface «interface»"]:::core
    SinkIface["Sink Interface «interface»"]:::core
    Hooks["Hooks/Extensions"]:::core
  end

  subgraph "Implementations"
    JSONEnc["JSON Encoder"]:::impl
    TextEnc["Text Encoder"]:::impl
    StdoutSink["Stdout Sink"]:::impl
    FileSink["File Sink"]:::impl
    HTTPHook["HTTP Hook Sink"]:::impl
  end

  subgraph "Utilities & CI/CD"
    GoMod["go.mod"]:::external
    Makef["Makefile"]:::external
    Gorel[".goreleaser.yaml"]:::external
    Workflow[".github/workflows/release.yml"]:::external
    Readme["README.md"]:::external
    Lic["LICENSE"]:::external
    GitIg[".gitignore"]:::external
    Dependabot[".github/dependabot.yml"]:::external
  end

  App -->|"calls NewLogger()"| ZlogAPI
  ZlogAPI -->|"builds" | Event
  Event -->|"passes to"| EncoderIface
  EncoderIface -->|"implemented by"| JSONEnc
  EncoderIface -->|"implemented by"| TextEnc
  Event -->|"passes to"| SinkIface
  SinkIface -->|"implemented by"| StdoutSink
  SinkIface -->|"implemented by"| FileSink
  SinkIface -->|"implemented by"| HTTPHook
  Hooks -->|"before/after"| Event
  Hooks -->|"before/after"| EncoderIface
  Hooks -->|"before/after"| SinkIface

  click ZlogAPI "https://github.com/gokselkucuksahin/zlog/blob/main/zlog.go"
  click EncoderIface "https://github.com/gokselkucuksahin/zlog/blob/main/zlog.go"
  click SinkIface "https://github.com/gokselkucuksahin/zlog/blob/main/zlog.go"
  click Hooks "https://github.com/gokselkucuksahin/zlog/blob/main/zlog.go"
  click GoMod "https://github.com/gokselkucuksahin/zlog/blob/main/go.mod"
  click Makef "https://github.com/gokselkucuksahin/zlog/tree/main/Makefile"
  click Gorel "https://github.com/gokselkucuksahin/zlog/blob/main/.goreleaser.yaml"
  click Workflow "https://github.com/gokselkucuksahin/zlog/blob/main/.github/workflows/release.yml"
  click Readme "https://github.com/gokselkucuksahin/zlog/blob/main/README.md"
  click Lic "https://github.com/gokselkucuksahin/zlog/tree/main/LICENSE"
  click GitIg "https://github.com/gokselkucuksahin/zlog/blob/main/.gitignore"
  click Dependabot "https://github.com/gokselkucuksahin/zlog/blob/main/.github/dependabot.yml"

  classDef core fill:#a8d1ff,stroke:#000,stroke-width:1px
  classDef impl fill:#b7f3a8,stroke:#000,stroke-width:1px
  classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px
```
