# agent-kilo/jwno architecture

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

- Interactive diagram: https://gitdiagram.com/agent-kilo/jwno
- Repository: https://github.com/agent-kilo/jwno

## Overview

##### Project type and purpose
- Jwno is a desktop application—a tiling window manager for Windows 10/11—written primarily in Janet with a small C stub for Win32 integration. It installs as a native Windows executable, hooks into the OS’s window events, provides a customizable REPL, and manages window layouts.

##### File structure
- Top-level:
- c/                 → C source for WinMain stub (boots Janet VM on Windows).
- src/               → Janet modules: core engine (main.janet), window/event handling, hooks, modules (auto-layout, scratch-pad, indicator, UI hints), REPL, config, logging, etc.
- res/, manifest/    → Windows resources (.rc) and application manifest.
- example/           → Sample Janet scripts/configs demonstrating use.
- doc/, doc/scripts  → Static site source (Markdown + Janet generators) for documentation.
- script/            → Utility Janet scripts (vcs, build helpers).
- test/              → Janet unit tests exercising core modules.
- CI/config:
- .github/workflows → build and release pipelines (install Janet, build docs, release artifacts).

##### README for additional insights
- Confirms project is a window manager built in Janet.
- Emphasizes features, interactive REPL, documentation site, installation and development guides.

##### Final recommendations
- Related modules in clusters (e.g., “Layout Modules”, “UI Modules”).
- Be exhaustive: if a module handles window management, call it out explicitly (e.g., “auto-layout.janet”).

This structure will give a clear, accurate representation of Jwno’s architecture, from process startup through runtime event dispatch to modules and back to the OS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Components
    WinMainStub["WinMain Stub (C)"]:::c
    JanetVM["Janet VM & Core Engine"]:::core
    subgraph "Event Layer"
        direction TB
        Input["input.janet (Input Layer)"]:::core
        Key["key.janet (Key Handling)"]:::core
        WinHook["win.janet (Win32 Hooks)"]:::core
        UIA["uia.janet (UI Automation)"]:::core
        HookMgr["hook.janet (Hook Manager)"]:::core
    end
    subgraph "Modules"
        direction TB
        AutoLayout["auto-layout.janet"]:::module
        ScratchPad["scratch-pad.janet"]:::module
        Indicator["indicator.janet"]:::module
        UIHint["ui-hint.janet"]:::module
        LayoutHist["layout-history.janet"]:::module
        LoggingMod["log.janet"]:::module
        CmdDefs["cmd.janet"]:::module
        ModLoader["mod.janet"]:::module
        UIAbstr["ui.janet"]:::module
    end
    subgraph "Configuration"
        direction TB
        ConfigSys["config.janet"]:::module
        ExampleCfg["example-config.janet"]:::module
    end
    subgraph "REPL"
        direction TB
        REPLSrv["repl.janet"]:::module
    end
    subgraph "OS Services"
        direction TB
        OSWinAPI["Win32 API"]:::os
        OSUIA["UI Automation COM"]:::os
    end
    subgraph "Logging & Persistence"
        direction TB
        LayoutHist
        LoggingMod
    end
    subgraph "Tooling & Docs"
        direction TB
        Docs["doc/ (Documentation)"]:::tooling
        CI[".github/workflows"]:::tooling
        Scripts["script/"]:::tooling
        Tests["test/"]:::tooling
    end

    %% Relationships
    OSWinAPI -->|"WindowEvents"| WinMainStub
    WinMainStub -->|"Initialize VM"| JanetVM
    JanetVM -->|"Load modules"| Input
    JanetVM --> Key
    JanetVM --> WinHook
    JanetVM --> UIA
    Input -->|"KeyPress"| HookMgr
    Key --> HookMgr
    WinHook -->|"WindowEvent"| HookMgr
    UIA --> HookMgr
    HookMgr -->|"Dispatch"| AutoLayout
    HookMgr --> ScratchPad
    HookMgr --> Indicator
    HookMgr --> UIHint
    HookMgr --> ModLoader
    HookMgr --> CmdDefs
    HookMgr --> UIAbstr
    AutoLayout --> OSWinAPI
    ScratchPad --> OSWinAPI
    Indicator --> OSWinAPI
    UIHint --> OSWinAPI
    ModLoader --> JanetVM
    CmdDefs --> JanetVM
    UIAbstr --> OSUIA
    ConfigSys --> HookMgr
    ConfigSys --> CmdDefs
    ExampleCfg --> ConfigSys
    REPLSrv --> JanetVM
    REPLSrv -->|"Socket"| REPLClient((REPL Client))
    AutoLayout --> LayoutHist
    HookMgr --> LoggingMod
    LayoutHist -->|"Read/Write"| JanetVM
    LoggingMod -->|"Persist"| JanetVM

    %% Tooling connections
    Docs --- CI
    CI --- Scripts
    Scripts --- Tests

    %% Click Events
    click WinMainStub "https://github.com/agent-kilo/jwno/blob/master/c/winmain_stub.c"
    click Input "https://github.com/agent-kilo/jwno/blob/master/src/input.janet"
    click Key "https://github.com/agent-kilo/jwno/blob/master/src/key.janet"
    click WinHook "https://github.com/agent-kilo/jwno/blob/master/src/win.janet"
    click UIA "https://github.com/agent-kilo/jwno/blob/master/src/uia.janet"
    click HookMgr "https://github.com/agent-kilo/jwno/blob/master/src/hook.janet"
    click AutoLayout "https://github.com/agent-kilo/jwno/blob/master/src/auto-layout.janet"
    click ScratchPad "https://github.com/agent-kilo/jwno/blob/master/src/scratch-pad.janet"
    click Indicator "https://github.com/agent-kilo/jwno/blob/master/src/indicator.janet"
    click UIHint "https://github.com/agent-kilo/jwno/blob/master/src/ui-hint.janet"
    click LayoutHist "https://github.com/agent-kilo/jwno/blob/master/src/layout-history.janet"
    click LoggingMod "https://github.com/agent-kilo/jwno/blob/master/src/log.janet"
    click CmdDefs "https://github.com/agent-kilo/jwno/blob/master/src/cmd.janet"
    click ModLoader "https://github.com/agent-kilo/jwno/blob/master/src/mod.janet"
    click UIAbstr "https://github.com/agent-kilo/jwno/blob/master/src/ui.janet"
    click ConfigSys "https://github.com/agent-kilo/jwno/blob/master/src/config.janet"
    click ExampleCfg "https://github.com/agent-kilo/jwno/blob/master/example/example-config.janet"
    click REPLSrv "https://github.com/agent-kilo/jwno/blob/master/src/repl.janet"
    click Docs "https://github.com/agent-kilo/jwno/tree/master/doc/"
    click CI "https://github.com/agent-kilo/jwno/tree/master/.github/workflows"
    click Scripts "https://github.com/agent-kilo/jwno/tree/master/script/"
    click Tests "https://github.com/agent-kilo/jwno/tree/master/test/"

    %% Styles
    classDef c fill:#cccccc,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#0066CC,stroke-width:1px
    classDef module fill:#90EE90,stroke:#228B22,stroke-width:1px
    classDef os fill:#FFA500,stroke:#CC8400,stroke-width:1px
    classDef tooling fill:#EEEEEE,stroke:#AAAAAA,stroke-width:1px
```
