# friendoye/recyclerxray architecture

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

- Interactive diagram: https://gitdiagram.com/friendoye/recyclerxray
- Repository: https://github.com/friendoye/recyclerxray

## Overview

##### Project Type & Purpose
- This project is an Android debug library designed to help developers visually inspect and navigate RecyclerView layouts. It wraps RecyclerView.Adapter instances to provide extra debugging information – such as ViewHolder source links, visual previews, and custom parameters.
- It offers integrations with popular UI libraries like Epoxy and Groupie, and includes sample apps (sample, sample-epoxy, sample-groupie, sample-shared) that show real integration use cases. The README explains setup, initialization (using XRayInitializer), debugging modes, and advanced customizations.

##### Main Components
- Core Debug Library (library module): Contains the bulk of the core functionality, including classes like RecyclerXRay, LocalRecyclerXRay, XRayInitializer, custom debug view holders, internal adapters, and the core logic to wrap and intercept RecyclerView.Adapter.
- Integration Modules:
- Epoxy Integration (epoxy-integration): Provides specific classes (e.g., EpoxyLinkProvider) for debugging Epoxy-based adapters.
- Groupie Integration (groupie-integration): Provides analogous support for Groupie library compatibility via GroupieLinkProvider.
- Sample Applications:
- sample, sample-epoxy, sample-groupie, sample-shared: These demonstrate how to integrate and use RecyclerXRay in various environments and with different RecyclerView setups.
- Testing & Quality:
- A comprehensive test suite exists in the library module’s androidTest and test directories.
- Additional workflow and CI configuration files (in .github/workflows and others) ensure consistent build and integration testing.
- Supporting Elements:
- Build and configuration scripts for Gradle (build.gradle, deploy.gradle, settings.gradle, gradle wrapper files) that manage the project’s build, versioning, and integration with jcenter and other repositories.
- Documentation (docs folder) that contains screenshots and additional documentation for tests.

##### Relationships and Interactions
- Application Initialization Flow:
- The host Android Application calls XRayInitializer.init(this) during startup. This sets up either the real or no-op implementation based on build type.
- Adapter Wrapping:
- In the client code, the original RecyclerView.Adapter is wrapped with RecyclerXRay.wrap(adapter) or through LocalRecyclerXRay. The wrapped adapter intercepts calls and provides debugging functionality.
- The custom debug view holders and layouts (configured via XRaySettings) then provide visual overlays that display debug information.
- Integrations:
- The integration modules plug into the core by providing extra LoggableLinkProviders (like EpoxyLinkProvider and GroupieLinkProvider). They dynamically enhance the capability of RecyclerXRay to navigate and log clickable links to the appropriate source code in supported environments.
- Toggle Control:
- An AdbToggleReceiver component is integrated, allowing developers to switch debug modes via adb commands (broadcast intents). This shows how external control channels interact with the core debugging functionality.

- “RecyclerXRay Core” (including XRayInitializer, RecyclerXRay, LocalRecyclerXRay, XRaySettings, custom debug view holders, and internal adapters).
- “Integration Modules” (Epoxy Integration and Groupie Integration) as subsidiary modules that plug into the core, indicating dependency and extension.
- “External Interaction” (showing how ADB commands and possibly configuration via build.gradle and external repositories play a role).
- From the Android Application layer to the Initialization block.
- From the Application or Activities wrapping their RecyclerView.Adapters to the core RecyclerXRay module.
- From RecyclerXRay to its integrations, indicating optional enhancements for libraries like Epoxy and Groupie.

##### Architectural Patterns & Design Principles
- The library adopts a wrapper or decorator pattern for RecyclerView.Adapter, intercepting and augmenting functionality.
- There is an extension principle (via interfaces such as XRayCustomParamsAdapterProvider and XRayCustomParamsViewHolderProvider) which lets clients supply additional debugging data.
- The modular design (with clear separation between core, integration-specific modules, and samples) makes the codebase extensible and easy to integrate with different RecyclerView setups.
- Configuration via dependency injection-like patterns (through XRaySettings and builder methods) that allow for fine-grained control over behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("Android Application"):::external
    U("UI RecyclerView Adapter"):::external

    subgraph "Core Debug Library"
        X1("XRayInitializer"):::core
        R("RecyclerXRay & LocalRecyclerXRay"):::core
        S("XRaySettings & Debug View Holders"):::core
        I("Internal Adapter & Debug Logic"):::core
        ADB("ADB Toggle Receiver"):::core
    end

    subgraph "Integration Modules"
        E("Epoxy Integration"):::integration
        G("Groupie Integration"):::integration
    end

    subgraph "Sample Applications"
        S1("Standard Sample App"):::sample
        S2("Epoxy Sample App"):::sample
        S3("Groupie Sample App"):::sample
        S4("Shared Sample App"):::sample
    end

    subgraph "Testing & CI"
        T("Library Tests"):::test
        CI("CI Workflows"):::test
    end

    subgraph "Build & Supporting Assets"
        B("Build & Configuration Scripts"):::build
        D("Documentation & Supporting Assets"):::build
    end

    A -->|"calls_init"| X1
    U -->|"wrap(adapter)"| R
    X1 -->|"configures"| R
    S -->|"configures_view"| R
    R -->|"manages"| I
    ADB -->|"toggle_debug"| R
    R -->|"enhances"| E
    R -->|"enhances"| G
    R -->|"used_in"| S1
    R -->|"used_in"| S2
    R -->|"used_in"| S3
    R -->|"used_in"| S4
    X1 -->|"tested_by"| T
    CI --- T
    B -->|"build_config"| X1
    D -->|"docs"| X1

    click X1 "https://github.com/friendoye/recyclerxray/blob/main/library/src/main/java/com/friendoye/recyclerxray/XRayInitializer.kt"
    click R "https://github.com/friendoye/recyclerxray/blob/main/library/src/main/java/com/friendoye/recyclerxray/RecyclerXRay.kt"
    click R "https://github.com/friendoye/recyclerxray/blob/main/library/src/main/java/com/friendoye/recyclerxray/LocalRecyclerXRay.kt"
    click S "https://github.com/friendoye/recyclerxray/blob/main/library/src/main/java/com/friendoye/recyclerxray/XRaySettings.kt"
    click S "https://github.com/friendoye/recyclerxray/blob/main/library/src/main/java/com/friendoye/recyclerxray/XRayDebugViewHolder.kt"
    click I "https://github.com/friendoye/recyclerxray/tree/main/library/src/main/java/com/friendoye/recyclerxray/internal"
    click ADB "https://github.com/friendoye/recyclerxray/blob/main/library/src/main/java/com/friendoye/recyclerxray/AdbToggleReceiver.kt"
    click E "https://github.com/friendoye/recyclerxray/blob/main/epoxy-integration/src/main/java/com/friendoye/recyclerxray/EpoxyLinkProvider.kt"
    click G "https://github.com/friendoye/recyclerxray/blob/main/groupie-integration/src/main/java/com/friendoye/recyclerxray/GroupieLinkProvider.kt"
    click S1 "https://github.com/friendoye/recyclerxray/tree/main/sample"
    click S2 "https://github.com/friendoye/recyclerxray/tree/main/sample-epoxy"
    click S3 "https://github.com/friendoye/recyclerxray/tree/main/sample-groupie"
    click S4 "https://github.com/friendoye/recyclerxray/tree/main/sample-shared"
    click T "https://github.com/friendoye/recyclerxray/tree/main/library/src/test"
    click T "https://github.com/friendoye/recyclerxray/tree/main/library/src/androidTest"
    click CI "https://github.com/friendoye/recyclerxray/blob/main/.github/workflows/ci.yml"
    click B "https://github.com/friendoye/recyclerxray/blob/main/build.gradle"
    click D "https://github.com/friendoye/recyclerxray/tree/main/docs"

    classDef core fill:#f4cccc,stroke:#b45f06,stroke-width:2px;
    classDef integration fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef sample fill:#cfe2f3,stroke:#3c78d8,stroke-width:2px;
    classDef test fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
    classDef build fill:#ead1dc,stroke:#b04499,stroke-width:2px;
    classDef external fill:#d9d2e9,stroke:#6a329f,stroke-width:2px;
```
