# kraanzu/smassh architecture

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

- Interactive diagram: https://gitdiagram.com/kraanzu/smassh
- Repository: https://github.com/kraanzu/smassh

## Overview

##### 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”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["__main__.py"]:::config
    end

    %% Core Logic Layer
    subgraph "Core Logic" 
        CP["ConfigParser"]:::core
        DP["DataParser"]:::core
        GP["Generic Parser"]:::core
        GEN["Text Generator"]:::core
        CONV["Converter"]:::core
        CSSG["CSS Generator"]:::core
        FIG["Figlet"]:::core
        STS["StatsTracker"]:::core
        TRK["Tracker"]:::core
        BUD["Buddy"]:::core
        HELP["HelpMenu"]:::core
    end

    %% Plugins Layer
    subgraph "Plugins"
        PLUG["add_language"]:::plugin
    end

    %% UI Layer
    subgraph "UI Layer"
        ED["Event Dispatcher"]:::ui
        TUI["TUI Runner"]:::ui
        subgraph Screens
            ABOUT["AboutScreen"]:::ui
            CONF["ConfirmScreen"]:::ui
            HELP_S["HelpScreen"]:::ui
            PAL_S["PaletteScreen"]:::ui
            RES_S["ResultScreen"]:::ui
            SET_S["SettingsScreen"]:::ui
            TYP_S["TypingScreen"]:::ui
        end
        subgraph Widgets
            BW["BaseWindow"]:::ui
            HDR["Header"]:::ui
            LAB["Label"]:::ui
            subgraph PaletteWidgets
                PAL_W["Palette"]:::ui
                PI["PaletteInput"]:::ui
                PL["PaletteList"]:::ui
                PO["PaletteOptions"]:::ui
            end
            subgraph ResultWidgets
                RS["ResultStrip"]:::ui
                VAL["Value"]:::ui
            end
            subgraph SettingsWidgets
                SO["Option"]:::ui
                SEP["Separator"]:::ui
                SOPT["SettingsOptions"]:::ui
                DO["DangerOptions"]:::ui
                SS["Strip"]:::ui
            end
            subgraph TypingWidgets
                CS["ConfigStrip"]:::ui
                SP["Space"]:::ui
                TICK["Ticker"]:::ui
            end
        end
        subgraph "CSS Themes"
            BASE_CSS["base.tcss"]:::config
            THEMES["themes/"]:::config
        end
    end

    %% Assets & Config
    subgraph "Assets & Config"
        IMGS["imgs/"]:::config
        PYPROJ["pyproject.toml"]:::config
        FLAKE["flake.nix & lock"]:::config
        PRE[".pre-commit-config.yaml"]:::config
        GHWF[".github/workflows/"]:::config
    end

    %% Relationships
    CLI -->|"start"| CP
    CP -->|"load corpora"| DP
    DP -->|"parse data"| GP
    GP -->|"generate text"| GEN
    GEN -->|"format text"| CONV
    CONV -->|"generate styles"| CSSG
    CSSG -->|"banner"| FIG
    GEN -->|"text"| TUI
    CSSG -->|"styles"| TUI
    FIG -->|"decor"| TUI

    TUI -->|"init events"| ED
    ED --> ABOUT
    ED --> CONF
    ED --> HELP_S
    ED --> PAL_S
    ED --> RES_S
    ED --> SET_S
    ED --> TYP_S

    TYP_S -->|"keystrokes"| TRK
    TRK --> STS
    STS -->|"stats"| RES_S

    PLUG -.-> CP
    PLUG -.-> TRK

    BASE_CSS --> TUI
    THEMES --> TUI

    IMGS --> CLI
    PYPROJ --> CLI
    FLAKE --> CLI
    PRE --> CLI
    GHWF --> CLI

    %% Click Events
    click CLI "https://github.com/kraanzu/smassh/blob/main/smassh/__main__.py"
    click CP "https://github.com/kraanzu/smassh/blob/main/smassh/src/parser/config_parser.py"
    click DP "https://github.com/kraanzu/smassh/blob/main/smassh/src/parser/data_parser.py"
    click GP "https://github.com/kraanzu/smassh/blob/main/smassh/src/parser/parser.py"
    click GEN "https://github.com/kraanzu/smassh/blob/main/smassh/src/generator.py"
    click CONV "https://github.com/kraanzu/smassh/blob/main/smassh/src/converter.py"
    click CSSG "https://github.com/kraanzu/smassh/blob/main/smassh/src/css_generator.py"
    click FIG "https://github.com/kraanzu/smassh/blob/main/smassh/src/figlet.py"
    click STS "https://github.com/kraanzu/smassh/blob/main/smassh/src/stats_tracker.py"
    click TRK "https://github.com/kraanzu/smassh/blob/main/smassh/src/tracker.py"
    click PLUG "https://github.com/kraanzu/smassh/blob/main/smassh/src/plugins/add_language.py"
    click BUD "https://github.com/kraanzu/smassh/blob/main/smassh/src/buddy.py"
    click HELP "https://github.com/kraanzu/smassh/blob/main/smassh/src/help_menu.py"
    click ED "https://github.com/kraanzu/smassh/blob/main/smassh/ui/events.py"
    click TUI "https://github.com/kraanzu/smassh/blob/main/smassh/ui/tui.py"
    click ABOUT "https://github.com/kraanzu/smassh/blob/main/smassh/ui/screens/about.py"
    click CONF "https://github.com/kraanzu/smassh/blob/main/smassh/ui/screens/confirm.py"
    click HELP_S "https://github.com/kraanzu/smassh/blob/main/smassh/ui/screens/help.py"
    click PAL_S "https://github.com/kraanzu/smassh/blob/main/smassh/ui/screens/palette.py"
    click RES_S "https://github.com/kraanzu/smassh/blob/main/smassh/ui/screens/result.py"
    click SET_S "https://github.com/kraanzu/smassh/blob/main/smassh/ui/screens/settings.py"
    click TYP_S "https://github.com/kraanzu/smassh/blob/main/smassh/ui/screens/typing.py"
    click BW "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/base_window.py"
    click HDR "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/header.py"
    click LAB "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/label.py"
    click PAL_W "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/palette/palette.py"
    click PI "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/palette/palette_input.py"
    click PL "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/palette/palette_list.py"
    click PO "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/palette/palette_options.py"
    click RS "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/result/result_strip.py"
    click VAL "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/result/value.py"
    click SO "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/settings/option.py"
    click SEP "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/settings/separator.py"
    click SOPT "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/settings/settings_options.py"
    click DO "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/settings/danger_options.py"
    click SS "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/settings/strip.py"
    click CS "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/typing/config_strip.py"
    click SP "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/typing/space.py"
    click TICK "https://github.com/kraanzu/smassh/blob/main/smassh/ui/widgets/typing/ticker.py"
    click BASE_CSS "https://github.com/kraanzu/smassh/blob/main/smassh/ui/css/base.tcss"
    click THEMES "https://github.com/kraanzu/smassh/tree/main/smassh/ui/css/themes/"
    click IMGS "https://github.com/kraanzu/smassh/tree/main/imgs/"
    click PYPROJ "https://github.com/kraanzu/smassh/blob/main/pyproject.toml"
    click FLAKE "https://github.com/kraanzu/smassh/blob/main/flake.nix"
    click PRE "https://github.com/kraanzu/smassh/blob/main/.pre-commit-config.yaml"
    click GHWF "https://github.com/kraanzu/smassh/tree/main/.github/workflows/"
    
    %% Styles
    classDef core fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef ui fill:#d9ead3,stroke:#333,stroke-width:1px
    classDef config fill:#f9cb9c,stroke:#333,stroke-width:1px
    classDef plugin fill:#d9d2e9,stroke:#333,stroke-width:1px
```
