# quantumbadger/redreader architecture

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

- Interactive diagram: https://gitdiagram.com/quantumbadger/redreader
- Repository: https://github.com/quantumbadger/redreader

## Overview

##### Project type and purpose
- This is a native Android client app (“RedReader”) for browsing Reddit.
- It’s a mobile‐only application that interfaces with Reddit’s REST API, provides local caching, image/video viewing, multiple accounts, and supports features like swipe actions and themes.

##### File structure
- Top‐level build files (build.gradle.kts, gradle/, fastlane/) indicate a Gradle‐based Android project with CI/CD and release metadata.
- `src/main/java/org/quantumbadger/redreader` contains the main app code, organized into feature packages (activities, fragments, adapters, cache, common, http, image, reddit, settings, views).
- `libs/redreader-common` and `libs/redreader-datamodel` are shared library modules encapsulating cross‐cutting utilities (time, collections) and data definitions.
- Resources (`src/main/res/`) include layouts, drawables, themes, localized strings.
- Tests under `src/androidTest` and `src/test` cover UI and unit tests.
- Receivers (`receivers/`), `BootReceiver` and schedulers indicate background jobs.
- HTTP implementations under `http/` and `http/okhttp/` show pluggable backends.
- Compose UI code under `compose/` for Jetpack Compose integration.

##### README for additional insights
- Confirms features: caching, multiple accounts, image/video player, swipe actions, themes.
- Mentions open-source nature, build via Gradle, Android API 21+ support.

##### Main components
a. Presentation Layer
- Android Activities & Fragments
- Jetpack Compose components
- Custom Views (e.g., GIFView, ExoPlayerWrapperView)
b. Domain / Controller Layer
- ListingControllers (PostListingController, CommentListingController)
- Adapters & Managers (RedditListingManager, CacheManager, RedditAccountManager)
- FeatureFlagHandler, ChangelogManager
c. Data Layer
- HTTPBackend / OKHTTPBackend (network abstraction)
- JSON parsers (`jsonwrap/`, `reddit/kthings/`)
- Cache DB & ContentProvider (`cache/CacheContentProvider`, `io/RawObjectDB`)
- Download strategies (Cache download, prioritisation)
d. External Services
- Reddit REST API (RedditAPI, RedditOAuth)
- Image/video providers (ImgurAPI, GfycatAPI, DeviantArtAPI, RedditGalleryAPI)
e. Android Platform
- BroadcastReceivers & Alarms (BootReceiver, NewMessageChecker, RegularCachePruner)
- System services (Connectivity, Storage, SharedPreferences)

##### Relationships and interactions
- UI components initiate requests (e.g., user scrolls, swipes, taps).
- Controllers / Managers decide data source:
- If cached and within policy → CacheManager retrieves from local DB
- Otherwise → HTTPBackend issues network request via OKHTTP → remote API
- JSON responses parsed into datamodel objects → passed back to controllers → view updated.
- Background Receivers schedule periodic cache pruning and message checks.
- Shared libraries (`redreader-common`, `redreader-datamodel`) provide utility functions and type definitions.

##### Architectural patterns & design principles
- Layered architecture (Presentation → Domain → Data)
- Strategy pattern for download strategies
- Factory pattern for JSON/value object creation
- Observer/listener pattern (e.g., RedditAccountChangeListener, CacheRequestCallbacks)
- Separation of concerns: UI, networking, caching, parsing each in its own package
- Use of shared modules to avoid code duplication

##### Technologies, frameworks, libraries
- Android SDK (Activities, Fragments, Services, BroadcastReceivers)
- Gradle Kotlin DSL for build configuration
- Jetpack Compose (in `compose/`)
- OkHttp for HTTP networking
- ExoPlayer for video playback
- JSON handling via custom wrappers
- Local storage via SQLite/ContentProvider and custom RawObjectDB

##### Diagramming recommendations
- UI → Controllers → Data Layer → External Services
- Receivers → CacheManager
- Rectangles for code modules

##### Essential elements to capture
- All major packages: activities, fragments, http, cache, reddit, image
- Shared modules (`redreader-common`, `redreader-datamodel`)
- Network request flow and caching strategy
- Background scheduling via BroadcastReceivers
- UI update path from parsed data to view

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        AF["Android Activities & Fragments"]:::presentation
        COMP["Jetpack Compose UI"]:::presentation
        GIFV["GIFView"]:::presentation
        EXOV["ExoPlayerWrapperView"]:::presentation
    end

    %% Domain / Controller Layer
    subgraph "Domain / Controller Layer"
        direction TB
        PLC["PostListingController"]:::domain
        CLC["CommentListingController"]:::domain
        RLM["RedditListingManager"]:::domain
        PLM["PostListingManager"]:::domain
        FCM["FilteredCommentListingManager"]:::domain
        RAM["RedditAccountManager"]:::domain
        CMGR["CacheManager"]:::domain
        FFH["FeatureFlagHandler"]:::domain
        CHM["ChangelogManager"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        HTTPB["HTTPBackend"]:::data
        OKHTTP["OKHTTPBackend"]:::data
        JSONP["JSON Parsers"]:::data
        DBP["CacheContentProvider"]:::data
        DBC["CacheDbManager"]:::data
        RODB["RawObjectDB"]:::data
        DS["Download Strategies"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        REDAPI["Reddit REST API"]:::external
        REDOAUTH["RedditOAuth"]:::external
        IMGUR["ImgurAPI"]:::external
        GFYCAT["GfycatAPI"]:::external
        DEVART["DeviantArtAPI"]:::external
        RGL["RedditGalleryAPI"]:::external
        RVAPI["RedditVideosAPI"]:::external
    end

    %% Android Platform
    subgraph "Android Platform"
        direction TB
        BOOTR["BootReceiver"]:::platform
        NMC["NewMessageChecker"]:::platform
        RCP["RegularCachePruner"]:::platform
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        COMMON["redreader-common"]:::shared
        DATAM["redreader-datamodel"]:::shared
    end

    %% Relationships
    AF -->|uses| PLC
    COMP -->|uses| PLC
    PLC -->|delegates| RLM
    CLC -->|delegates| FCM
    RLM -->|requests| CMGR
    CMGR -->|stores/queries| DBP
    DBP -->|manages| RODB
    CMGR -->|uses| DS
    RLM -->|fetch| HTTPB
    HTTPB -->|impl| OKHTTP
    HTTPB -->|calls| REDAPI
    HTTPB -->|auth| REDOAUTH
    HTTPB -->|calls| IMGUR
    HTTPB -->|calls| GFYCAT
    HTTPB -->|calls| DEVART
    HTTPB -->|calls| RGL
    HTTPB -->|calls| RVAPI
    BOOTR -->|schedules| CMGR
    NMC -->|checks| REDAPI
    RCP -->|prunes| DBP

    %% Shared
    COMMON -->|utilities| PLC
    COMMON -->|utilities| CMGR
    DATAM -->|models| JSONP
    DATAM -->|models| PLC

    %% Click Events
    click AF "https://github.com/quantumbadger/redreader/tree/master/src/main/java/org/quantumbadger/redreader/activities"
    click AF "https://github.com/quantumbadger/redreader/tree/master/src/main/java/org/quantumbadger/redreader/fragments"
    click COMP "https://github.com/quantumbadger/redreader/tree/master/src/main/java/org/quantumbadger/redreader/compose"
    click GIFV "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/views/GIFView.java"
    click EXOV "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/views/video/ExoPlayerWrapperView.java"
    click PLC "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/listingcontrollers/PostListingController.java"
    click CLC "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/listingcontrollers/CommentListingController.java"
    click RLM "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/adapters/RedditListingManager.java"
    click PLM "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/adapters/PostListingManager.java"
    click FCM "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/adapters/FilteredCommentListingManager.java"
    click RAM "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/account/RedditAccountManager.java"
    click CMGR "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/cache/CacheManager.java"
    click FFH "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/common/FeatureFlagHandler.java"
    click CHM "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/common/ChangelogManager.java"
    click HTTPB "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/http/HTTPBackend.kt"
    click OKHTTP "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/http/okhttp/OKHTTPBackend.kt"
    click JSONP "https://github.com/quantumbadger/redreader/tree/master/src/main/java/org/quantumbadger/redreader/jsonwrap"
    click JSONP "https://github.com/quantumbadger/redreader/tree/master/src/main/java/org/quantumbadger/redreader/reddit/kthings"
    click DBP "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/cache/CacheContentProvider.java"
    click DBC "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/cache/CacheDbManager.java"
    click RODB "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/io/RawObjectDB.java"
    click DS "https://github.com/quantumbadger/redreader/tree/master/src/main/java/org/quantumbadger/redreader/cache/downloadstrategy"
    click REDAPI "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/reddit/RedditAPI.java"
    click REDOAUTH "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/reddit/api/RedditOAuth.kt"
    click IMGUR "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/image/ImgurAPI.java"
    click GFYCAT "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/image/GfycatAPI.java"
    click DEVART "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/image/DeviantArtAPI.java"
    click RGL "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/image/RedditGalleryAPI.kt"
    click RVAPI "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/image/RedditVideosAPI.kt"
    click BOOTR "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/receivers/BootReceiver.java"
    click NMC "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/receivers/NewMessageChecker.java"
    click RCP "https://github.com/quantumbadger/redreader/blob/master/src/main/java/org/quantumbadger/redreader/receivers/RegularCachePruner.java"
    click COMMON "https://github.com/quantumbadger/redreader/tree/master/libs/redreader-common/src/main/java/org/quantumbadger/redreader/common"
    click DATAM "https://github.com/quantumbadger/redreader/tree/master/libs/redreader-datamodel"

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef domain fill:#E2F0CB,stroke:#6a8e23,stroke-width:1px
    classDef data fill:#FFE4B5,stroke:#d2691e,stroke-width:1px
    classDef external fill:#F2F2F2,stroke:#666666,stroke-width:1px
    classDef platform fill:#E6E6FA,stroke:#9370db,stroke-width:1px
    classDef shared fill:#FFFACD,stroke:#DAA520,stroke-width:1px
```
