How vimcki/key-analyser works
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.