# vimcki/key-analyser architecture

> Architecture diagram of the GitHub repository vimcki/key-analyser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vimcki/key-analyser
- Repository: https://github.com/vimcki/key-analyser

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is a **Rust CLI tool** (“Key-analyser”) that **generates a histogram of keypresses** from keypress logs produced by an external command pipeline (`xinput test-xi2 ...`). At runtime it also shells out to **`xmodmap -pke`** to map **keycode → human-readable key name**.

- **Runtime dataflow** (stdin/files → parse → normalize/map → aggregate → output)
- **External OS/tool dependencies** (xinput for data collection, xmodmap for mapping)
- **Where boundaries are** (your binary vs. external commands vs. user environment)

##### What the file tree implies about architecture
File tree:
- `Cargo.toml`, `Cargo.lock`: Rust crate; dependencies (if any) are declared here.
- `src/main.rs`: single-binary CLI; likely everything is in one module (no library crate separation).

##### What the README adds (runtime interactions)
From README:
- Input is keypress data gathered *outside* this tool (the `xinput ... | grep ... | awk ...` pipeline).
- The tool accepts **either file paths** or **stdin**.
- It calls **`xmodmap -pke`** underneath to build mapping for keycode→text.
- Output is a histogram (likely printed to stdout).

This means the most accurate architecture view is a **pipeline** plus **external process invocation**.

##### CLI / Argument Handler
- Determines mode: file paths vs stdin
- Possibly validates inputs

##### Input Reader
- Reads line-oriented records from stdin or file(s)
- Emits parsed raw tokens (or raw lines)

##### Log Parser
- Parses the expected record format from the pipeline (`print $9, $4` suggests two fields)
- Produces events like:
- `{ keycode, event_type (press/release), timestamp? }` (whatever exists in the log)

##### Keycode Mapper (X11 mapping adapter)
- Responsibility: call `xmodmap -pke`
- Parse its output
- Build a map: `keycode -> "KeyName"`
- Provide lookup to translate events

- Decides if histogram counts presses only, or both press/release
- Handles unknown keycodes (fallback label)
- Handles multiple representations/symbols from xmodmap

##### Histogram Aggregator
- Core: counts occurrences by key label
- Data structure: map/dictionary (HashMap in Rust)

##### Formatter / Output Renderer
- Sort order (by frequency? alphabetically?)
- Prints to stdout

- CLI → Input Reader → Log Parser → (optional Filter) → Mapper lookup → Aggregator → Formatter → stdout

- Mapper → (spawns) xmodmap → Mapper (returns mapping)

- Clear separation of concerns
- Where external coupling exists (`xmodmap`)
- The primary data transformations

##### Relationships and interactions to explicitly label
- “keypress record stream (keycode, event)”
- “mapping table (keycode→symbol)”
- “events (normalized)”
- “counts (symbol→frequency)”
- “histogram text”

**sync/async** nature where relevant:
- `xmodmap` call likely happens once at startup (annotate “startup dependency”)
- Input processing is streaming/iterative (annotate “stream processing”)

- Key-analyser: **Rust / Cargo binary**
- Mapping: **X11 tooling (`xmodmap`)**
- Data collection: **`xinput test-xi2`** (external; not in repo but part of the system workflow)
- OS: **Linux/X11 requirement** (implied by tooling)

##### Practical “don’t overthink it” checklist for this repo
To be maximally detailed without inventing things not in the repo:
- Split `main.rs` into the logical components above even if they’re functions.
- Both input modes (stdin vs file paths).
- `xmodmap -pke` as a spawned subprocess and the mapping table it produces.
- Histogram output as stdout.
- Upstream capture pipeline (`xinput...|grep...|awk...`) as an external producer feeding stdin/a file.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% CONTEXT (C4-style)
    %% =========================
    subgraph "System Context (Key-analyser on Linux/X11)"
        direction TB

        U["User / Operator"]:::actor

        subgraph "Key-analyser (Rust CLI binary)"
            direction TB
            KA["Key-analyser (Rust CLI)"]:::app
        end

        subgraph "Keypress Log Source (external)"
            direction TB
            PIPE["Live capture pipeline\nxinput test-xi2 ... \\| grep ... \\| awk ..."]:::external
            FILE["keylog.txt file"]:::io
        end

        subgraph "X11 / OS Tooling (external)"
            direction TB
            XMOD["xmodmap -pke\n(keycode→keysym)"]:::external
        end

        STDIN["stdin (pipe)"]:::io
        TERM["Terminal / stdout"]:::io

        U -->|"runs_cli_with_args_or_pipes_stdin"| KA
        PIPE -->|"keypress_records_stream\n(keycode,event_type)"| STDIN
        FILE -->|"keypress_records_file\n(keycode,event_type)"| KA
        STDIN -->|"line_stream"| KA

        KA -->|"executes_at_startup"| XMOD
        XMOD -->|"mapping_table\n(keycode→symbol)"| KA

        KA -->|"prints_histogram_text"| TERM
    end

    %% =========================
    %% RUNTIME / COMPONENTS (src/main.rs logical decomposition)
    %% =========================
    subgraph "Runtime / Components (implemented in src/main.rs)"
        direction TB

        subgraph "Process Boundary: key-analyser"
            direction TB

            CLI["CLI / Argument Handler\n(select stdin vs file paths)"]:::component
            IR["Input Reader\n(read stdin and/or files)"]:::component
            LP["Log Parser\n(extract keycode + event type)"]:::component
            NF["Normalizer / Filter\n(press vs release, unknown codes)"]:::component
            KM["Keycode Mapper (X11 adapter)\n(spawn xmodmap, parse output)"]:::component
            HA["Histogram Aggregator\n(HashMap: symbol→frequency)"]:::component
            FR["Formatter / Output Renderer\n(sort + print)"]:::component

            IN_STDIN["stdin stream"]:::io
            IN_FILES["file paths"]:::io
            OUT_STDOUT["stdout"]:::io
        end

        subgraph "External Command Boundary"
            direction TB
            XMOD2["xmodmap -pke subprocess"]:::external
        end

        %% In-process dataflow (stream processing)
        CLI -->|"selects_input_mode"| IR
        IN_STDIN -->|"lines"| IR
        IN_FILES -->|"open_read_files"| IR

        IR -->|"raw_lines"| LP
        LP -->|"events\n{keycode,event_type}"| NF
        NF -->|"normalized_events"| HA

        %% Mapping side-channel (startup dependency)
        KM -->|"spawns_and_reads_stdout"| XMOD2
        XMOD2 -->|"keycode→symbol_table"| KM

        %% Lookup during aggregation
        HA -->|"lookup_keycode"| KM
        KM -->|"symbol_or_fallback"| HA

        HA -->|"counts\nsymbol→frequency"| FR
        FR -->|"histogram_text"| OUT_STDOUT
    end

    %% Cargo metadata nodes (kept minimal but clickable)
    TOML["Cargo.toml\n(crate config)"]:::meta
    LOCK["Cargo.lock\n(resolved versions)"]:::meta
    TOML -.->|"build_metadata"| KA
    LOCK -.->|"lockfile"| KA

    %% =========================
    %% CLICK EVENTS (component_mapping)
    %% =========================
    click KA "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click CLI "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click IR "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click LP "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click KM "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click NF "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click HA "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click FR "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click IN_STDIN "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click IN_FILES "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"
    click OUT_STDOUT "https://github.com/vimcki/key-analyser/blob/master/src/main.rs"

    click PIPE "https://github.com/vimcki/key-analyser/blob/master/README.md"
    click XMOD "https://github.com/vimcki/key-analyser/blob/master/README.md"
    click XMOD2 "https://github.com/vimcki/key-analyser/blob/master/README.md"
    click FILE "https://github.com/vimcki/key-analyser/blob/master/README.md"
    click STDIN "https://github.com/vimcki/key-analyser/blob/master/README.md"
    click TERM "https://github.com/vimcki/key-analyser/blob/master/README.md"
    click U "https://github.com/vimcki/key-analyser/blob/master/README.md"

    click TOML "https://github.com/vimcki/key-analyser/blob/master/Cargo.toml"
    click LOCK "https://github.com/vimcki/key-analyser/blob/master/Cargo.lock"

    %% =========================
    %% STYLES (color critical)
    %% =========================
    classDef actor fill:#FFF3CD,stroke:#B08900,stroke-width:1px,color:#1f1f1f
    classDef app fill:#D6EAF8,stroke:#1B4F72,stroke-width:1.5px,color:#0b2239
    classDef component fill:#E8F8F5,stroke:#117A65,stroke-width:1px,color:#0b2b26
    classDef external fill:#FADBD8,stroke:#922B21,stroke-width:1.5px,color:#3b0d0a
    classDef io fill:#F2F3F4,stroke:#5D6D7E,stroke-width:1px,color:#111
    classDef meta fill:#EAECEE,stroke:#626567,stroke-width:1px,color:#111
```
