# 0x4133/snaklonger architecture

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

- Interactive diagram: https://gitdiagram.com/0x4133/snaklonger
- Repository: https://github.com/0x4133/snaklonger

## Overview

##### Project type and purpose
- This is a small CLI‐based Python utility (“Text Expander”) that hooks into OS keyboard events, watches what the user types, and replaces user‐defined abbreviations with full text snippets in real time.
- It is not a multi‐tier web app or microservice—it’s a single process script with a few logical modules.

##### File structure
- Top‐level files:
– main.py / main2.py: two entry‐point scripts (variants) containing the core logic
– expansions.txt: plain text datastore of “abbreviation:expansion” mappings
– longerPS.ps1: optional PowerShell helper script (likely for launching or installation)
– README.md: user documentation
- No “frontend” or “backend” folders—everything lives in one process
- No explicit tests or dev directories—focus is on runtime logic and data file

##### README for additional insights
- Libraries used: pynput (keyboard monitor & key simulation), pyperclip (clipboard ops)
- Flow described:
a. load_expansions() reads expansions.txt into an in‐memory dict
b. on_press() callback appends each key to a buffer
c. when space/enter detected, process_typed_text() checks buffer against abbreviations
d. if matched, simulate backspaces then “type” the expansion

##### Main components
a. OS Keyboard Events (external source)
b. Input Listener Module (pynput listener)
c. Typing Buffer Manager
d. Expansion Store Loader (reads expansions.txt → dict)
e. Text Processor (detect & match abbreviation)
f. Output Simulator (pynput to delete & type)
g. Clipboard Manager (pyperclip, if used for large text)
h. Optional Launcher (longerPS.ps1 or wrapper script)

##### Relationships & interactions
- OS Key Events → Input Listener → passes KeyEvent to Buffer Manager
- Buffer Manager accumulates characters until trigger key (space/enter) → invokes Text Processor
- Text Processor queries Expansion Store (in‐memory dict); if match found → calls Output Simulator
- Output Simulator issues backspace key events and types expansion (optionally via Clipboard Manager)
- Expansion Store Loader runs once at startup, then sits in memory

##### Highlighted architectural patterns & design principles
- Single‐process, event‐driven architecture (pynput’s callback model)
- Clear separation of concerns: I/O (keyboard), state management (buffer), data access (expansions.txt), processing logic, and output simulation
- Pluggable data source: expansions.txt can be replaced/extended without code changes

##### Detail
- Even for a small script, break it into these logical subcomponents
- Both the startup sequence (loading expansions) and the runtime loop (key events → expansion)
- Which third-party library implements each component (pynput, pyperclip)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    OSKeyboard["OS Keyboard Events"]:::external
    FileExp["expansions.txt"]:::datastore
    Launcher["Optional Launcher\n(longerPS.ps1)"]:::external
    Readme["User Documentation\n(README.md)"]:::external

    %% Main Process Container
    subgraph "Text Expander Process"
        direction TB
        Entry["Entry-point Scripts\n(main.py / main2.py)"]:::module
        Loader["Expansion Store Loader"]:::module
        Dict["In-memory Dictionary"]:::datastore
        Listener["Input Listener Module"]:::module
        Buffer["Typing Buffer Manager"]:::module
        Processor["Text Processor"]:::module
        Simulator["Output Simulator"]:::module
        Clipboard["Clipboard Manager"]:::module
    end

    %% Startup Flow
    Entry -->|loads| Loader
    Loader -->|reads mappings| Dict

    %% Runtime Flow
    OSKeyboard -->|key events| Listener
    Listener -->|passes KeyEvent| Buffer
    Buffer -->|on trigger| Processor
    Processor -->|match found| Simulator
    Simulator -->|backspace/type| OSKeyboard
    Simulator -->|uses clipboard| Clipboard

    %% Data Dependencies
    FileExp -->|data source| Loader
    Dict -->|lookup| Processor

    %% Other Links
    Launcher -->|starts| Entry
    Readme -.-> Entry

    %% Click Events
    click Entry "https://github.com/0x4133/snaklonger/blob/main/main.py"
    click Loader "https://github.com/0x4133/snaklonger/blob/main/main.py"
    click Listener "https://github.com/0x4133/snaklonger/blob/main/main.py"
    click Buffer "https://github.com/0x4133/snaklonger/blob/main/main.py"
    click Processor "https://github.com/0x4133/snaklonger/blob/main/main.py"
    click Simulator "https://github.com/0x4133/snaklonger/blob/main/main.py"
    click Clipboard "https://github.com/0x4133/snaklonger/blob/main/main.py"
    click FileExp "https://github.com/0x4133/snaklonger/blob/main/expansions.txt"
    click Launcher "https://github.com/0x4133/snaklonger/blob/main/longerPS.ps1"
    click Readme "https://github.com/0x4133/snaklonger/blob/main/README.md"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px;
    classDef module fill:#bbf,stroke:#333,stroke-width:1px;
    classDef datastore fill:#bfb,stroke:#333,stroke-width:1px;
```
