# x-slayer/notification_listener_service architecture

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

- Interactive diagram: https://gitdiagram.com/x-slayer/notification_listener_service
- Repository: https://github.com/x-slayer/notification_listener_service

## Overview

##### Project type & purpose (what you’re diagramming)
This repository is a **Flutter plugin** (Dart package + Android platform implementation) that lets a Flutter app:
- **Check/request Notification Listener permission**
- **Receive Android notification posted/removed events** as a Dart **Stream**
- **Reply to notifications** (via Android RemoteInput / actions)

So the “system” you’re diagramming is not a typical backend; it’s a **mobile plugin architecture** bridging **Flutter (Dart)** ↔ **Android OS NotificationListenerService APIs**.

##### Repo structure to architectural components
Use the file tree to identify boundaries:

##### Dart / Flutter package (public API surface)
- `lib/notification_listener_service.dart`
Likely the main API: permission methods + `notificationsStream`.
- `lib/notification_event.dart`
Data model (e.g., `ServiceNotificationEvent`) and helper methods like `sendReply`.

##### Android platform implementation (the real “engine”)
- `android/src/main/java/notification/listener/service/NotificationListener.java`
The Android **NotificationListenerService** subclass that receives OS callbacks.
- `android/src/main/java/notification/listener/service/NotificationListenerServicePlugin.java`
The Flutter plugin entrypoint: sets up **MethodChannel/EventChannel** and binds to service/event stream.
- `android/src/main/java/notification/listener/service/NotificationReceiver.java`
BroadcastReceiver or internal receiver for actions/replies or lifecycle events.
- `android/src/main/java/notification/listener/service/NotificationUtils.java`
- `android/src/main/java/notification/listener/service/NotificationConstants.java`
Channel names, intent actions, keys, etc.
- `android/src/main/java/notification/listener/service/models/*`
Reply/action support:
- `Action.java` (an action model)
- `RemoteInputParcel.java` (parcelable remote input data)
- `ActionCache.java` (stores actions per notification for later reply)

##### Tests
- `test/notification_listener_service_test.dart`
Likely Dart-side API tests (not Android instrumentation).

##### What the README tells you to emphasize
The README explicitly defines:
- **Manifest service binding requirement** (`BIND_NOTIFICATION_LISTENER_SERVICE`)
- **Permission workflow** (`isPermissionGranted()`, `requestPermission()`)
- **Event streaming contract** (notifications posted/removed)
- **Reply flow** (`event.sendReply()`)

##### Dart Plugin Layer
- `NotificationListenerService` (API facade)
- `ServiceNotificationEvent` (event model + reply method)
##### Flutter Platform Channels
- **MethodChannel** for permission checks / requests / reply commands
- **EventChannel** for notification event stream
##### Android Plugin Layer
- `NotificationListenerServicePlugin` (channel handlers, wiring)
##### Android Service
- `NotificationListener` (extends NotificationListenerService)
##### Android OS / Framework
- NotificationManager / System UI pipeline (conceptual)
##### Supporting Android components
- `NotificationReceiver` (broadcast/action handling)
- `ActionCache`, `RemoteInputParcel`, `Action` (reply/action data plane)
- `NotificationUtils` (parsing/serialization)
##### External Actor
- “Other Apps” that post notifications (WhatsApp, Gmail, etc.)

- Other Apps → Android OS → `NotificationListener` (posted/removed callbacks)
- `NotificationListener` → Android Plugin (`NotificationListenerServicePlugin`) → EventChannel → Dart Stream → Flutter App UI
- Flutter App → Dart API → MethodChannel → Android Plugin → (opens Settings for permission / checks status)
- Flutter App → `event.sendReply()` → MethodChannel → Android Plugin → `ActionCache`/`RemoteInputParcel` → Android OS notification action dispatch

##### “Notification received” sequence
Lifelines:
- Other App
- Android OS
- `NotificationListener` (service)
- `NotificationUtils`
- `NotificationListenerServicePlugin`
- EventChannel
- Dart `NotificationListenerService.notificationsStream`
- Flutter App listener

Show:

##### “Reply to notification” sequence
Lifelines:
- Flutter App
- Dart `ServiceNotificationEvent.sendReply`
- MethodChannel
- `NotificationListenerServicePlugin`
- `ActionCache` / `RemoteInputParcel`
- Android OS (RemoteInput / notification action)
- Target app (recipient of reply)

Show:

##### Architectural patterns to call out explicitly
- **Flutter Plugin architecture** (Dart API + platform implementation)
- **Event-driven streaming** (Android callbacks → EventChannel → Dart Stream)
- **Command/query split over MethodChannel**:
- Query: `isPermissionGranted`
- Command: `requestPermission`, `sendReply`
- **OS-managed service lifecycle** (NotificationListenerService is controlled by Android)
- **Caching layer for actions** (`ActionCache`) enabling deferred reply calls

On components, annotate:
- Flutter / Dart (`lib/*`)
- Flutter Platform Channels (MethodChannel/EventChannel)
- Android (Java)
- Android `NotificationListenerService`
- Android `RemoteInput` / notification actions (conceptual, even if wrapped by your code)
- Android Manifest binding + permission (`BIND_NOTIFICATION_LISTENER_SERVICE`)
- (Optional) Settings screen / permission UI as an OS subsystem

##### Minimum “best” output to aim for
Deliverables that will be both accurate and useful:
- “Flutter app process” vs “Android system service callbacks”
- Manifest-declared service binding requirement

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Component / Container Diagram (Vertical)
  %% =========================================================
  subgraph "Context: Android Notifications Ecosystem"
    direction TB
    OtherApps["Other Apps\n(WhatsApp, Gmail, etc.)"]:::external
    AndroidOS["Android OS / Framework\n(NotificationManager, System UI,\nSettings Permission UI)"]:::os
  end

  subgraph "Flutter App (Consumer)"
    direction TB
    ExampleApp["Example Flutter App\n(UI + integration)"]:::app
  end

  subgraph "Dart Plugin Layer (Flutter / Dart)"
    direction TB
    DartAPI["NotificationListenerService\n(Dart API facade)"]:::dart
    DartEvent["ServiceNotificationEvent\n(model + sendReply())"]:::dart
    DartTests["Dart Tests"]:::test
  end

  subgraph "Platform Channel Bridge (Flutter ↔ Android)"
    direction TB
    MethodCh["MethodChannel\n(commands/queries)"]:::bridge
    EventCh["EventChannel\n(stream)"]:::bridge
  end

  subgraph "Android Platform Implementation (Java)"
    direction TB

    subgraph "Plugin Entrypoint"
      direction TB
      AndroidPlugin["NotificationListenerServicePlugin\n(channel wiring + handlers)"]:::android
      AndroidConstants["NotificationConstants\n(channel names, intent keys)"]:::android
    end

    subgraph "OS-managed Service & Supporting Components"
      direction TB
      NLSvc(["NotificationListener\nextends NotificationListenerService"]):::service
      NUtils["NotificationUtils\n(extract/serialize notification fields)"]:::android
      NReceiver["NotificationReceiver\n(BroadcastReceiver/action handling)"]:::android

      subgraph "Reply / Action Data Plane"
        direction TB
        ActionCache["ActionCache\n(cache actions per notification)"]:::cache
        ActionModel["Action\n(model)"]:::android
        RemoteInputP["RemoteInputParcel\n(parcelable remote input)"]:::android
      end
    end

    AndroidManifest["AndroidManifest.xml\n(BIND_NOTIFICATION_LISTENER_SERVICE)"]:::manifest
  end

  %% ---- Architecture relationships (vertical, minimal horizontal) ----
  OtherApps -->|"posts/removes notifications"| AndroidOS
  AndroidOS -->|"OS-callbacks\nonNotificationPosted/onNotificationRemoved"| NLSvc

  NLSvc -->|"parses/builds payload"| NUtils
  NLSvc -->|"updates cached actions"| ActionCache

  %% Event-driven streaming (dashed)
  NLSvc -.->|"notification events"| AndroidPlugin
  AndroidPlugin -.->|"emit events"| EventCh
  EventCh -.->|"deliver stream events"| DartAPI
  DartAPI -.->|"notificationsStream"| DartEvent
  DartEvent -.->|"Stream listener"| ExampleApp

  %% Permission workflow (commands/queries)
  ExampleApp -->|"isPermissionGranted()\nrequestPermission()"| DartAPI
  DartAPI -->|"invoke"| MethodCh
  MethodCh -->|"query/command"| AndroidPlugin
  AndroidPlugin -->|"open Settings / check status"| AndroidOS

  %% Reply flow (command)
  ExampleApp -->|"event.sendReply(text)"| DartEvent
  DartEvent -->|"invoke sendReply"| MethodCh
  MethodCh -->|"sendReply command"| AndroidPlugin
  AndroidPlugin -->|"lookup action + remote inputs"| ActionCache
  AndroidPlugin -->|"construct RemoteInput"| RemoteInputP
  AndroidPlugin -->|"dispatch notification action"| AndroidOS
  AndroidOS -->|"deliver reply"| OtherApps

  %% Wiring / dependencies
  AndroidPlugin -->|"uses"| AndroidConstants
  AndroidPlugin -->|"registers receiver / intents"| NReceiver
  AndroidManifest -->|"declares service + permission"| NLSvc

  %% Tests relationship
  DartTests -->|"tests Dart API/model"| DartAPI
  DartTests -->|"tests event model"| DartEvent

  %% =========================================================
  %% Sequence Diagram 1: Notification received (Vertical)
  %% =========================================================
  subgraph "Sequence: Notification received (Event Stream)"
    direction TB
    Seq1Title["(Sequence) Notification posted → Dart Stream"]:::seqtitle

    Seq1Other["Other App"]:::external
    Seq1OS["Android OS"]:::os
    Seq1Svc["NotificationListener (NLS service)"]:::service
    Seq1Utils["NotificationUtils"]:::android
    Seq1Plugin["NotificationListenerServicePlugin"]:::android
    Seq1EventCh["EventChannel"]:::bridge
    Seq1DartStream["NotificationListenerService.notificationsStream"]:::dart
    Seq1Flutter["Flutter App listener"]:::app

    Seq1Other -->|"posts notification"| Seq1OS
    Seq1OS -->|"onNotificationPosted()"| Seq1Svc
    Seq1Svc -->|"extract fields/images"| Seq1Utils
    Seq1Utils -->|"payload"| Seq1Svc
    Seq1Svc -.->|"event payload"| Seq1Plugin
    Seq1Plugin -.->|"send event"| Seq1EventCh
    Seq1EventCh -.->|"stream event"| Seq1DartStream
    Seq1DartStream -.->|"emit ServiceNotificationEvent"| Seq1Flutter
  end

  %% =========================================================
  %% Sequence Diagram 2: Reply to notification (Vertical)
  %% =========================================================
  subgraph "Sequence: Reply to notification (RemoteInput)"
    direction TB
    Seq2Title["(Sequence) sendReply() → MethodChannel → RemoteInput/action dispatch"]:::seqtitle

    Seq2Flutter["Flutter App"]:::app
    Seq2Event["ServiceNotificationEvent.sendReply()"]:::dart
    Seq2Method["MethodChannel"]:::bridge
    Seq2Plugin["NotificationListenerServicePlugin"]:::android
    Seq2Cache["ActionCache"]:::cache
    Seq2Remote["RemoteInputParcel"]:::android
    Seq2OS["Android OS (RemoteInput/action)"]:::os
    Seq2Target["Target App"]:::external

    Seq2Flutter -->|"call sendReply(text)"| Seq2Event
    Seq2Event -->|"invoke method"| Seq2Method
    Seq2Method -->|"sendReply(notificationId,actionKey,text)"| Seq2Plugin
    Seq2Plugin -->|"find cached action"| Seq2Cache
    Seq2Plugin -->|"rebuild RemoteInput"| Seq2Remote
    Seq2Plugin -->|"dispatch action intent"| Seq2OS
    Seq2OS -->|"deliver reply"| Seq2Target
    Seq2Plugin -->|"return result"| Seq2Method
    Seq2Method -->|"complete Future"| Seq2Event
  end

  %% =========================================================
  %% Click events (from component_mapping)
  %% =========================================================
  click DartAPI "https://github.com/x-slayer/notification_listener_service/blob/main/lib/notification_listener_service.dart"
  click DartEvent "https://github.com/x-slayer/notification_listener_service/blob/main/lib/notification_event.dart"
  click AndroidPlugin "https://github.com/x-slayer/notification_listener_service/blob/main/android/src/main/java/notification/listener/service/NotificationListenerServicePlugin.java"
  click NLSvc "https://github.com/x-slayer/notification_listener_service/blob/main/android/src/main/java/notification/listener/service/NotificationListener.java"
  click NReceiver "https://github.com/x-slayer/notification_listener_service/blob/main/android/src/main/java/notification/listener/service/NotificationReceiver.java"
  click NUtils "https://github.com/x-slayer/notification_listener_service/blob/main/android/src/main/java/notification/listener/service/NotificationUtils.java"
  click AndroidConstants "https://github.com/x-slayer/notification_listener_service/blob/main/android/src/main/java/notification/listener/service/NotificationConstants.java"
  click ActionModel "https://github.com/x-slayer/notification_listener_service/blob/main/android/src/main/java/notification/listener/service/models/Action.java"
  click RemoteInputP "https://github.com/x-slayer/notification_listener_service/blob/main/android/src/main/java/notification/listener/service/models/RemoteInputParcel.java"
  click ActionCache "https://github.com/x-slayer/notification_listener_service/blob/main/android/src/main/java/notification/listener/service/models/ActionCache.java"
  click AndroidManifest "https://github.com/x-slayer/notification_listener_service/blob/main/android/src/main/AndroidManifest.xml"
  click ExampleApp "https://github.com/x-slayer/notification_listener_service/blob/main/example/lib/main.dart"
  click DartTests "https://github.com/x-slayer/notification_listener_service/blob/main/test/notification_listener_service_test.dart"

  %% example android bits
  click Seq1Flutter "https://github.com/x-slayer/notification_listener_service/blob/main/example/lib/main.dart"
  click Seq2Flutter "https://github.com/x-slayer/notification_listener_service/blob/main/example/lib/main.dart"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef app fill:#D6EAF8,stroke:#1B4F72,stroke-width:1.5px,color:#0B2E4A
  classDef dart fill:#AED6F1,stroke:#21618C,stroke-width:1.5px,color:#0B2E4A
  classDef bridge fill:#D5F5E3,stroke:#1E8449,stroke-width:1.5px,color:#0B3D1E
  classDef android fill:#FAD7A0,stroke:#B9770E,stroke-width:1.5px,color:#4A2C00
  classDef service fill:#F8C471,stroke:#AF601A,stroke-width:2px,color:#4A2C00
  classDef cache fill:#FDEBD0,stroke:#B9770E,stroke-width:1.5px,color:#4A2C00
  classDef os fill:#E5E7E9,stroke:#566573,stroke-width:1.5px,color:#1C2833
  classDef external fill:#D7DBDD,stroke:#424949,stroke-width:1.5px,color:#1C2833
  classDef manifest fill:#F5EEF8,stroke:#6C3483,stroke-width:1.5px,color:#2E1036
  classDef test fill:#EBDEF0,stroke:#7D3C98,stroke-width:1.5px,color:#2E1036
  classDef seqtitle fill:#FFFFFF,stroke:#85929E,stroke-width:1px,color:#2C3E50
```
