# gravitlauncher/gravitguard architecture

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

- Interactive diagram: https://gitdiagram.com/gravitlauncher/gravitguard
- Repository: https://github.com/gravitlauncher/gravitguard

## Overview

#### Purpose
GravitGuard 2 Pro is a Windows-native protection template for Java applications. It builds a native launcher plus a guard DLL, intended to start or supervise a JVM-based target and apply native checks/hooks. The included Java program is a minimal demonstration target.

#### Build Outputs and Entry Points
- Native executable entry point: `GravitGuard2/GravitGuard2.cpp`, built by `GravitGuard2/GravitGuard2.vcxproj`.
- Guard DLL process entry point: `GuardDLL/dllmain.cpp`, built by `GuardDLL/GuardDLL.vcxproj`.
- Java demonstration entry point: `demo-application/src/main/java/org/example/Main.java`.
- The solution is `GravitGuard2.sln`; the README specifies separate x86 and x64 Release builds and requires `JAVA_HOME`.

#### Native Launcher Stage
`GravitGuard2/GravitGuard2.cpp` is the top-level native application boundary. Its architectural role is to operate before or alongside the Java target, where it can establish the protected process/JVM environment and coordinate use of the guard DLL. It is the executable artifact expected to be distributed with the protection.

#### Guard DLL and Protection Core
The DLL contains the core protection implementation:
- `GuardDLL/GravitGuard.cpp` and `GuardDLL/GravitGuard.h` define the principal GravitGuard-facing implementation/API.
- `GuardDLL/guard.cpp` and `GuardDLL/include/guard.h` contain guard-specific logic and shared declarations.
- `GuardDLL/dllmain.cpp` attaches this functionality to DLL lifecycle events.

This division makes the launcher/process boundary separate from code that executes inside a guarded process.

#### Hooking / Interception Boundary
Hooking is a first-class mechanism:
- `GuardDLL/hooks.cpp` implements hook setup or hook callbacks.
- `GuardDLL/GuardDetour.h` and `GuardDLL/GuardDetourHandler.h` define detour abstractions and handling contracts.
- `minhook` is an external/submodule dependency used for native API detouring.

Hooks form the primary interception boundary between guard policy and Windows/JVM-related runtime behavior. Low-level Windows compatibility definitions are isolated in `GuardDLL/WindowsInternalDefines.h`.

#### JVM and Java Target Integration
The native side includes JVM-oriented definitions in `GuardDLL/jli_defines.h`, indicating direct integration with Java launcher/JLI interfaces rather than only controlling an unrelated child process. The Java application remains a separate Gradle project under `demo-application`, with its executable application code at `demo-application/src/main/java/org/example/Main.java`.

The expected flow is native launcher/guard initialization → JVM or Java target startup → native hooks/checks active during target execution.

#### Diagnostics and Runtime Dependencies
`GuardDLL/Logger.cpp` and `GuardDLL/Logger.h` provide diagnostics from the injected/loaded native guard layer. The material runtime dependencies are Windows, a JDK/JVM available through `JAVA_HOME`, and the MinHook native detouring library. CI is Windows/MSBuild-oriented through `.github/workflows/msbuild.yml`.

Main entry points: [`GuardDLL/GravitGuard.cpp`](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/GravitGuard.cpp) (GravitGuard core), [`GuardDLL/hooks.cpp`](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/hooks.cpp) (Hook layer), [`GravitGuard2/GravitGuard2.cpp`](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GravitGuard2/GravitGuard2.cpp) (Native launcher entry), [`GuardDLL/dllmain.cpp`](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/dllmain.cpp) (DLL lifecycle entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launcher["Native Launcher"]
  node_launcher_project["Launcher project<br/>MSBuild project"]
  node_launcher_entry["Native launcher entry<br/>Windows executable<br/>[GravitGuard2.cpp]"]
end

subgraph group_guard["Guard DLL"]
  node_guard_project["Guard DLL project<br/>MSBuild project<br/>[GuardDLL.vcxproj]"]
  node_dll_entry["DLL lifecycle entry<br/>DLL entry point<br/>[dllmain.cpp]"]
  node_guard_core["GravitGuard core<br/>protection API<br/>[GravitGuard.cpp]"]
  node_guard_api["GravitGuard API<br/>header<br/>[GravitGuard.h]"]
  node_guard_logic["Guard logic<br/>protection logic<br/>[guard.cpp]"]
  node_hook_layer{{"Hook layer<br/>interception<br/>[hooks.cpp]"}}
  node_detour_contracts["Detour contracts<br/>hook abstractions<br/>[GuardDetour.h]"]
  node_jli_integration["JLI integration<br/>JVM interface definitions<br/>[jli_defines.h]"]
  node_logger["Guard diagnostics<br/>native logging<br/>[Logger.cpp]"]
end

subgraph group_java["Java Target"]
  node_java_entry["Demo Java entry<br/>Java application<br/>[Main.java]"]
end

subgraph group_runtime["Runtime Dependencies"]
  node_windows["Windows<br/>native runtime"]
  node_jdk["JDK / JVM<br/>Java runtime"]
  node_minhook["MinHook<br/>native detouring library"]
end

node_solution["Visual Studio solution<br/>build orchestration<br/>[GravitGuard2.sln]"]

node_solution -->|"builds"| node_launcher_project
node_solution -->|"builds"| node_guard_project
node_launcher_project -->|"compiles"| node_launcher_entry
node_guard_project -->|"builds DLL"| node_dll_entry
node_launcher_entry -->|"loads / coordinates"| node_dll_entry
node_dll_entry -->|"initializes"| node_guard_core
node_guard_core -->|"implements"| node_guard_api
node_guard_core -->|"uses"| node_guard_logic
node_guard_logic -->|"applies policy through"| node_hook_layer
node_hook_layer -->|"uses"| node_detour_contracts
node_hook_layer -->|"detours with"| node_minhook
node_guard_core -->|"integrates through"| node_jli_integration
node_launcher_entry -->|"starts / supervises"| node_jdk
node_jdk -->|"executes"| node_java_entry
node_hook_layer -->|"intercepts runtime behavior"| node_windows
node_guard_core -->|"emits diagnostics"| node_logger
node_jdk -->|"runs on"| node_windows

click node_solution "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GravitGuard2.sln"
click node_launcher_project "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GravitGuard2/GravitGuard2.vcxproj"
click node_launcher_entry "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GravitGuard2/GravitGuard2.cpp"
click node_guard_project "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/GuardDLL.vcxproj"
click node_dll_entry "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/dllmain.cpp"
click node_guard_core "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/GravitGuard.cpp"
click node_guard_api "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/GravitGuard.h"
click node_guard_logic "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/guard.cpp"
click node_hook_layer "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/hooks.cpp"
click node_detour_contracts "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/GuardDetour.h"
click node_jli_integration "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/jli_defines.h"
click node_logger "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/Logger.cpp"
click node_java_entry "https://github.com/gravitlauncher/gravitguard/blob/v2-beta/demo-application/src/main/java/org/example/Main.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher_project,node_launcher_entry toneBlue
class node_guard_project,node_dll_entry,node_guard_core,node_guard_api,node_guard_logic,node_hook_layer,node_detour_contracts,node_jli_integration,node_logger toneAmber
class node_java_entry toneMint
class node_windows,node_jdk,node_minhook toneRose
class node_solution toneNeutral
```

## Components

### Native Launcher

- [Launcher project](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GravitGuard2/GravitGuard2.vcxproj): MSBuild project · `GravitGuard2/GravitGuard2.vcxproj`
- [Native launcher entry](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GravitGuard2/GravitGuard2.cpp): Windows executable · Establishes the protected process or JVM environment. · `GravitGuard2/GravitGuard2.cpp`

### Guard DLL

- [Guard DLL project](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/GuardDLL.vcxproj): MSBuild project · `GuardDLL/GuardDLL.vcxproj`
- [DLL lifecycle entry](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/dllmain.cpp): DLL entry point · Attaches guard functionality to DLL lifecycle events. · `GuardDLL/dllmain.cpp`
- [GravitGuard core](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/GravitGuard.cpp): protection API · Principal guard-facing implementation. · `GuardDLL/GravitGuard.cpp`
- [GravitGuard API](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/GravitGuard.h): header · `GuardDLL/GravitGuard.h`
- [Guard logic](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/guard.cpp): protection logic · `GuardDLL/guard.cpp`
- [Hook layer](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/hooks.cpp): interception · Installs hooks and handles hook callbacks. · `GuardDLL/hooks.cpp`
- [Detour contracts](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/GuardDetour.h): hook abstractions · `GuardDLL/GuardDetour.h`
- [JLI integration](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/jli_defines.h): JVM interface definitions · Connects the native guard to Java launcher/JLI interfaces. · `GuardDLL/jli_defines.h`
- [Guard diagnostics](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GuardDLL/Logger.cpp): native logging · `GuardDLL/Logger.cpp`

### Java Target

- [Demo Java entry](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/demo-application/src/main/java/org/example/Main.java): Java application · Minimal JVM target started under native protection. · `demo-application/src/main/java/org/example/Main.java`

### Runtime Dependencies

- **Windows**: native runtime
- **JDK / JVM**: Java runtime · Provided through JAVA_HOME.
- **MinHook**: native detouring library · External or submodule dependency for API detouring.

### Other components

- [Visual Studio solution](https://github.com/gravitlauncher/gravitguard/blob/v2-beta/GravitGuard2.sln): build orchestration · Produces separate x86 and x64 Release builds. · `GravitGuard2.sln`

## Connections

- Visual Studio solution → Launcher project: builds
- Visual Studio solution → Guard DLL project: builds
- Launcher project → Native launcher entry: compiles
- Guard DLL project → DLL lifecycle entry: builds DLL
- Native launcher entry → DLL lifecycle entry: loads / coordinates
- DLL lifecycle entry → GravitGuard core: initializes
- GravitGuard core → GravitGuard API: implements
- GravitGuard core → Guard logic: uses
- Guard logic → Hook layer: applies policy through
- Hook layer → Detour contracts: uses
- Hook layer → MinHook: detours with
- GravitGuard core → JLI integration: integrates through
- Native launcher entry → JDK / JVM: starts / supervises
- JDK / JVM → Demo Java entry: executes
- Hook layer → Windows: intercepts runtime behavior
- GravitGuard core → Guard diagnostics: emits diagnostics
- JDK / JVM → Windows: runs on