# sandboxie-plus/sandboxie architecture

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

- Interactive diagram: https://gitdiagram.com/sandboxie-plus/sandboxie
- Repository: https://github.com/sandboxie-plus/sandboxie

## Overview

Based on our analysis of the file tree and the README, this project is the open‐source community fork of Sandboxie – a Windows sandbox solution that creates isolated environments for running untrusted applications. It actually comprises two editions: the “Classic” version with its legacy MFC-based UI and the “Plus” version with a modern, Qt-based user interface. The project contains many components that include the core sandbox engine (with kernel-mode drivers, user-mode DLLs, hooks, detouring, and service components), installers, support utilities, and additional add-on tools (e.g., SandboxieTools, QSbieAPI, SandMan, UGlobalHotkey).

##### Main high-level components
- Installer/Deployment: Look at the Installer directory, Sandboxie/install, and related build scripts. These represent the system’s deployment and update processes.
- Core Sandbox Engine: The “Sandboxie/core” directory is organized into several submodules:
– User-mode DLLs (e.g., Sandboxie/core/dll): Responsible for API hooking, detouring (the project even includes Detours subfolders), configuration, and file operations.
– Kernel-mode components (drivers in Sandboxie/core/drv): They handle low-level operations, including sandbox isolation at the OS level.
– Low-level system interactions (Sandboxie/core/low) and services (Sandboxie/core/svc): These manage IPC, service control, and communication with the installed sandbox driver.
- User Interfaces:
– Classic UI: Found in the “Sandboxie” directory and its MFC-based code.
– Plus UI: Organized under “SandboxiePlus” (and subprojects such as QSbieAPI, SandMan, and SbieShell) which use Qt and other modern libraries.
- Auxiliary/Helper Modules: Additional directories like SandboxieTools and SandboxiePlus/MiscHelpers provide plug-in functionality and supporting libraries (e.g., for archive management, network/firewall control, add-on management, hotkey functionality, and so on).
- Messaging & Localization: The “Sandboxie/msgs” directory collates language resource files and components that provide UI strings and error messages.

##### Relations and interactions
- The UI layer (both Classic and Plus) is the entry point from the user. It sends control instructions (e.g., start a sandboxed process, apply a configuration change) to the underlying core engine.
- The Core Engine layers communicate with the OS using both user-mode DLLs and kernel drivers. They use IPC mechanisms (through services and named pipes as seen in the “svc” subdirectory) and hook into processes to enforce the sandbox environment.
- The Installer components build and deploy the appropriate binaries and configurations (e.g., the NSIS scripts and build commands in the Installer directory), which prepare the system for installation and updates.
- External tools and add-ons (like LogApiDll or SandboxToys2) interact with the sandbox environment through exposed APIs, logging, or hook interfaces.

##### Architectural patterns and design principles
- Modularity & Layering: The system is built in layers – from the interface layer (UI), to the sandbox orchestration (dll and service components), down to the driver/kernel and low-level hooks.
- Separation of Concerns: Different directories manage UI (Classic vs. Plus), sandbox core, installers, and external tools.
- Extensibility: The presence of add-on modules (e.g., SandMan and MiscHelpers) indicates a design that favors plug-and-play additions and extension points.
- Cross-cutting concerns: Support for multiple languages, configuration files, and separate CI/CD pipelines (as evidenced by the .github folder with workflows) underline the robustness in design.

##### Final checklist
- Every major directory group and significant file collection (Installer, Sandboxie, SandboxiePlus, and SandboxieTools) is represented.
- External interactions (e.g., OS-level interactions like system calls, IPC channels, network communications, etc.).
- Labels are clear and cover responsibilities such as “isolating sandbox environments,” “hooking system calls,” “managing sandbox configurations,” or “facilitating add-on integration.”

## Diagram (Mermaid)

```mermaid
graph TD
    %% Top Level: User
    User["User"]:::user

    %% User Interfaces Subgraph
    subgraph "User Interfaces"
        ClassicUI["Classic UI (Legacy MFC)"]:::ui
        PlusUI["Plus UI (Modern Qt)"]:::ui
    end

    %% Core Sandbox Engine Subgraph
    subgraph "Core Sandbox Engine"
        UserModeDLLs["User-mode DLLs (Sandboxie/core/dll)"]:::core
        LowSystem["Low-level System Interactions (Sandboxie/core/low)"]:::core
        KernelDrivers["Kernel-mode Components (Sandboxie/core/drv)"]:::core
        Services["Services/IPC (Sandboxie/core/svc)"]:::core
    end

    %% Additional Components
    InstallerDeployment["Installer/Deployment"]:::installer
    AuxModules["Auxiliary/Helper Modules"]:::aux
    Messaging["Messaging & Localization"]:::msg

    %% Connections from User to UIs
    User -->|"initiates"| ClassicUI
    User -->|"initiates"| PlusUI

    %% UI to Core Engine commands
    ClassicUI -->|"commands"| UserModeDLLs
    ClassicUI -->|"triggers"| Services

    PlusUI -->|"commands"| UserModeDLLs
    PlusUI -->|"triggers"| Services

    %% Bidirectional IPC within Core Engine
    UserModeDLLs <-->|"IPC"| Services

    %% Internal flow within Core Engine
    UserModeDLLs -->|"calls"| LowSystem
    LowSystem -->|"delegates"| KernelDrivers
    Services -->|"monitors"| LowSystem

    %% Installer/Deployment integration
    InstallerDeployment -->|"deploys"| KernelDrivers
    InstallerDeployment -->|"updates"| UserModeDLLs

    %% Auxiliary modules interaction with Core Engine
    AuxModules -->|"extends"| Services
    AuxModules -->|"assists"| UserModeDLLs

    %% Messaging and Localization feeding UI and Core
    Messaging -->|"supplies"| ClassicUI
    Messaging -->|"supplies"| PlusUI
    Messaging -->|"supports"| Services

    %% Click Events for Component Mapping
    click InstallerDeployment "https://github.com/sandboxie-plus/sandboxie/tree/master/Installer"
    click UserModeDLLs "https://github.com/sandboxie-plus/sandboxie/tree/master/Sandboxie/core/dll"
    click KernelDrivers "https://github.com/sandboxie-plus/sandboxie/tree/master/Sandboxie/core/drv"
    click LowSystem "https://github.com/sandboxie-plus/sandboxie/tree/master/Sandboxie/core/low"
    click Services "https://github.com/sandboxie-plus/sandboxie/tree/master/Sandboxie/core/svc"
    click ClassicUI "https://github.com/sandboxie-plus/sandboxie/tree/master/Sandboxie"
    click PlusUI "https://github.com/sandboxie-plus/sandboxie/tree/master/SandboxiePlus"
    click AuxModules "https://github.com/sandboxie-plus/sandboxie/tree/master/SandboxieTools"
    click Messaging "https://github.com/sandboxie-plus/sandboxie/tree/master/Sandboxie/msgs"

    %% Styling Classes
    classDef user fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef ui fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef installer fill:#FFECB3,stroke:#FF8C00,stroke-width:2px;
    classDef aux fill:#FFCCCB,stroke:#CD5C5C,stroke-width:2px;
    classDef msg fill:#D3D3D3,stroke:#696969,stroke-width:2px;
```
