# lenni0451/reflect architecture

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

- Interactive diagram: https://gitdiagram.com/lenni0451/reflect
- Repository: https://github.com/lenni0451/reflect

## Overview

##### Project Type and Purpose
- This is a Java library (“Reflect”) offering a unified API to perform advanced reflection tasks and bypass the usual JVM restrictions (e.g., inaccessible members, module boundaries).
- It provides builders for bytecode generation (via ASM), dynamic proxies, local variable capture, stream-style reflection queries, and utility helpers. There is also a dedicated `j9` submodule for Java 9+ module support.

##### File Structure Analysis
- Top─level: Gradle build files, `src/` main module, `j9/` Java 9 compatibility module, `config/`, templates, and tests.
- `src/main/java/net/lenni0451/reflect`: core reflection APIs (Classes, Fields, Methods, Modules, etc.).
- Subpackages:
- `bytecode` → bytecode builders & wrappers (ASM-based implementations)
- `proxy` → proxy generation abstractions and runtime
- `localcapture` → capturing local stack frames & values
- `stream` → fluent reflection-based streams
- `accessor`, `wrapper`, `exceptions`, `utils`
- `j9/src/main/java/...`: mirrors core logic but with module‐safe implementations.

##### Key Architecture Insights from README
- Primary concern is modularity: separate concerns (core reflection vs. code-gen vs. proxy vs. Java 9 module hacks).

##### Main Components
a. Core Module
- Entry point classes (net.lenni0451.reflect.*)
- Basic operations: find classes, fields, methods, manipulate objects
b. Bytecode Engine
- High-level builders (`bytecode.builder`)
- ASM implementations (`bytecode.impl.asm`)
- Wrappers (`bytecode.wrapper`)
c. Proxy Module
- Public API (`reflect.proxy.*`)
- Internal builders & runtime (`.impl`, `.internal`)
d. LocalCapture Module
- And inspect local variables at runtime
e. Stream API
- Fluent reflection streams (constructor, field, method streams)
f. Utilities & Exceptions
- Helpers (ObjectPrinter, FieldInitializer)
- Custom exceptions
g. j9 Compatibility Module
- Overrides or extensions for Java 9 module access
h. Build & Distribution
- Gradle build scripts, templates (Mustache), generated `UnsafeAccess` code
- Publication to Maven repositories

##### Component Relationships and Data Flows
- Core → Proxy Module (to build dynamic proxies)
- Core → LocalCapture (to snapshot local stack frames)
- Bytecode Engine uses ASM library (external)
- Proxy Module depends on Bytecode Engine for instrumentation
- j9 Module plugs into Reflect Core and Proxy to adjust access for modules
- Templates feed into codegen at build time (UnsafeAccess.mustache → generated Java)
- Build subsystem packages everything into a JAR and publishes to Maven

##### Architectural Patterns & Principles
- Modular layered design: core API layer, codegen layer, runtime helpers
- Builder pattern in bytecode and proxy generation
- Abstraction over ASM and Unsafe primitives
- Extension point via `j9` submodule

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Reflection APIs
    subgraph "Reflect Core Module"
        direction TB
        Core["Reflect Core\n(net.lenni0451.reflect)"]:::core
        Stream["Stream API\n(net.lenni0451.reflect.stream)"]:::core
        LocalCap["LocalCapture Module\n(net.lenni0451.reflect.localcapture)"]:::core
    end

    %% Bytecode Engine
    subgraph "Bytecode Engine" 
        direction TB
        Builder["Bytecode Builders\n(bytecode.builder)"]:::codegen
        ASM_Impl["ASM Implementations\n(bytecode.impl.asm)"]:::codegen
        Wrapper["Bytecode Wrappers\n(bytecode.wrapper)"]:::codegen
    end

    %% Proxy Module
    subgraph "Proxy Module"
        direction TB
        Proxy_API["Proxy Public API\n(proxy)"]:::codegen
        Proxy_Impl["Proxy Internal Builders\n(proxy/impl)"]:::codegen
        Proxy_Int["Proxy Runtime Internal\n(proxy/internal)"]:::codegen
    end

    %% Utilities & Exceptions
    subgraph "Utilities & Exceptions"
        direction TB
        Utils["Utilities\n(utils)"]:::util
        Exceptions["Exceptions\n(exceptions)"]:::util
    end

    %% j9 Compatibility
    subgraph "j9 Compatibility Module"
        direction TB
        J9_Core["j9 Core Overrides\n(j9/net.lenni0451.reflect)"]:::compat
        J9_LC["j9 LocalCapture Overrides\n(j9/localcapture)"]:::compat
    end

    %% Build & Distribution
    subgraph "Build & Distribution"
        direction TB
        Gradle["Gradle Scripts"]:::build
        Templates["Codegen Templates\n(UnsafeAccess.mustache/json)"]:::build
        Generated["Generated UnsafeAccess.java"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ASM_lib["ASM Library"]:::external
        Mustache["Mustache Templates"]:::external
        Unsafe["Unsafe API"]:::external
    end

    %% Connections
    Core -->|"generates bytecode"| Builder
    Builder -->|"uses ASM"| ASM_lib
    Builder -->|"wraps primitives"| Wrapper
    Core -->|"builds proxies"| Proxy_API
    Proxy_API -->|"instrumentation via"| Builder
    Proxy_Impl --> Proxy_Int
    Core -->|"captures stack"| LocalCap
    Core -->|"streams reflection"| Stream
    Core -->|"helper calls"| Utils
    Core -->|"throws"| Exceptions
    J9_Core -->|"augments access"| Core
    J9_LC -->|"overrides capture"| LocalCap
    Gradle -->|"processes templates"| Templates
    Templates -->|"generates"| Generated
    Generated -->|"integrates into"| Core
    Gradle -->|"packages modules"| Core
    Gradle -->|"publishes JAR"| Maven[(Maven Central)]:::external
    Proxy_API -->|"requires Unsafe"| Unsafe
    LocalCap -->|"requires Unsafe"| Unsafe

    %% Click Events
    click Core "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect"
    click Stream "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/stream"
    click LocalCap "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/localcapture"
    click Builder "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/bytecode/builder"
    click ASM_Impl "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/bytecode/impl/asm"
    click Wrapper "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/bytecode/wrapper"
    click Proxy_API "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/proxy"
    click Proxy_Impl "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/proxy/impl"
    click Proxy_Int "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/proxy/internal"
    click Utils "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/utils"
    click Exceptions "https://github.com/lenni0451/reflect/tree/main/src/main/java/net/lenni0451/reflect/exceptions"
    click J9_Core "https://github.com/lenni0451/reflect/tree/main/j9/src/main/java/net/lenni0451/reflect"
    click J9_LC "https://github.com/lenni0451/reflect/tree/main/j9/src/main/java/net/lenni0451/reflect/localcapture"
    click Gradle "https://github.com/lenni0451/reflect/blob/main/build.gradle"
    click Settings "https://github.com/lenni0451/reflect/blob/main/settings.gradle"
    click Gradlew "https://github.com/lenni0451/reflect/tree/main/gradlew"
    click GradlewBat "https://github.com/lenni0451/reflect/blob/main/gradlew.bat"
    click WrapperDir "https://github.com/lenni0451/reflect/tree/main/gradle/wrapper/"
    click Template1 "https://github.com/lenni0451/reflect/blob/main/src/main/templates/UnsafeAccess.mustache"
    click Template2 "https://github.com/lenni0451/reflect/blob/main/src/main/templates/UnsafeAccess.json"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#1E70BF,color:#1E70BF;
    classDef codegen fill:#E0FFD0,stroke:#3F8F1E,color:#3F8F1E;
    classDef util fill:#F0F0F0,stroke:#888888,color:#555555;
    classDef compat fill:#FFE0B2,stroke:#BF6E00,color:#BF6E00;
    classDef build fill:#F8F0E0,stroke:#B07000,color:#B07000;
    classDef external fill:#F3E6FF,stroke:#8A2BE2,color:#8A2BE2;
```
