# nethical6/digipaws architecture

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

- Interactive diagram: https://gitdiagram.com/nethical6/digipaws
- Repository: https://github.com/nethical6/digipaws

## Overview

- App Presentation Layer (UI)
- Activities, fragments, dialogs, and overlays found under app/src/main/java/nethical/digipaws/ui and its subdirectories.
- Examples: MainActivity, LauncherActivity, various fragments (e.g., installation, usage stats) and dialogs (e.g., StartFocusMode, TweakBlocker warnings).
- Service Layer
- Android services that handle background tasks and blocker logic located in app/src/main/java/nethical/digipaws/services.
- Examples: AppBlockerService, UsageTrackingService, KeywordBlockerService, GeneralFeaturesService, and ViewBlockerService.
- Core Blocking/Business Logic
- The blockers and their base classes found under the blockers package.
- Examples: BaseBlocker, AppBlocker, FocusModeBlocker, KeywordBlocker, and ViewBlocker. Also related data models and configurations exist under data/blockers.
- Receivers and System Integration
- The admin and accessibility receivers (e.g., AdminReceiver) that capture system-level events.
- Utilities and Helpers
- A collection of utility classes (e.g., CommonUtils, TimeTools, ShizukuRunner, UsageStatsHelper) that provide auxiliary functions.
- Configuration and Resource Layer
- XML files for service configuration (in res/xml) and layout files in res/layout that define UI structure.
- External Integration & Metadata
- Integration with external libraries (e.g., MPAndroidChart for charts) as well as using Shizuku components for special tasks.

##### Relationships and Data Flow
- The UI layer (Activities, Fragments, Dialogs) sends user actions to trigger service calls and interact with the core blockers.
- Services (such as the AppBlockerService and UsageTrackingService) operate in the background and monitor app usage events, interfacing with Android’s accessibility services.
- The Blockers (e.g., FocusModeBlocker, KeywordBlocker) act upon data provided by the services and user configurations to enforce blocking logic.
- Utility classes assist by managing configurations, scheduling notifications, and handling error logging (CrashLogger).
- Data flows from the accessibility or usage tracking components to the UI overlays (e.g., UsageStatOverlayManager) and widgets for real-time feedback.
- Receivers capture system events (e.g., admin events) which then trigger service actions or updates in the UI.

##### Architectural Patterns and Design Principles
- Layered/MVC/MVVM Pattern: Although not strictly using a formal pattern like MVVM, the app clearly separates UI components from core business logic (in services and blockers) and utility/data modules.
- Service-Oriented and Event-Driven: The accessibility service, usage tracking, and event receivers indicate a reactive approach based on system events.
- Modularity: The separation of blockers into distinct classes and packages, along with segregated configurations (e.g., XML service configs), shows a modular design intended for easy expansion (e.g., future gamified mode or external API integration).

## Diagram (Mermaid)

```mermaid
graph TD
    %% App Presentation Layer (UI)
    subgraph "App Presentation Layer (UI)"
        UI1("Activities/Fragments/Dialogs"):::ui
    end

    %% Service Layer
    subgraph "Service Layer"
        S1("AppBlockerService"):::service
        S2("UsageTrackingService"):::service
        S3("KeywordBlockerService"):::service
        S4("GeneralFeaturesService"):::service
        S5("ViewBlockerService"):::service
    end

    %% Core Blocking/Business Logic
    subgraph "Core Blocking/Business Logic"
        B1("Blockers Logic"):::blocker
        B2("Blockers Data&Config"):::blocker
    end

    %% Receivers and System Integration
    subgraph "Receivers and System Integration"
        R1("AdminReceiver"):::receiver
    end

    %% Utilities and Helpers
    subgraph "Utilities and Helpers"
        U1("CommonUtils/TimeTools/UsageStatsHelper"):::util
        U2("ShizukuRunner"):::util
    end

    %% Configuration and Resource Layer
    subgraph "Configuration and Resource Layer"
        C1("XML Configurations"):::config
        C2("UI Layout Files"):::config
    end

    %% External Integration & Metadata
    subgraph "External Integration & Metadata"
        E1("MPAndroidChart Integration"):::external
    end

    %% Future Expansion
    subgraph "Future Expansion (Gamified Mode)"
        FE1("Separate Gamified App"):::external
    end

    %% Relationships / Data Flows
    UI1 -->|"triggers"| S1
    UI1 -->|"triggers"| S2
    UI1 -->|"triggers"| S3
    UI1 -->|"triggers"| S4
    UI1 -->|"triggers"| S5

    S1 -->|"enforces"| B1
    S2 -->|"enforces"| B1
    S3 -->|"enforces"| B1
    S5 -->|"enforces"| B1

    R1 -->|"feedsEvents"| S1
    R1 -->|"feedsEvents"| S2

    S1 -->|"updates"| UI1
    S2 -->|"updates"| UI1

    B1 -->|"uses"| B2
    B1 -->|"reliesOn"| U1

    U2 -->|"assists"| S1
    U2 -->|"assists"| UI1
    U2 -->|"assists"| B1

    B2 -->|"references"| C1
    B2 -->|"references"| C2

    UI1 -->|"rendersCharts"| E1

    UI1 -.->|"futureLink"| FE1

    %% Click Events
    click UI1 "https://github.com/nethical6/digipaws/tree/kt-rewrite/app/src/main/java/nethical/digipaws/ui"
    click S1 "https://github.com/nethical6/digipaws/tree/kt-rewrite/app/src/main/java/nethical/digipaws/services"
    click B1 "https://github.com/nethical6/digipaws/tree/kt-rewrite/app/src/main/java/nethical/digipaws/blockers"
    click B2 "https://github.com/nethical6/digipaws/tree/kt-rewrite/app/src/main/java/nethical/digipaws/data/blockers"
    click R1 "https://github.com/nethical6/digipaws/blob/kt-rewrite/app/src/main/java/nethical/digipaws/receivers/AdminReceiver.kt"
    click U1 "https://github.com/nethical6/digipaws/tree/kt-rewrite/app/src/main/java/nethical/digipaws/utils"
    click U2 "https://github.com/nethical6/digipaws/blob/kt-rewrite/app/src/main/java/nethical/digipaws/utils/ShizukuRunner.kt"
    click C1 "https://github.com/nethical6/digipaws/tree/kt-rewrite/app/src/main/res/xml"
    click C2 "https://github.com/nethical6/digipaws/tree/kt-rewrite/app/src/main/res/layout"
    click E1 "https://github.com/nethical6/digipaws/tree/kt-rewrite/app/src/main/java/nethical/digipaws/views"

    %% Styles
    classDef ui fill:#f9c74f,stroke:#f9844a,stroke-width:2px;
    classDef service fill:#90be6d,stroke:#43aa8b,stroke-width:2px;
    classDef blocker fill:#f94144,stroke:#f3722c,stroke-width:2px;
    classDef receiver fill:#277da1,stroke:#577590,stroke-width:2px;
    classDef util fill:#f8961e,stroke:#f9c74f,stroke-width:2px;
    classDef config fill:#90caf9,stroke:#2196f3,stroke-width:2px;
    classDef external fill:#c5e99b,stroke:#a3d3a1,stroke-width:2px;
```
