# trungnt2910/lxmonika architecture

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

- Interactive diagram: https://gitdiagram.com/trungnt2910/lxmonika
- Repository: https://github.com/trungnt2910/lxmonika

## Overview

##### Project type and purpose
- This is a multi‐component, system‐level compatibility layer for Windows that implements Linux‐style syscalls and execution environments (“Just Monika”).
- It consists of two kernel‐mode drivers (lxmonika and mxss), a stub library (lxstub), a command‐line/service tool (monika), plus a sample host and demo (mxss/monix & mxss/mxhost).
- The goal is to let user‐mode Linux‐style processes call into Windows via a custom driver, manage that driver, and host Linux binaries.

##### File structure
Top‐level solution (lxmonika.sln)
- lxmonika/       → Windows kernel‐mode driver (monika.sys)
– include/      → public driver API headers
– include_private/ → driver internals (modules, logger, OS abstractions)
– src/          → driver entry, dispatch, context, providers, reality (syscall translations)
– lxmonika.vcxproj & INF, RC, PROPS, TARGETS → build & installer
- lxstub/         → user‐mode stub DLL that Linux binaries link against
– include/      → stub API (lxss.h, pico.h)
– src/          → thin shim forwarding calls to the kernel driver
– lxstub.vcxproj → build project
- monika/         → management utility (CLI + Windows service)
– include/, src/ → commands (install, uninstall, exec), parameters, registry, service logic
– monika.vcxproj, RC → build project & resources
- mxss/           → second subsystem with its own driver and host
– mxss/         → MXSS driver (structure similar to lxmonika)
– monix/        → sample Linux “hello” application & build script
– mxhost/       → host launcher for Linux binaries

##### README for additional insights
- While minimal, the monika README confirms the “Just Monika” branding and directs contributors to Discord.
- Each subfolder has its own README describing build or purpose (e.g., mxss/README.md).

##### Detailed coverage
- Be exhaustive: list both public include directories and private internals.
- Four projects and their interactions.
- External dependencies only if they exist (none beyond Windows kernel and standard C++).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Kernel-mode Drivers
    subgraph "Kernel-mode Layer"
        direction TB
        LXMONIKA["LXMONIKA Driver<br/>(monika.sys)"]:::kernel
        MXSSDRV["MXSS Driver<br/>(mxss.sys)"]:::kernel
    end

    %% Subcomponents of LXMONIKA
    subgraph "LXMONIKA Internals" 
        direction TB
        API_HDR["Public API Headers"]:::kernel
        PRIV_HDR["Private Internals"]:::kernel
        SRC["Driver Source"]:::kernel
        INSTALLER["Build & Installer Files"]:::kernel
    end

    LXMONIKA --> API_HDR
    LXMONIKA --> PRIV_HDR
    LXMONIKA --> SRC
    LXMONIKA --> INSTALLER

    %% Subcomponents of MXSS
    subgraph "MXSS Internals"
        direction TB
        MXSS_HDR["Public API Headers"]:::kernel
        MXSS_SRC["Driver Source"]:::kernel
        MXSS_INSTALLER["Build & Installer Files"]:::kernel
    end

    MXSSDRV --> MXSS_HDR
    MXSSDRV --> MXSS_SRC
    MXSSDRV --> MXSS_INSTALLER

    %% User-mode Components
    subgraph "User-mode Layer"
        direction TB
        LXSTUB["LXSTUB DLL"]:::user
        MONIKA["MONIKA CLI/Service"]:::user
        MXHOST["MXHOST Launcher"]:::user
        MONIX_APP["MONIX Sample App"]:::user
    end

    MONIX_APP -->|links to| LXSTUB
    LXSTUB -->|DeviceIoControl| LXMONIKA
    MONIKA -->|IOCTL install/uninstall| LXMONIKA
    MXHOST -->|DeviceIoControl| MXSSDRV

    %% Build & CI
    subgraph "Build & CI" 
        direction TB
        SOLN["Visual Studio Solution"]:::build
        CI["GitHub Actions CI"]:::build
        SETUPPS["setup.ps1"]:::build
        PACKPS["pack.ps1"]:::build
    end

    SOLN --> LXMONIKA
    SOLN --> LXSTUB
    SOLN --> MONIKA
    SOLN --> MXSSDRV
    SOLN --> MXHOST
    SOLN --> MONIX_APP
    CI --> SOLN
    CI --> SETUPPS
    CI --> PACKPS

    %% Click Events
    click LXMONIKA "https://github.com/trungnt2910/lxmonika/tree/master/lxmonika/"
    click API_HDR "https://github.com/trungnt2910/lxmonika/tree/master/lxmonika/include/"
    click PRIV_HDR "https://github.com/trungnt2910/lxmonika/tree/master/lxmonika/include_private/"
    click SRC "https://github.com/trungnt2910/lxmonika/tree/master/lxmonika/src/"
    click INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/lxmonika/lxmonika.vcxproj"
    click INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/lxmonika/lxmonika.inf"
    click INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/lxmonika/lxmonika.rc"
    click INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/lxmonika/lxmonika.wprp"
    click INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/lxmonika/lxmonika.vcxproj.filters"

    click LXSTUB "https://github.com/trungnt2910/lxmonika/tree/master/lxstub/"
    click LXSTUB "https://github.com/trungnt2910/lxmonika/blob/master/lxstub/lxstub.vcxproj"
    click API_HDR "https://github.com/trungnt2910/lxmonika/tree/master/lxstub/include/"
    click SRC "https://github.com/trungnt2910/lxmonika/blob/master/lxstub/src/driver.cpp"
    click INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/lxstub/lxstub.def"
    click INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/lxstub/lxstub.rc"

    click MONIKA "https://github.com/trungnt2910/lxmonika/tree/master/monika/"
    click MONIKA "https://github.com/trungnt2910/lxmonika/blob/master/monika/monika.vcxproj"
    click API_HDR "https://github.com/trungnt2910/lxmonika/tree/master/monika/include/"
    click MONIKA "https://github.com/trungnt2910/lxmonika/tree/master/monika/src/Commands/"
    click MONIKA "https://github.com/trungnt2910/lxmonika/blob/master/monika/src/main.cpp"
    click MONIKA "https://github.com/trungnt2910/lxmonika/blob/master/monika/src/service.cpp"
    click MONIKA "https://github.com/trungnt2910/lxmonika/blob/master/monika/src/registry.cpp"
    click INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/monika/res/monika.rc"

    click MXSSDRV "https://github.com/trungnt2910/lxmonika/tree/master/mxss/mxss/"
    click MXSS_HDR "https://github.com/trungnt2910/lxmonika/tree/master/mxss/mxss/include/"
    click MXSS_SRC "https://github.com/trungnt2910/lxmonika/tree/master/mxss/mxss/src/"
    click MXSS_INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/mxss/mxss/mxss.vcxproj"
    click MXSS_INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/mxss/mxss/mxss.inf"
    click MXSS_INSTALLER "https://github.com/trungnt2910/lxmonika/blob/master/mxss/mxss/mxss.vcxproj.filters"

    click MONIX_APP "https://github.com/trungnt2910/lxmonika/blob/master/mxss/monix/src/hello.cpp"
    click MONIX_APP "https://github.com/trungnt2910/lxmonika/blob/master/mxss/monix/build.sh"

    click MXHOST "https://github.com/trungnt2910/lxmonika/tree/master/mxss/mxhost/"
    click MXHOST "https://github.com/trungnt2910/lxmonika/blob/master/mxss/mxhost/mxhost.vcxproj"

    click SOLN "https://github.com/trungnt2910/lxmonika/blob/master/lxmonika.sln"
    click CI "https://github.com/trungnt2910/lxmonika/blob/master/.github/workflows/build.yml"
    click SETUPPS "https://github.com/trungnt2910/lxmonika/blob/master/setup.ps1"
    click PACKPS "https://github.com/trungnt2910/lxmonika/blob/master/pack.ps1"

    %% Styles
    classDef kernel fill:#f88,stroke:#900;
    classDef user fill:#88f,stroke:#006;
    classDef build fill:#8f8,stroke:#090;
```
