# moudey/shell architecture

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

- Interactive diagram: https://gitdiagram.com/moudey/shell
- Repository: https://github.com/moudey/shell

## Overview

##### Main Components
- Windows File Explorer Environment – This is the external system with which the application integrates.
- Shell Extension DLL – Found under src/dll, this is the core module that hooks into File Explorer (using the Detours library from src/3rdparty/detours) and manages context menu manipulation.
- Executable Components – Located in src/exe, these may manage configuration or launch helper functionalities.
- Parser & Expression Engine – Under src/dll/src/Parser and src/dll/src/Expression, these modules parse and evaluate the custom scripting (from .nss files in src/bin/imports) that defines the menu behavior, appearance, and configuration.
- Shared Library Components – Found under src/shared, these utilities include common definitions, Windows system integration (e.g., RegistryConfig, System modules, UI elements, drawing utilities) that support both the DLL and executable.
- Setup/Installer – Under src/setup (using WiX tools) and packages (chocolatey packages), the project has a dedicated installer module to package and deploy the extension.
- Documentation and Templates – While not directly part of runtime, the docs and templates give insight into configuration options and are useful during development.

##### Relationships and Data Flow
- Windows Explorer loads the Shell DLL (via installer registration and Windows runtime hooks).
- The Shell DLL uses Detours (external library) to intercept system calls or menu invocation events.
- Upon activation (right-click in File Explorer), the Shell DLL gathers configuration data – typically stored as plain text script files (.nss) under src/bin/imports. The Parser and Expression engine processes these scripts to determine what items to display.
- Shared libraries provide utility functions (for file system operations, registry management, logging, UI drawing, etc.) and support both DLL and executable modules.
- The executable module (src/exe) may be used to launch the configuration UI or provide additional command-line functionality.
- The installer (src/setup/wix) packages the DLL and supporting files and handles deployment/registration with Windows.
- Tools under src/tools (e.g., versioning and hash tools) run separate processes to support development and build management.

##### Architectural Patterns/Design Principles
- Modularity: Each component (extension DLL, parser, shared libraries, installer) is clearly separated.
- Hooking/Interception: The use of Detours to hook Windows API calls, which is central to the extension’s function.
- Configuration-as-Code: The project treats configuration as plain-text scripts (custom .nss files) that are parsed to define the context menu’s structure and style.
- Reusability: Shared libraries and separation of 3rd party integrations promote reuse of code and ease of maintenance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    X["Windows File Explorer"]:::actor

    subgraph "Core Modules"
        B["Shell Extension DLL"]:::core
        C["Parser"]:::parser
        D["Expression Engine"]:::parser
        E["Executable Components"]:::executable
        F["Shared Library Components"]:::shared
    end

    subgraph "Third-Party Libraries"
        G["Detours"]:::thirdparty
        H["PlutoSVG"]:::thirdparty
    end

    I["Setup/Installer"]:::installer
    J["Documentation & Templates"]:::documentation

    X -->|"hooks_into"| B
    B -->|"parses"| C
    B -->|"evaluates"| D
    B -->|"utilizes"| F
    E -->|"utilizes"| F
    B -->|"hooks_with"| G
    B -->|"renders_svg"| H
    I -->|"deploys_DLL"| B
    I -->|"deploys_exe"| E
    J ---|"provides_info"| I

    click B "https://github.com/moudey/shell/tree/main/src/dll"
    click E "https://github.com/moudey/shell/tree/main/src/exe"
    click C "https://github.com/moudey/shell/tree/main/src/dll/src/Parser"
    click D "https://github.com/moudey/shell/tree/main/src/dll/src/Expression"
    click F "https://github.com/moudey/shell/tree/main/src/shared"
    click G "https://github.com/moudey/shell/tree/main/src/3rdparty/detours"
    click H "https://github.com/moudey/shell/tree/main/src/3rdparty/plutosvg"
    click I "https://github.com/moudey/shell/tree/main/src/setup/wix"
    click J "https://github.com/moudey/shell/tree/main/docs"

    classDef actor fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef parser fill:#d2b4de,stroke:#7d3c98,stroke-width:2px;
    classDef executable fill:#a2d9ce,stroke:#1e8449,stroke-width:2px;
    classDef shared fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef thirdparty fill:#fad7a0,stroke:#d35400,stroke-width:2px,stroke-dasharray:5,5;
    classDef installer fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef documentation fill:#f6e3b4,stroke:#b9770e,stroke-width:2px;
```
