# 1strewave/winscript architecture

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

- Interactive diagram: https://gitdiagram.com/1strewave/winscript
- Repository: https://github.com/1strewave/winscript

## Overview

##### Project Type and Purpose
- WinScript is a domain-specific scripting language primarily for automating Windows tasks. It combines a CLI interface (using Cobra) with interpreter components to parse and execute simple scripts (.ws files).
- The README and file structure indicate that the project is a command-line tool with core features like launching applications, simulating input, and other Windows automation actions.

##### Break Down the File Structure into Main Components
- CLI/Command Layer: Located in the "cmd" directory, these Go files (docs.go, root.go, run.go, version.go) define the entry points managed by Cobra. They handle command-line argument parsing and dispatch commands.
- Core Logic and Runtime: Under the "internal" directory, split broadly into:
- The Parser Module ("internal/parser/parser.go") which will convert the human-readable .ws scripts into an internal representation.
- The Runtime Module ("internal/runtime/runtime.go") that likely processes the parsed commands to interact with Windows (handling actions such as “open”, “type”, “move_mouse”, etc.).
- Data Models: The "internal/models" directory (e.g., types.go) defines the data structures used across the parser and runtime.
- Documentation: The "docs" directory and README provide usage instructions, command details, and examples.
- Scripts & Utilities: The "scripts" folder containing sample ".ws" script files, and installation scripts like "install.bat".

##### Component Relationships and Interactions
- The CLI layer receives user commands and file inputs which it passes to the Parser.
- The Parser translates the script into structured commands or tokens.
- The structured commands are then processed by the Runtime, which interacts with Windows services and APIs.
- Data models serve as shared structures between the Parser and Runtime.
- The output or any errors are communicated back to the CLI for display.
- External interactions include operating system calls (for process launching, simulating keystrokes/mouse actions) and integration with Cobra for command-handling.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project clearly divides responsibilities among the CLI, parser, runtime, and models.
- Modularity: Encapsulation of functions in packages (cmd, internal/*) allows for easier testing, debugging, and potential extension.
- Simplicity & Extensibility: The design, inspired by AppleScript but in Go, keeps the core functionality simple with room for future enhancements (as detailed in the roadmap).

##### Final Steps
- Verify that all essential elements from the file structure (cmd, internal, docs, etc.) are represented and that their roles in processing a .ws file from input to execution are clearly communicated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI (Cobra Commands)"]:::cli
    end

    %% Internal Modules
    subgraph "Internal Modules"
        Parser["Parser Module"]:::parser
        Runtime["Runtime Engine"]:::runtime
        Models["Data Models"]:::models
    end

    %% External and Supporting Components
    subgraph "External & Support"
        Windows["External Windows APIs"]:::external
        Documentation["Documentation & README"]:::docs
        Scripts["Scripts & Utilities"]:::scripts
    end

    %% Connections
    CLI -->|"accepts_script"| Parser
    Parser -->|"parse_script"| Runtime
    Parser -->|"references"| Models
    Runtime -->|"executes_on"| Windows
    Runtime -->|"reports_to"| CLI

    Documentation -->|"guides"| CLI
    Scripts -->|"provides_examples"| CLI

    %% Click Events
    click CLI "https://github.com/1strewave/winscript/tree/main/cmd"
    click Parser "https://github.com/1strewave/winscript/blob/main/internal/parser/parser.go"
    click Runtime "https://github.com/1strewave/winscript/blob/main/internal/runtime/runtime.go"
    click Models "https://github.com/1strewave/winscript/blob/main/internal/models/types.go"
    click Documentation "https://github.com/1strewave/winscript/tree/main/docs"
    click Scripts "https://github.com/1strewave/winscript/tree/main/scripts"

    %% Styles
    classDef cli fill:#ADD8E6, stroke:#000, stroke-width:2px;
    classDef parser fill:#FFA500, stroke:#000, stroke-width:2px;
    classDef runtime fill:#90EE90, stroke:#000, stroke-width:2px;
    classDef models fill:#FFD700, stroke:#000, stroke-width:2px;
    classDef external fill:#D3D3D3, stroke:#000, stroke-width:2px;
    classDef docs fill:#FFB6C1, stroke:#000, stroke-width:2px;
    classDef scripts fill:#E6E6FA, stroke:#000, stroke-width:2px;
```
