# botflux/pino-logfmt architecture

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

- Interactive diagram: https://gitdiagram.com/botflux/pino-logfmt
- Repository: https://github.com/botflux/pino-logfmt

## Overview

##### Project type and purpose
- This is a Node.js library and CLI tool (“pino-logfmt”) that plugs into the Pino logging framework. It transforms JSON‐structured Pino log events into logfmt‐formatted text, either as a programmatic transport or as a standalone CLI.

##### File structure
- src/bin.js – CLI entry point, parses arguments, invokes the transport
- src/transport.js – the core transport implementation for Pino
- src/tree-to-key-value.js – flattens nested objects into key/value pairs
- src/levels.js – maps numeric log levels to labels or custom levels
- src – all core logic lives here
- tests – unit tests for each module
- package.json, .github/workflows, demarcate build/test/publish steps
- typings/types.d.ts – TypeScript definitions (for consumers)

##### Extract architecture hints from the README
- Two modes of use:
– Programmatic: `pino({ transport: { target: "pino-logfmt", options: {…} } })`
– CLI: `node src/bin.js | pino-logfmt [flags]`
- Transform pipeline: raw Pino JSON → flatten nested fields → rename keys (snake_case) → format time → assemble logfmt string → output (stdout or file).

a. Input sources
– Pino logger (in‐process)
– STDIN (piped JSON logs for CLI)
b. Configuration/Options layer
– CLI flags or transport options object
c. Core transformation modules
– Levels module (map level numbers to labels)
– Tree‐to‐key‐value module (flatten nested metadata)
– Transport orchestrator (applies options, calls formatting functions)
d. Output sinks
– STDOUT (default)
– File (if `destination` option set)

##### Relationships and data flow
1. Application or shell emits a JSON log event.
2. The transport/bin receives the JSON.
3. JSON is parsed into an object.
4. Options are applied (flattenNestedObjects, convertToSnakeCase, formatTime, includeLevelLabel).
5. tree-to-key-value flattens nested structures.
6. levels module optionally injects or renames the level label.
7. Formatter builds a single logfmt string (key=value pairs).
8. Transport writes the string to its configured destination.

##### Architectural patterns and principles
- Pipeline pattern: each module transforms data before passing to the next.
- Single responsibility: each file handles one transformation concern.
- Plugin boundary: the transport implements Pino’s transport interface.
- CLI wrapper: separates argument parsing from core logic.

##### Essential elements
– Module names and file pointers (e.g., src/transport.js)
– Option flags mapping into branches in the pipeline
– Destinations (stdout, file) clearly called out

## Diagram (Mermaid)

```mermaid
graph TB
    %% Input Sources
    subgraph "Input Sources"
        Pino["Pino Logger (Programmatic)"]:::input
        CLI["CLI Entry Point\n(STDIN / Arg Parsing)"]:::input
    end

    %% Parsing & Configuration
    Parser["JSON Parser"]:::core
    Options["Options Router"]:::config

    %% Core Modules
    subgraph "Core Modules"
        Transport["Transport Orchestrator"]:::core
        Flatten["tree-to-key-value"]:::core
        Levels["levels"]:::core
        Formatter["Formatter"]:::core
    end

    %% Output Sinks
    subgraph "Output Sinks"
        Stdout["STDOUT"]:::output
        File["File (if destination set)"]:::output
    end

    %% Type Definitions
    subgraph "TypeScript Definitions"
        TypeDefs["typings/types.d.ts"]:::types
        BinDefs["src/bin.d.ts"]:::types
    end

    %% Infrastructure
    subgraph "Project Infrastructure"
        Package["package.json"]:::infra
        CI1[".github/workflows/node.js.yml"]:::infra
        CI2[".github/workflows/publish.yml"]:::infra
    end

    %% Quality / Tests
    subgraph "Quality (Unit Tests)"
        levelsSpec["tests/levels.spec.js"]:::tests
        transportSpec["tests/transport.spec.js"]:::tests
        treeSpec["tests/tree-to-kv.spec.js"]:::tests
    end

    %% Data Flow
    Pino -->|"1. emits JSON"| Parser
    CLI -->|"1. emits JSON"| Parser
    Parser -->|"3. parsed object"| Options
    Options -->|"4. apply options"| Transport
    Transport -->|"5. flatten nested"| Flatten
    Flatten -->|"6. map levels"| Levels
    Levels -->|"7. assemble logfmt"| Formatter
    Formatter -->|"8. write output"| Stdout
    Formatter -->|"8. write output"| File

    %% Click Events
    click CLI "https://github.com/botflux/pino-logfmt/blob/main/src/bin.js"
    click Transport "https://github.com/botflux/pino-logfmt/blob/main/src/transport.js"
    click Flatten "https://github.com/botflux/pino-logfmt/blob/main/src/tree-to-key-value.js"
    click Levels "https://github.com/botflux/pino-logfmt/blob/main/src/levels.js"
    click levelsSpec "https://github.com/botflux/pino-logfmt/blob/main/tests/levels.spec.js"
    click transportSpec "https://github.com/botflux/pino-logfmt/blob/main/tests/transport.spec.js"
    click treeSpec "https://github.com/botflux/pino-logfmt/blob/main/tests/tree-to-kv.spec.js"
    click TypeDefs "https://github.com/botflux/pino-logfmt/blob/main/typings/types.d.ts"
    click BinDefs "https://github.com/botflux/pino-logfmt/blob/main/src/bin.d.ts"
    click Package "https://github.com/botflux/pino-logfmt/blob/main/package.json"
    click CI1 "https://github.com/botflux/pino-logfmt/blob/main/.github/workflows/node.js.yml"
    click CI2 "https://github.com/botflux/pino-logfmt/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef input fill:#a6f3a6,stroke:#333,stroke-width:1px
    classDef core fill:#a6d2f3,stroke:#333,stroke-width:1px
    classDef config fill:#f3e76a,stroke:#333,stroke-width:1px
    classDef output fill:#f3b16a,stroke:#333,stroke-width:1px
    classDef tests fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef types fill:#d8a6f3,stroke:#333,stroke-width:1px
    classDef infra fill:#c2c2c2,stroke:#333,stroke-width:1px
```
