# peterm45/sysinput architecture

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

- Interactive diagram: https://gitdiagram.com/peterm45/sysinput
- Repository: https://github.com/peterm45/sysinput

## Overview

##### Main Components
- Main Application Entry: (src/main.zig, src/sysinput.zig) which wire up all modules.
- Core Module: Handles text buffer management, configuration, and debugging (src/core/* and src/buffer_controller.zig).
- Input Module: Captures keystrokes and detects the active text fields (src/input/keyboard.zig, src/input/text_field.zig, src/input/window_detection.zig).
- Text Processing Module: Provides autocomplete functionality, dictionary management, edit distance algorithms, spell checking, and text insertion techniques (src/text/*).
- Suggestion Module: Manages the generation and tracking of suggestions and statistics (src/suggestion/manager.zig, src/suggestion/stats.zig).
- User Interface (UI) Module: Responsible for positioning and displaying the suggestion overlay near the text cursor (src/ui/position.zig, src/ui/suggestion_ui.zig, src/ui/window.zig).
- Win32 Module: Contains Windows API bindings and functions for keyboard hooks and text injection (src/win32/api.zig, src/win32/hook.zig, src/win32/text_inject.zig).
- External Resources: The dictionary file (resources/dictionary.txt) and build scripts (build.zig, build.zig.zon).

##### Out the Relationships and Interactions
- The main entry point initializes the system, bringing all components together.
- The Win32 module sets up Windows hooks for capturing keystrokes. These hooks feed into the Input module, which processes keystrokes and detects active text fields.
- Input events and detected text field data are passed to the Core module which maintains a text buffer.
- The updated text buffer is then analyzed by the Text Processing module (autocomplete, spell check, edit distance algorithms) which leverages the Dictionary resource.
- The Suggestion module receives processed data and generates the appropriate suggestion based on learned user patterns.
- The UI module displays the suggestion using an overlay window at the correct position relative to the cursor.
- Depending on which text insertion method is most effective (clipboard operations, key simulation, or direct messaging), the Win32 module’s text injection utilities are used to insert text into the active text field.

##### Architectural Patterns & Design Principles
- Modularity: Each major piece of functionality (input capture, core buffering, text processing, suggestion logic, UI, and OS interfacing) is encapsulated in its own module.
- Extensibility: Highlight the adaptive learning mechanisms that choose among various text insertion methods.

##### Detailed Explanation for the Principal Software Engineer
- System Integration Layer (Win32): Highlighting Windows hook setup and text injection utilities.
- Input Processing Layer: Capturing keyboard events and detecting active text fields.
- Core Processing: Text buffering and configuration management.
- Text & Suggestion Processing Layer: Autocomplete, dictionary handling, spell-check, and suggestion management.
- UI Layer: Suggestion display and window positioning.
- Build and external resources separately, indicating that they support the overall operation.
- Module is annotated with its key components (e.g., for Text, mention ‘autocomplete’, ‘edit_distance’, ‘spellcheck’).
- Multi-method text insertion strategies and adaptive learning across different application classes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% High-Level System Container
    subgraph "SysInput System"
        %% Application Entry Layer
        subgraph "Application Entry"
            MainApp["Main Application Entry"]:::mainEntry
            SysInputEntry["SysInput Entry"]:::mainEntry
        end

        %% Integration Layer (Win32)
        subgraph "Integration Layer (Win32)"
            Win32Module["Win32 Module"]:::integration
            Win32API["Win32 API Bindings"]:::integration
            Win32Hook["Win32 Keyboard Hook"]:::integration
            Win32TextInject["Win32 Text Injection"]:::integration
        end

        %% Input Processing Layer
        subgraph "Input Processing Layer"
            InputModule["Input Module"]:::input
            InputKeyboard["Keyboard Capture"]:::input
            InputTextField["Text Field Detection"]:::input
            InputWindowDetection["Window Detection"]:::input
        end

        %% Core Processing Layer
        subgraph "Core Processing Layer"
            CoreModule["Core Module (Buffer, Config, Debug)"]:::core
            CoreBuffer["Buffer Management"]:::core
            CoreConfig["Configuration"]:::core
            CoreDebug["Debugging"]:::core
            BufferController["Buffer Controller"]:::core
        end

        %% Text & Suggestion Processing Layer
        subgraph "Text & Suggestion Processing Layer"
            subgraph "Text Processing Module"
                TextModule["Text Processing Module"]:::processing
                TextAutocomplete["Autocomplete Engine"]:::processing
                TextDictionary["Dictionary Manager"]:::processing
                TextEditDistance["Edit Distance Algorithm"]:::processing
                TextInsertion["Text Insertion Techniques"]:::processing
                TextSpellcheck["Spell Checker"]:::processing
            end
            subgraph "Suggestion Module"
                SuggestionModule["Suggestion Module"]:::processing
                SuggestionManager["Suggestion Manager"]:::processing
                SuggestionStats["Usage Statistics"]:::processing
            end
        end

        %% UI Layer
        subgraph "UI Layer"
            UIModule["UI Module"]:::ui
            UIPosition["Positioning Engine"]:::ui
            UISuggestionUI["Suggestion Overlay UI"]:::ui
            UIWin["Window Management"]:::ui
        end

        %% External Resources & Build Scripts
        subgraph "External & Build Resources"
            DictionaryResource["Dictionary Resource"]:::external
            BuildScript["Build Script"]:::external
            BuildConfig["Build Config"]:::external
        end
    end

    %% Connections between Layers
    MainApp -->|"init"| Win32Module
    MainApp -->|"init"| InputModule
    SysInputEntry -->|"init"| CoreModule

    %% Win32 to Input: Windows hooks capture keystrokes
    Win32Module -->|"keyboardHooks"| InputModule
    Win32API --> Win32Module
    Win32Hook --> Win32Module
    Win32TextInject --> Win32Module

    %% Input Layer details
    InputModule -->|"captures"| InputKeyboard
    InputModule -->|"detects"| InputTextField
    InputModule -->|"monitors"| InputWindowDetection

    %% Input to Core: Passing text data
    InputModule -->|"updatesTextBuffer"| CoreModule

    %% Core Processing internal connections
    CoreModule -->|"manages"| CoreBuffer
    CoreModule -->|"reads"| CoreConfig
    CoreModule -->|"logs"| CoreDebug
    CoreModule -->|"controls"| BufferController

    %% Core to Text Processing: Analyzing and processing text
    CoreModule -->|"processes"| TextModule

    %% Text Processing Module internal details
    TextModule -->|"autocomplete"| TextAutocomplete
    TextModule -->|"dictionaryLookup"| TextDictionary
    TextModule -->|"calcEditDistance"| TextEditDistance
    TextModule -->|"textInsertion"| TextInsertion
    TextModule -->|"spellcheck"| TextSpellcheck
    TextDictionary ---|"uses"| DictionaryResource

    %% Text Processing to Suggestion Module
    TextModule -->|"generatesSuggestions"| SuggestionModule
    SuggestionModule -->|"manages"| SuggestionManager
    SuggestionModule -->|"tracks"| SuggestionStats

    %% Suggestion to UI: Displaying suggestions
    SuggestionModule -->|"display"| UIModule

    %% UI internal connections
    UIModule -->|"positions"| UIPosition
    UIModule -->|"renders"| UISuggestionUI
    UIModule -->|"managesWindow"| UIWin

    %% UI feedback to Win32: Text injection for input
    UIModule -->|"injectText"| Win32TextInject

    %% Styling Classes
    classDef mainEntry fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef integration fill:#cce5ff,stroke:#004080,stroke-width:2px;
    classDef input fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef core fill:#ffffcc,stroke:#b3b300,stroke-width:2px;
    classDef processing fill:#ffebcc,stroke:#e69138,stroke-width:2px;
    classDef ui fill:#e6ccff,stroke:#9933cc,stroke-width:2px;
    classDef external fill:#d9ead3,stroke:#6aa84f,stroke-width:2px;

    %% Click Events for Main Application Entry
    click MainApp "https://github.com/peterm45/sysinput/blob/main/src/main.zig"
    click SysInputEntry "https://github.com/peterm45/sysinput/blob/main/src/sysinput.zig"

    %% Click Events for Win32 Module
    click Win32Module "https://github.com/peterm45/sysinput/tree/main/src/win32"
    click Win32API "https://github.com/peterm45/sysinput/blob/main/src/win32/api.zig"
    click Win32Hook "https://github.com/peterm45/sysinput/blob/main/src/win32/hook.zig"
    click Win32TextInject "https://github.com/peterm45/sysinput/blob/main/src/win32/text_inject.zig"

    %% Click Events for Input Module
    click InputModule "https://github.com/peterm45/sysinput/tree/main/src/input"
    click InputKeyboard "https://github.com/peterm45/sysinput/blob/main/src/input/keyboard.zig"
    click InputTextField "https://github.com/peterm45/sysinput/blob/main/src/input/text_field.zig"
    click InputWindowDetection "https://github.com/peterm45/sysinput/blob/main/src/input/window_detection.zig"

    %% Click Events for Core Module
    click CoreModule "https://github.com/peterm45/sysinput/tree/main/src/core"
    click CoreBuffer "https://github.com/peterm45/sysinput/blob/main/src/core/buffer.zig"
    click CoreConfig "https://github.com/peterm45/sysinput/blob/main/src/core/config.zig"
    click CoreDebug "https://github.com/peterm45/sysinput/blob/main/src/core/debug.zig"
    click BufferController "https://github.com/peterm45/sysinput/blob/main/src/buffer_controller.zig"

    %% Click Events for Text Processing Module
    click TextModule "https://github.com/peterm45/sysinput/tree/main/src/text"
    click TextAutocomplete "https://github.com/peterm45/sysinput/blob/main/src/text/autocomplete.zig"
    click TextDictionary "https://github.com/peterm45/sysinput/blob/main/src/text/dictionary.zig"
    click TextEditDistance "https://github.com/peterm45/sysinput/blob/main/src/text/edit_distance.zig"
    click TextInsertion "https://github.com/peterm45/sysinput/blob/main/src/text/insertion.zig"
    click TextSpellcheck "https://github.com/peterm45/sysinput/blob/main/src/text/spellcheck.zig"

    %% Click Events for Suggestion Module
    click SuggestionModule "https://github.com/peterm45/sysinput/tree/main/src/suggestion"
    click SuggestionManager "https://github.com/peterm45/sysinput/blob/main/src/suggestion/manager.zig"
    click SuggestionStats "https://github.com/peterm45/sysinput/blob/main/src/suggestion/stats.zig"

    %% Click Events for UI Module
    click UIModule "https://github.com/peterm45/sysinput/tree/main/src/ui"
    click UIPosition "https://github.com/peterm45/sysinput/blob/main/src/ui/position.zig"
    click UISuggestionUI "https://github.com/peterm45/sysinput/blob/main/src/ui/suggestion_ui.zig"
    click UIWin "https://github.com/peterm45/sysinput/blob/main/src/ui/window.zig"

    %% Click Events for External Resources & Build Scripts
    click DictionaryResource "https://github.com/peterm45/sysinput/blob/main/resources/dictionary.txt"
    click BuildScript "https://github.com/peterm45/sysinput/blob/main/build.zig"
    click BuildConfig "https://github.com/peterm45/sysinput/blob/main/build.zig.zon"
```
