# emmaguy/wear-notify-for-reddit architecture

> Architecture diagram of the GitHub repository emmaguy/wear-notify-for-reddit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/emmaguy/wear-notify-for-reddit
- Repository: https://github.com/emmaguy/wear-notify-for-reddit

## Overview

##### Project Type and Purpose
- This is a multi-module Android application (“Wear Notify for Reddit”) that pushes content from Reddit to an Android phone and wearable.
- Modules:
- mobile – the phone app (settings UI, fetch‐and‐sync engine, notification sender, Wear Data Layer client)
- wear – the watch app (notification listener, UI for posts/comments/actions)
- sharedlib – common model objects (Post, Comment, Constants, drawables)

##### High‐Level Architectural Overview
- External services:
- Reddit REST API (authentication, listing, comments)
- Pocket API (save to Pocket)
- Local storage: Android SharedPreferences (token storage, user settings, action order)
- Dependency injection: Dagger modules (AppModule, StorageModule, SettingsModule) provide singletons throughout both mobile and wear modules.
- Synchronization: mobile periodically fetches new posts & direct messages via a background alarm (BackgroundAlarmListener → LatestPostsRetriever → RedditService). Results are converted, filtered, persisted (if needed), and then forwarded to the watch via WearableListenerService.
- Notification pipeline: mobile packages data items/notifications to the watch; wear’s NotificationListenerService listens for them and displays native watch notifications with actions (reply, upvote, view image/comments).

##### Main Components
- Frontend (mobile UI): SettingsActivity (subreddit picker, action reorder)
- Backend (mobile fetch engine):
– BackgroundAlarmListener → RetrieveService → Retrofit‐backed RedditAuthenticationService/RedditService
– Converters (JSON → Java models) in refresh/
– TokenRefreshInterceptor handles OAuth token lifecycle
- Local Storage (mobile): SharedPreferencesTokenStorage, UserStorage, UniqueIdentifierStorage
- Wear Data Layer Client (mobile): WearableListenerService sends DataApi messages to wearable
- Frontend (wear UI): MainActivity, CommentsActivity, ViewImageActivity, PanView, comment fragments
- Notification Listener (wear): NotificationListenerService displays rich notifications
- Shared Library: Comment, Post models + resource drawables used by both modules

##### Relationships and Data Flows
1. User configures settings in mobile UI → writes to SharedPreferences via SettingsModule
2. Alarm triggers BackgroundAlarmListener → calls LatestPostsRetriever → uses RedditService (Retrofit) authenticated by Token and TokenRefreshInterceptor → JSON responses → converters → Java models
3. Mobile sends DataItems/MessageEvents via WearableListenerService → Wear Data Layer → watch
4. Wear receives data → NotificationListenerService publishes notifications → user taps actions → Intents handled by wear Activities/Services → may send reply back to mobile (e.g. voice reply)
5. “Save to Pocket” action invokes PocketUtils on the phone via the phone’s Pocket app

##### Architectural Patterns & Principles
- Modularization: mobile vs. wear vs. sharedlib
- Separation of concerns: UI, networking, storage, DI
- Dependency Injection (Dagger) for testability (mobile/src/test covers converters, retriever, token interceptor)
- Observer/publisher (Wearable Data Layer) for inter-device comms
- Retrofit + interceptors for clean REST integration
- JSON converters (delegating converter pattern)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Mobile Module
    subgraph "Mobile Module"
        direction TB

        subgraph "UI (Mobile)"
            direction TB
            SettingsActivity["SettingsActivity"]:::mobile
        end

        subgraph "DI (Dagger)"
            direction TB
            AppComponent["AppComponent"]:::mobile
            AppModule["AppModule"]:::mobile
            SettingsModule["SettingsModule"]:::mobile
            StorageModule["StorageModule"]:::mobile
        end

        subgraph "Fetch Engine"
            direction TB
            BackgroundAlarmListener["BackgroundAlarmListener"]:::mobile
            LatestPostsRetriever["LatestPostsRetriever"]:::mobile
            RetrieveService["RetrieveService"]:::mobile
        end

        subgraph "Networking"
            direction TB
            RedditAuthenticationService["RedditAuthenticationService"]:::mobile
            RedditService["RedditService"]:::mobile
            TokenRefreshInterceptor["TokenRefreshInterceptor"]:::mobile
        end

        subgraph "Converters"
            direction TB
            DelegatingConverter["DelegatingConverter"]:::mobile
            PostConverter["PostConverter"]:::mobile
            CommentsConverter["CommentsConverter"]:::mobile
            ListingResponseConverter["ListingResponseConverter"]:::mobile
            TokenConverter["TokenConverter"]:::mobile
            SubscriptionMarkAsReadConverters["SubscriptionConverter & MarkAsReadConverter"]:::mobile
        end

        subgraph "Storage (SharedPreferences)"
            direction TB
            SharedPreferencesTokenStorage["SharedPreferencesTokenStorage"]:::mobile
            SharedPreferencesUserStorage["SharedPreferencesUserStorage"]:::mobile
            SharedPreferencesUniqueIdentifierStorage["SharedPreferencesUniqueIdentifierStorage"]:::mobile
        end

        WearableListenerService["WearableListenerService"]:::mobile
    end

    %% Wear Module
    subgraph "Wear Module"
        direction TB

        subgraph "UI (Wear)"
            direction TB
            MainActivity["MainActivity"]:::wear
            CommentsActivity["CommentsActivity"]:::wear
            ViewImageActivity["ViewImageActivity"]:::wear
            PanView["PanView"]:::wear
            CommentFragmentsAdapters["Comment Fragments & Adapters"]:::wear
        end

        NotificationListenerService["NotificationListenerService"]:::wear
    end

    %% Shared Library
    subgraph "Shared Library"
        direction TB
        PostModel["Post"]:::shared
        CommentModel["Comment"]:::shared
        Constants["Constants"]:::shared
        Drawables["Drawables"]:::shared
    end

    %% External Services
    subgraph "External Services"
        direction TB
        RedditAPI["Reddit REST API"]:::external
        PocketAPI["Pocket API"]:::external
    end

    %% Data Flows and Relationships
    SettingsActivity -->|"writes settings via Dagger"| SettingsModule
    SettingsModule --> SharedPreferencesUserStorage
    SettingsModule --> SharedPreferencesUniqueIdentifierStorage

    BackgroundAlarmListener -->|"1. triggers"| LatestPostsRetriever
    LatestPostsRetriever -->|"2. uses"| RetrieveService
    RetrieveService -->|"calls"| RedditService
    RetrieveService -->|"auth via"| RedditAuthenticationService
    RedditAuthenticationService -->|"intercepts via"| TokenRefreshInterceptor
    RedditService -->|"intercepts via"| TokenRefreshInterceptor

    RetrieveService -->|"3. JSON→models"| DelegatingConverter
    DelegatingConverter --> PostConverter
    DelegatingConverter --> CommentsConverter
    DelegatingConverter --> ListingResponseConverter
    DelegatingConverter --> TokenConverter
    DelegatingConverter --> SubscriptionMarkAsReadConverters

    PostConverter --> PostModel
    CommentsConverter --> CommentModel

    LatestPostsRetriever -->|"4. sends DataItems"| WearableListenerService
    WearableListenerService -->|"DataApi"| NotificationListenerService

    NotificationListenerService -->|"displays notifications to"| MainActivity
    NotificationListenerService -->|"displays notifications to"| CommentsActivity
    NotificationListenerService -->|"displays notifications to"| ViewImageActivity

    MainActivity --> CommentFragmentsAdapters
    CommentsActivity --> CommentFragmentsAdapters

    %% External API calls
    RedditAuthenticationService -->|"HTTPS/REST"| RedditAPI
    RedditService -->|"HTTPS/REST"| RedditAPI
    MainActivity -->|"Save to Pocket"| PocketAPI

    %% DI Graph
    AppComponent --> AppModule
    AppComponent --> SettingsModule
    AppComponent --> StorageModule

    AppModule --> SharedPreferencesTokenStorage
    AppModule --> TokenRefreshInterceptor

    %% Usage of Shared Library
    SettingsActivity --> Constants
    MainActivity --> PostModel
    CommentsActivity --> CommentModel

    %% Click Events
    click SettingsActivity "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/settings/SettingsActivity.java"
    click AppComponent "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/AppComponent.java"
    click AppModule "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/AppModule.java"
    click SettingsModule "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/settings/SettingsModule.java"
    click StorageModule "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/storage/StorageModule.java"
    click BackgroundAlarmListener "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/BackgroundAlarmListener.java"
    click LatestPostsRetriever "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/LatestPostsRetriever.java"
    click RetrieveService "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/RetrieveService.java"
    click RedditAuthenticationService "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/RedditAuthenticationService.java"
    click RedditService "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/RedditService.java"
    click TokenRefreshInterceptor "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/TokenRefreshInterceptor.java"
    click DelegatingConverter "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/DelegatingConverter.java"
    click PostConverter "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/PostConverter.java"
    click CommentsConverter "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/CommentsConverter.java"
    click ListingResponseConverter "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/ListingResponseConverter.java"
    click TokenConverter "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/TokenConverter.java"
    click SharedPreferencesTokenStorage "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/storage/SharedPreferencesTokenStorage.java"
    click SharedPreferencesUserStorage "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/storage/SharedPreferencesUserStorage.java"
    click SharedPreferencesUniqueIdentifierStorage "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/storage/SharedPreferencesUniqueIdentifierStorage.java"
    click WearableListenerService "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/mobile/src/main/java/com/emmaguy/todayilearned/refresh/WearListenerService.java"
    click MainActivity "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/wear/src/main/java/com/emmaguy/todayilearned/MainActivity.java"
    click CommentsActivity "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/wear/src/main/java/com/emmaguy/todayilearned/comments/CommentsActivity.java"
    click ViewImageActivity "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/wear/src/main/java/com/emmaguy/todayilearned/ViewImageActivity.java"
    click PanView "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/wear/src/main/java/com/emmaguy/todayilearned/PanView.java"
    click NotificationListenerService "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/wear/src/main/java/com/emmaguy/todayilearned/NotificationListenerService.java"
    click PostModel "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/sharedlib/src/main/java/com/emmaguy/todayilearned/sharedlib/Post.java"
    click CommentModel "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/sharedlib/src/main/java/com/emmaguy/todayilearned/sharedlib/Comment.java"
    click Constants "https://github.com/emmaguy/wear-notify-for-reddit/blob/master/sharedlib/src/main/java/com/emmaguy/todayilearned/sharedlib/Constants.java"
    click Drawables "https://github.com/emmaguy/wear-notify-for-reddit/tree/master/sharedlib/src/main/res/drawable-anydpi/"

    %% Styles
    classDef mobile fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef wear fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef shared fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
