# manabu-gt/debugoverlay-android architecture

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

- Interactive diagram: https://gitdiagram.com/manabu-gt/debugoverlay-android
- Repository: https://github.com/manabu-gt/debugoverlay-android

## Overview

##### Project type and purpose
- This is a multi‐module Android library project (built with Gradle) that produces:
- debugoverlay (core AAR) – a runtime overlay service and UI modules
- debugoverlay-no-op (no-operation stub for release/test)
- debugoverlay-ext-timber and debugoverlay-ext-netstats (optional extension modules)
- sample (Android application demonstrating usage)
- Purpose: allow Android developers to plug in performance/debug overlays (CPU, memory, FPS, logcat, network, Timber logs, or custom) into their apps via a uniform API.

##### File structure
- Root: settings.gradle includes five subprojects: debugoverlay, debugoverlay-no-op, debugoverlay-ext-timber, debugoverlay-ext-netstats, sample
- Each library subproject follows the standard Android Gradle module layout:
- build.gradle + gradle.properties + proguard-rules (where applicable)
- src/main/java/com/ms_square/... – core classes (OverlayModule, DataModule, ViewModule, service, modules)
- src/main/res + src/main/AndroidManifest.xml
- src/test for unit tests
- The sample app consumes the AARs (via local modules/libs) and shows how to compose modules with DebugOverlay.Builder
- Key build files: top‐level build.gradle orchestrates plugin versions; each subproject’s build.gradle exports an AAR.

##### README for additional insights
- Architecture is plugin-based: each OverlayModule bundles a DataModule and a ViewModule
- A Builder API configures which modules to install, positioning, styling, and whether to use the system window layer
- Extensions (Timber, NetStats) are separate modules that implement the same OverlayModule interface
- No‐op variant implements the same interfaces but does nothing, to avoid method count in production

##### Main components
a. Core components:
- DebugOverlay.Builder (configuration entrypoint)
- OverlayService (for system‐layer window management)
- OverlayModule (abstract interface)
– DataModule (collects metrics, notifies observers)
– ViewModule (creates/updates Android View)
- Android WindowManager/System Alert Window (overlay host)
b. Extension modules (subprojects):
- debugoverlay-ext-timber → TimberModule → TimberDataModule + TimberViewModule
- debugoverlay-ext-netstats → NetStatsModule → NetStatsDataModule + NetStatsView
c. No-op library: stub implementations of OverlayModule, DataModule, ViewModule
d. Sample app: depends on core & optional modules, invokes Builder, embeds OverlayService

##### Relationships and interactions
- Sample App/API Consumer calls DebugOverlay.Builder → selects modules → calls install()
- Builder instantiates OverlayService (or uses in-process windows)
- For each OverlayModule:
- DataModule.start() reads OS sources (/proc, Choreographer callbacks, Logcat streams, Network stats)
- DataModule pushes updates via observer callbacks
- ViewModule receives updates and updates Android View contents (TextView or custom layouts)
- OverlayService attaches these Views to WindowManager as system alert windows (or in‐app overlays)
- No-op modules are swapped in during release/test builds by Gradle’s debugCompile/releaseCompile configuration

##### Architectural patterns and design principles
- Plugin/Modular architecture: core library defines interfaces; modules conform to those
- Separation of concerns: data gathering (DataModule) vs. UI rendering (ViewModule)
- Builder pattern: central configuration API for assembling modules, styles, permissions
- Multi-project Gradle setup: isolates core, no-op, extensions, sample

##### Technologies, frameworks, libraries
- Android SDK (WindowManager, Service, Choreographer, BroadcastReceiver)
- Gradle (multi-module build, AARs)
- Java (interfaces, observer pattern)
- Optional: Timber logging library for TimberModule

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Gradle Multi-Module"
        subgraph "Core Library"
            DBG["DebugOverlay.Builder"]:::core
            SVR["OverlayService"]:::core
            OVM["OverlayViewManager"]:::core
            OM["OverlayModule"]:::core
            DM["DataModule"]:::core
            VM["ViewModule"]:::core
        end
        subgraph "Extensions"
            TM["TimberModule"]:::ext
            TDM["TimberDataModule"]:::ext
            NM["NetStatsModule"]:::ext
            NDM["NetStatsDataModule"]:::ext
        end
        subgraph "No-op Library"
            NDBG["DebugOverlay.Builder (stub)"]:::noop
            NOM["OverlayModule (stub)"]:::noop
            NDM2["DataModule (stub)"]:::noop
            NVM2["ViewModule (stub)"]:::noop
        end
    end
    subgraph "Sample App"
        APP["DebugOverlaySampleApplication"]:::sample
        ACT["MainActivity"]:::sample
    end
    WM["WindowManager / System Layer"]:::os
    OS["Android OS"]:::os

    ACT -->|"calls"| DBG
    DBG -->|"creates"| SVR
    SVR -->|"uses"| OVM
    SVR -->|"initializes modules"| OM
    OM --> DM
    OM --> VM
    DM -->|"collects metrics"| OS
    DM -->|"push updates"| VM
    VM -->|"render view"| SVR
    SVR -->|"attaches view"| WM
    WM -->|"managed by"| OS

    TM -->|implements| OM
    TDM -->|"data for"| TM
    NM -->|implements| OM
    NDM -->|"data for"| NM

    NDBG -->|stub for| NOM
    NOM --> NDM2
    NOM --> NVM2

    classDef core fill:#D0E8FF,stroke:#0066CC,color:#000
    classDef ext fill:#E0FFDC,stroke:#00AA00,color:#000
    classDef noop fill:#F0F0F0,stroke:#999,color:#000
    classDef sample fill:#FFE8C8,stroke:#CC6600,color:#000
    classDef os fill:#EEEEFF,stroke:#6666CC,color:#000

    click DBG "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/DebugOverlay.java"
    click SVR "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/DebugOverlayService.java"
    click OM "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/OverlayModule.java"
    click DM "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/DataModule.java"
    click VM "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/ViewModule.java"
    click OVM "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay/src/main/java/com/ms_square/debugoverlay/OverlayViewManager.java"
    click TM "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay-ext-timber/src/main/java/com/ms_square/debugoverlay_ext_timber/TimberModule.java"
    click TDM "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay-ext-timber/src/main/java/com/ms_square/debugoverlay_ext_timber/TimberDataModule.java"
    click NM "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay-ext-netstats/src/main/java/com/ms_square/debugoverlay_ext_netstats/NetStatsModule.java"
    click NDM "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay-ext-netstats/src/main/java/com/ms_square/debugoverlay_ext_netstats/NetStatsDataModule.java"
    click APP "https://github.com/manabu-gt/debugoverlay-android/blob/master/sample/src/main/java/com/ms_square/debugoverlay/sample/DebugOverlaySampleApplication.java"
    click ACT "https://github.com/manabu-gt/debugoverlay-android/blob/master/sample/src/main/java/com/ms_square/debugoverlay/sample/MainActivity.java"
    click NDBG "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay-no-op/src/main/java/com/ms_square/debugoverlay/DebugOverlay.java"
    click NOM "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay-no-op/src/main/java/com/ms_square/debugoverlay/OverlayModule.java"
    click NDM2 "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay-no-op/src/main/java/com/ms_square/debugoverlay/DataModule.java"
    click NVM2 "https://github.com/manabu-gt/debugoverlay-android/blob/master/debugoverlay-no-op/src/main/java/com/ms_square/debugoverlay/ViewModule.java"
```
