# guolindev/permissionx architecture

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

- Interactive diagram: https://gitdiagram.com/guolindev/permissionx
- Repository: https://github.com/guolindev/permissionx

## Overview

##### Main Components
- Sample Application (“app”):
- Represents the client-side usage of the PermissionX library.
- Contains UI elements such as MainActivity, MainFragment, custom dialogs, and layouts.
- PermissionX Library (“permissionx”):
- Core library logic that encapsulates the permission request process.
- Contains several sub-modules/components:
– Permission Mediator (e.g., PermissionMediator.kt, PermissionX.java) which acts as the entry point.
– Request Handling Module (e.g., classes in the "request" package like ChainTask, RequestBuilder, and various specialized Request classes for background location, notifications, etc.).
– Callback Interfaces (e.g., ExplainReasonCallback, ForwardToSettingsCallback, RequestCallback) responsible for receiving events from the Android OS permission system.
– Dialog Components (in the "dialog" package) that create and display the rationale dialog, default dialogs, and a dialog fragment for permissions explanation.
- Android System/OS:
- Represents the underlying Android permission management system where runtime permissions are actually granted or denied by the user.

##### Defining Relationships and Interactions
- The Sample Application calls the PermissionX API (by calling PermissionX.init(activity)) to request permissions.
- The PermissionX Library uses the Permission Mediator to build a chain of permission request tasks:
- It first checks for permissions, then, if necessary, calls callback methods (onExplainRequestReason or onForwardToSettings) before finally executing the actual permission request.
- The Callbacks then interact with the Dialog components to display dialogs, and the user’s responses are propagated back through the PermissionX flow.
- Ultimately, the library communicates with the Android OS (invoking system APIs) to perform the actual permission request.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The sample app is strictly a consumer of the library, while the library itself cleanly separates UI/dialog handling, callback handling, and task chaining.
- Chain-of-Responsibility: The “request” package reflects a chain-based design where a series of permission related tasks are sequentially processed.
- Modularity and Reusability: By isolating different concerns (callbacks, dialogs, request tasks), the library is extensible and easily maintained.

##### Relevant Technologies, Frameworks, and Libraries
- Android Framework: The project relies on core Android SDK components (activities, fragments, manifest, etc.).
- Kotlin and Java: Code is written in both Kotlin (majority of the code, especially in the sample app and some of the library classes) and Java (supporting compatibility and API exposure).
- Gradle and Gradle Kotlin DSL: Project configuration and dependency management use Gradle scripts (build.gradle.kts, settings.gradle.kts, etc.).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Sample Application Subgraph
    subgraph "Sample Application"
        UI["Sample App UI (MainActivity, MainFragment, Custom Dialogs)"]:::ui
        Layouts["Sample App Layouts (XML layouts)"]:::ui
    end

    %% PermissionX Library Subgraph
    subgraph "PermissionX Library"
        subgraph "PermissionX API"
            PM["PermissionMediator.kt"]:::lib
            PX["PermissionX.java"]:::lib
        end
        REQ["Request Handling Module"]:::lib
        CB["Callback Interfaces"]:::lib
        DLG["Dialog Components"]:::lib
    end

    %% External Android System
    OS["Android OS (Runtime Permission System)"]:::system

    %% Relationships
    UI -->|"init()"| PM
    UI -->|"init()"| PX
    UI -->|"usesLayout"| Layouts

    PM -->|"buildChain"| REQ
    PX -->|"buildChain"| REQ

    REQ -->|"callback"| CB
    REQ -->|"dialogUI"| DLG

    CB -->|"requestPermission"| OS
    DLG -->|"userResponse"| UI

    %% Click Events
    click UI "https://github.com/guolindev/permissionx/tree/master/app/src/main/java/com/permissionx/app"
    click Layouts "https://github.com/guolindev/permissionx/tree/master/app/src/main/res/layout"
    click PM "https://github.com/guolindev/permissionx/blob/master/permissionx/src/main/java/com/permissionx/guolindev/PermissionMediator.kt"
    click PX "https://github.com/guolindev/permissionx/blob/master/permissionx/src/main/java/com/permissionx/guolindev/PermissionX.java"
    click REQ "https://github.com/guolindev/permissionx/tree/master/permissionx/src/main/java/com/permissionx/guolindev/request"
    click CB "https://github.com/guolindev/permissionx/tree/master/permissionx/src/main/java/com/permissionx/guolindev/callback"
    click DLG "https://github.com/guolindev/permissionx/tree/master/permissionx/src/main/java/com/permissionx/guolindev/dialog"

    %% Styling Classes
    classDef ui fill:#ffcc00,stroke:#000,stroke-width:1px;
    classDef lib fill:#99ff99,stroke:#000,stroke-width:1px;
    classDef system fill:#ccccff,stroke:#000,stroke-width:1px;
```
