# hardysimpson/zlog architecture

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

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

## Overview

##### Project Type and Purpose
- zlog is an open‑source, pure C logging library providing high‑performance, thread‑safe, flexible logging for C applications. It offers a log4j‑like model (categories, formats, rules) without external dependencies beyond POSIX (and optional Win32 support). The project includes core library code (src/), configuration parsing, platform abstraction, utility data structures, build scripts, packaging (cpack/), documentation (doc/), tests (test/), and helper tools (tools/).

##### File Structure Analysis
- Top‐level: BUILD.bazel, CMakeLists.txt, Makefile, README.md, LICENSE, INSTALL, TODO, Changelog
- Configuration/build: cmake/, cpack/, zlog.spec
- Core library: src/ (modules for configuration, categories, rules, formatting, buffering, rotation, threading, platform)
- Utilities: src/zc_*.c, zc_arraylist, zc_hashtable, zc_util, zc_profile, zc_xplatform
- Tests: test/ (unit tests, fuzzers, config scenarios)
- Tools: tools/mk_targz.sh
- Documentation: doc/ (User’s guide, GettingStarted, examples)

##### Core Components and Their Interactions
a. zlog API Layer
- zlog_init(cfg_path)
- zlog_get_category(name) → zlog_category_t*
- zlog_<level>(category, fmt, …)
- zlog_fini()
b. Configuration Module
- conf.c / conf.h: parse zlog.conf into in‑memory structures: formats, rules, categories
c. Category & Rule Management
- category.c / category_table.c: manage zlog_category_t instances
- rule.c / record_table.c: match category+level to output destinations and formats
d. Formatting Engine
- format.c: parse format strings (e.g., “%m%n”) and apply to log events
e. Event / Record Pipeline
- event.c / record.c: represent a log invocation as an event record
- zlog_info/debug → event → format → record
f. Output Modules (Appenders)
- stdout/stderr, file (with rotater.c for size/time rotation), syslog, user-defined callback
g. Concurrency & Safety
- thread.c: thread‑local data (MDC support)
- lockfile.c: file locking for process‑safe rotation
- zc_xplatform.c / zlog_win.c: OS abstraction (POSIX vs Windows)
h. Utilities
- zc_arraylist, zc_hashtable: in‑memory data structures
- zc_profile: performance counters
- zc_util: miscellaneous helpers
i. Build & Packaging
- CMake/Bazel/Make: build configurations, toolchain support
- cpack/: packaging scripts for RPM/DEB
- zlog.spec: spec file for RPM build
j. Testing & Validation
- test/: unit tests covering each module, fuzzers for init, test harness scripts

##### Architectural Patterns & Design Principles
- Modular pipeline architecture: API → Config → Event → Format → Output
- Separation of concerns: parsing vs storage vs formatting vs output vs rotation
- Plugin‑like output destinations: each appender implements a common interface
- Data structures abstracted into zc_* utilities for reuse
- Thread‑safe and process‑safe design (locks, thread‑local contexts)
- Platform abstraction layer for cross‑OS support

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Modules
    subgraph "API Layer"
        direction TB
        zlog_c["zlog.c"]:::runtime
        zlog_h["zlog.h"]:::runtime
        zlog_chk["zlog-chk-conf.c"]:::runtime
    end

    subgraph "Configuration Parser"
        direction TB
        conf_c["conf.c"]:::runtime
        conf_h["conf.h"]:::runtime
    end

    subgraph "Category Management"
        direction TB
        cat_c["category.c"]:::runtime
        cat_h["category.h"]:::runtime
        cat_tab_c["category_table.c"]:::runtime
        cat_tab_h["category_table.h"]:::runtime
    end

    subgraph "Rule Management"
        direction TB
        rule_c["rule.c"]:::runtime
        rule_h["rule.h"]:::runtime
        rec_tab_c["record_table.c"]:::runtime
        rec_tab_h["record_table.h"]:::runtime
    end

    subgraph "Event/Record Pipeline"
        direction TB
        event_c["event.c"]:::runtime
        event_h["event.h"]:::runtime
        record_c["record.c"]:::runtime
        record_h["record.h"]:::runtime
    end

    subgraph "Formatting Engine"
        direction TB
        format_c["format.c"]:::runtime
        format_h["format.h"]:::runtime
    end

    subgraph "Output Appenders & Rotation"
        direction TB
        buf_c["buf.c"]:::runtime
        buf_h["buf.h"]:::runtime
        rotater_c["rotater.c"]:::runtime
        rotater_h["rotater.h"]:::runtime
        spec_c["spec.c"]:::runtime
        spec_h["spec.h"]:::runtime
        lockfile_c["lockfile.c"]:::runtime
        lockfile_h["lockfile.h"]:::runtime
    end

    subgraph "Concurrency & Platform Abstraction"
        direction TB
        thread_c["thread.c"]:::runtime
        thread_h["thread.h"]:::runtime
        mdc_c["mdc.c"]:::runtime
        mdc_h["mdc.h"]:::runtime
        xplat_h["zc_xplatform.h"]:::runtime
        win_c["zlog_win.c"]:::runtime
        win_h["zlog_win.h"]:::runtime
    end

    subgraph "Logging Levels"
        direction TB
        level_c["level.c"]:::runtime
        level_h["level.h"]:::runtime
        level_list_c["level_list.c"]:::runtime
        level_list_h["level_list.h"]:::runtime
    end

    %% Utilities
    subgraph "Utilities" 
        direction TB
        arr_c["zc_arraylist.c"]:::util
        arr_h["zc_arraylist.h"]:::util
        ht_c["zc_hashtable.c"]:::util
        ht_h["zc_hashtable.h"]:::util
        prof_c["zc_profile.c"]:::util
        prof_h["zc_profile.h"]:::util
        util_c["zc_util.c"]:::util
        util_h["zc_util.h"]:::util
        defs_h["zc_defs.h"]:::util
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        bazel["BUILD.bazel"]:::build
        makef["Makefile"]:::build
        cmakel["CMakeLists.txt"]:::build
        cmake_dir["cmake/"]:::build
        cpack_dir["cpack/"]:::build
        specfile["zlog.spec"]:::build
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        ug_en["UsersGuide-EN.lyx"]:::doc
        ug_cn["UsersGuide-CN.lyx"]:::doc
        gs_en["GettingStart-EN.txt"]:::doc
        gs_cn["GettingStart-CN.txt"]:::doc
        doc_conf["zlog.conf"]:::doc
        perf["performence.txt"]:::doc
    end

    %% Tests
    subgraph "Test Harness"
        direction TB
        test_cmakel["test/CMakeLists.txt"]:::test
        fuzzer["zlog_init_fuzzer.c"]:::test
        unit_tests["test/*.c"]:::test
        test_conf["test/*.conf"]:::test
        valsh["val.sh"]:::test
    end

    %% Tools
    subgraph "Tools"
        direction TB
        mk_tgz["mk_targz.sh"]:::tool
    end

    %% Data Flows
    zlog_c -->|"invoke zlog_init()"| conf_c
    conf_c -->|"populate tables"| cat_tab_c
    cat_tab_c -->|"create categories"| cat_c
    cat_c --> rule_c
    rule_c --> rec_tab_c
    zlog_c -->|"invoke zlog_info()"| event_c
    event_c --> record_c
    record_c -->|"apply format"| format_c
    format_c --> buf_c
    buf_c --> rotater_c
    rotater_c --> lockfile_c
    spec_c --> buf_c
    lockfile_c --> buf_c
    thread_c --> event_c
    mdc_c --> event_c
    xplat_h --> thread_c
    xplat_h --> lockfile_c
    level_c --> event_c

    %% Click Events
    click zlog_c "https://github.com/hardysimpson/zlog/blob/master/src/zlog.c"
    click zlog_h "https://github.com/hardysimpson/zlog/blob/master/src/zlog.h"
    click zlog_chk "https://github.com/hardysimpson/zlog/blob/master/src/zlog-chk-conf.c"
    click conf_c "https://github.com/hardysimpson/zlog/blob/master/src/conf.c"
    click conf_h "https://github.com/hardysimpson/zlog/blob/master/src/conf.h"
    click cat_c "https://github.com/hardysimpson/zlog/blob/master/src/category.c"
    click cat_h "https://github.com/hardysimpson/zlog/blob/master/src/category.h"
    click cat_tab_c "https://github.com/hardysimpson/zlog/blob/master/src/category_table.c"
    click cat_tab_h "https://github.com/hardysimpson/zlog/blob/master/src/category_table.h"
    click rule_c "https://github.com/hardysimpson/zlog/blob/master/src/rule.c"
    click rule_h "https://github.com/hardysimpson/zlog/blob/master/src/rule.h"
    click rec_tab_c "https://github.com/hardysimpson/zlog/blob/master/src/record_table.c"
    click rec_tab_h "https://github.com/hardysimpson/zlog/blob/master/src/record_table.h"
    click format_c "https://github.com/hardysimpson/zlog/blob/master/src/format.c"
    click format_h "https://github.com/hardysimpson/zlog/blob/master/src/format.h"
    click event_c "https://github.com/hardysimpson/zlog/blob/master/src/event.c"
    click event_h "https://github.com/hardysimpson/zlog/blob/master/src/event.h"
    click record_c "https://github.com/hardysimpson/zlog/blob/master/src/record.c"
    click record_h "https://github.com/hardysimpson/zlog/blob/master/src/record.h"
    click buf_c "https://github.com/hardysimpson/zlog/blob/master/src/buf.c"
    click buf_h "https://github.com/hardysimpson/zlog/blob/master/src/buf.h"
    click rotater_c "https://github.com/hardysimpson/zlog/blob/master/src/rotater.c"
    click rotater_h "https://github.com/hardysimpson/zlog/blob/master/src/rotater.h"
    click spec_c "https://github.com/hardysimpson/zlog/blob/master/src/spec.c"
    click spec_h "https://github.com/hardysimpson/zlog/blob/master/src/spec.h"
    click lockfile_c "https://github.com/hardysimpson/zlog/blob/master/src/lockfile.c"
    click lockfile_h "https://github.com/hardysimpson/zlog/blob/master/src/lockfile.h"
    click thread_c "https://github.com/hardysimpson/zlog/blob/master/src/thread.c"
    click thread_h "https://github.com/hardysimpson/zlog/blob/master/src/thread.h"
    click mdc_c "https://github.com/hardysimpson/zlog/blob/master/src/mdc.c"
    click mdc_h "https://github.com/hardysimpson/zlog/blob/master/src/mdc.h"
    click xplat_h "https://github.com/hardysimpson/zlog/blob/master/src/zc_xplatform.h"
    click win_c "https://github.com/hardysimpson/zlog/blob/master/src/zlog_win.c"
    click win_h "https://github.com/hardysimpson/zlog/blob/master/src/zlog_win.h"
    click arr_c "https://github.com/hardysimpson/zlog/blob/master/src/zc_arraylist.c"
    click arr_h "https://github.com/hardysimpson/zlog/blob/master/src/zc_arraylist.h"
    click ht_c "https://github.com/hardysimpson/zlog/blob/master/src/zc_hashtable.c"
    click ht_h "https://github.com/hardysimpson/zlog/blob/master/src/zc_hashtable.h"
    click prof_c "https://github.com/hardysimpson/zlog/blob/master/src/zc_profile.c"
    click prof_h "https://github.com/hardysimpson/zlog/blob/master/src/zc_profile.h"
    click util_c "https://github.com/hardysimpson/zlog/blob/master/src/zc_util.c"
    click util_h "https://github.com/hardysimpson/zlog/blob/master/src/zc_util.h"
    click defs_h "https://github.com/hardysimpson/zlog/blob/master/src/zc_defs.h"
    click level_c "https://github.com/hardysimpson/zlog/blob/master/src/level.c"
    click level_h "https://github.com/hardysimpson/zlog/blob/master/src/level.h"
    click level_list_c "https://github.com/hardysimpson/zlog/blob/master/src/level_list.c"
    click level_list_h "https://github.com/hardysimpson/zlog/blob/master/src/level_list.h"
    click bazel "https://github.com/hardysimpson/zlog/blob/master/BUILD.bazel"
    click makef "https://github.com/hardysimpson/zlog/tree/master/Makefile"
    click cmakel "https://github.com/hardysimpson/zlog/blob/master/CMakeLists.txt"
    click cmake_dir "https://github.com/hardysimpson/zlog/tree/master/cmake/"
    click cpack_dir "https://github.com/hardysimpson/zlog/tree/master/cpack/"
    click specfile "https://github.com/hardysimpson/zlog/blob/master/zlog.spec"
    click ug_en "https://github.com/hardysimpson/zlog/blob/master/doc/UsersGuide-EN.lyx"
    click ug_cn "https://github.com/hardysimpson/zlog/blob/master/doc/UsersGuide-CN.lyx"
    click gs_en "https://github.com/hardysimpson/zlog/blob/master/doc/GettingStart-EN.txt"
    click gs_cn "https://github.com/hardysimpson/zlog/blob/master/doc/GettingStart-CN.txt"
    click doc_conf "https://github.com/hardysimpson/zlog/blob/master/doc/zlog.conf"
    click perf "https://github.com/hardysimpson/zlog/blob/master/doc/performence.txt"
    click test_cmakel "https://github.com/hardysimpson/zlog/blob/master/test/CMakeLists.txt"
    click fuzzer "https://github.com/hardysimpson/zlog/blob/master/test/fuzzers/zlog_init_fuzzer.c"
    click unit_tests "https://github.com/hardysimpson/zlog/blob/master/test/*.c"
    click test_conf "https://github.com/hardysimpson/zlog/blob/master/test/*.conf"
    click valsh "https://github.com/hardysimpson/zlog/blob/master/test/val.sh"
    click mk_tgz "https://github.com/hardysimpson/zlog/blob/master/tools/mk_targz.sh"

    %% Styles
    classDef runtime fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef util fill:#98FB98,stroke:#333,stroke-width:1px
    classDef build fill:#FFA500,stroke:#333,stroke-width:1px
    classDef test fill:#FFD700,stroke:#333,stroke-width:1px
    classDef doc fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef tool fill:#E6E6FA,stroke:#333,stroke-width:1px
```
