How kraanzu/smassh works
Project Type and Purpose
• Smassh is a single‐binary, command‐line TUI application written in Python.
• Purpose: Provide a monkey-type-inspired typing test via a terminal UI, with themes, settings, plugins and real-time stats.
File Structure
• Top-level module “smassh” with:
• __main__.py: CLI entrypoint
• src/: Core logic and business modules (buddy, converter, css_generator, figlet, generator, help_menu, parser, plugins, stats_tracker, tracker)
• ui/: UI layer – event loop (tui.py), screens, widgets, and CSS/theme files
• Configuration/build:
• pyproject.toml, flake.nix, pre-commit, GitHub workflows
• Assets: imgs/ for banners and preview images
Review README for Insights
• Confirms use-cases (time/word modes, themes, plugins).
• No external services or databases—everything runs in-process.
Main Components and Their Roles
a. CLI Layer
• __main__.py parses command-line flags, loads settings, and starts the TUI runner.
b. Core Logic Layer
• Parser (config_parser, data_parser): load user config & text corpora
• Generator: assemble the text to be typed
• Converter/CSS Generator/Figlet: prepare decorative text and styles
• StatsTracker/Tracker: record keystrokes, calculate WPM/accuracy
• Plugins: add language support or “cursor buddy”
c. UI Layer
• tui.py: main event loop
• screens: about, confirm, help, palette, result, settings, typing
• widgets: reusable UI elements (headers, labels, palettes, result strips, settings options, typing ticker)
d. Assets & Config
• imgs/: banners/screenshots
• Configuration files for linters, build, CI
Relationships & Data Flows
• CLI → Core Logic → UI
• On start: CLI reads flags → config_parser → data_parser → Generator produces test
• UI loads CSS → renders initial screen → user input events propagate via events.py to Tracker and StatsTracker
• StatsTracker feeds real-time updates back into UI screens/widgets
• Plugins hook into parsing or typing events (e.g., add_language)
• After test completes, UI calls result screen with stats from StatsTracker
Architectural Patterns & Principles
• Layered (CLI → Core → UI)
• Modular separation: parsing, generation, tracking, UI components, theming
• Plugin extension points under src/plugins
• MVC-like: Generator/Tracker = “Model,” tui.py/screens/widgets = “View/Controller”