A native, offline-first Android application that captures and stores status bar notifications locally in an SQLite database with an automatic 72-hour rolling retention policy, displayed in an expressive Material You dark theme feed.
- Status Bar Notification Capture: Continuous background interception powered by
NotificationCaptureService(NotificationListenerService). Automatically skips internal self-notifications and system noise. - Real-Time Keyword Search & Application Filtering: Instant keyword search triggered via top-bar magnifier icon, active app filter chips, dynamic match count summaries, and complete per-application filtering via a Material 3 modal bottom sheet.
- Visual Substring Match Highlighting: Real-time visual highlighting of search queries via styled inline substring spans within notification titles and message bodies, with match count badges and summaries provided in the filter controls.
- Reactive Permission States & Summary: Service state is surfaced by
DisabledSetupView(initial onboarding) andAccessRevokedBanner(paused state) when system notification access is revoked or restricted, alongside a captured notification counter and rolling 3-day window summary row inServiceStatusHeader("$capturedCount notifications • Last 3 days"). - 100% Offline Privacy: Zero network permissions declared in
AndroidManifest.xml. Notification content never leaves the device. - 72-Hour Rolling Retention: Automated pruning of expired records executed on every incoming notification and on-demand repository triggers to keep SQLite storage lightweight.
The project follows Clean Architecture principles with unidirectional data flow (UDF) through Kotlin StateFlow and Coroutines:
flowchart TD
subgraph System["Android OS System"]
SBN["StatusBarNotification Event"]
end
subgraph Service["Background Service Layer"]
NCS["NotificationCaptureService (IO Scope)"]
end
subgraph Data["Data Layer (Local Storage)"]
DB[("AppDatabase (Room SQLite)")]
DAO["NotificationDao"]
PREF["UserPreferences (SharedPreferences)"]
REPO["NotificationRepositoryImpl"]
end
subgraph Domain["Domain Layer"]
RECORD["NotificationRecord"]
STATE["ListenerState (Active / Paused / Inactive)"]
APPFILTER["AppFilterItem"]
end
subgraph UI["Presentation Layer (Jetpack Compose)"]
VM["NotificationViewModel"]
UISTATE["NotificationUiState"]
SCREEN["NotificationHistoryScreen"]
SEARCHBAR["SearchTopBar"]
BOTTOMSHEET["AppFilterBottomSheet"]
HEADER["ServiceStatusHeader"]
BANNER["AccessRevokedBanner / DisabledSetupView"]
FEED["LazyColumn & NotificationCard"]
end
SBN -->|onNotificationPosted| NCS
NCS -->|Insert & Purge >72h| DAO
DAO --> DB
DB --> DAO
DAO -->|observeNotifications Flow| REPO
REPO -->|Domain Models| VM
PREF --> VM
VM -->|MutableStateFlow.asStateFlow| UISTATE
UISTATE --> SCREEN
SCREEN --> SEARCHBAR
SCREEN --> BOTTOMSHEET
SCREEN --> HEADER
SCREEN --> BANNER
SCREEN --> FEED
SCREEN -->|TopAppBar overflow menu: clear-all, Snackbar: undo| VM
FEED -->|Card expansion toggles| VM
VM -->|Data mutations| REPO
REPO --> DAO
- Service Layer (
service/):NotificationCaptureService: Extends Android'sNotificationListenerService. Dispatches asynchronous processing to a dedicatedSupervisorJob+Dispatchers.IOcoroutine scope, resolves app labels, inserts entities, and purges records older than 72 hours.
- Data Layer (
data/):AppDatabase: Room SQLite database instance managing local storage.NotificationDao: Reactive Room queries returningFlow<List<NotificationEntity>>, batch operations, and timestamp-based eviction queries.NotificationEntity: Local SQLite schema representation with indexed columns.NotificationRepository&NotificationRepositoryImpl: Repository handling dispatcher switching (Dispatchers.IO), entity-to-domain transformations, batch clears, and atomic restoration.UserPreferences: Persistent storage tracking onboarding and setup completion.
- Domain Layer (
domain/):NotificationRecord: Immutable domain model holding title, content, app name, package name, timestamps, and UI expansion state.ListenerState: Sealed representation of listener status (Active,Paused,Inactive).AppFilterItem: Encapsulates application filter properties, total counts, query match counts, and selection states.
- UI Layer (
ui/):MainActivity: Single-activity entry point hosting edge-to-edge Compose UI.NotificationHistoryScreen: Container composable coordinating top app bar, service status banner, list state, and snackbars.NotificationViewModel: ViewModel orchestrating UI state, permission checks, card expansion toggles, batch deletion, and undo restoration.NotificationUiState: Single immutable state data class consumed by Compose components.- Components:
SearchTopBar: Dedicated pill-shaped search bar with query clear action, back navigation, and filter trigger.AppFilterBottomSheet: Material 3 modal bottom sheet supporting nested app search, radio selection, and dynamic match counts.NotificationCard: Expandable notification list item card.NotificationMetadataSection: Drawer showing raw system metadata and key attributes.ServiceStatusHeader: Displays captured notification counter and rolling 3-day window summary row ("$capturedCount notifications • Last 3 days"). Service state is surfaced by DisabledSetupView (initial onboarding) and AccessRevokedBanner (paused state).AccessRevokedBanner: Warning callout when listener permission has been disabled.DisabledSetupView: Initial onboarding screen when permissions are not yet configured.
| Technology | Specification / Version | Reference |
|---|---|---|
| Language | Kotlin 2.3.20 (JVM Toolchain 17) | build.gradle.kts |
| Min / Target SDK | Min SDK 33 (Android 13 Tiramisu) / Target & Compile SDK 36 | build.gradle.kts |
| UI Framework | Jetpack Compose BOM 2026.03.01 & Material Design 3 |
libs.versions.toml |
| Local Database | AndroidX Room 2.7.2 with Google KSP | libs.versions.toml |
| Asynchrony & State | Kotlinx Coroutines 1.10.2 & StateFlow |
libs.versions.toml |
| Navigation | AndroidX Navigation3 Core 1.0.1 | libs.versions.toml |
| Build Tool | Android Gradle Plugin 9.0.1 / Gradle 9.1.0 | libs.versions.toml |
Android requires explicit user authorization via the Device & app notifications (Special app access) menu to allow third-party applications to inspect status bar events.
- Install and launch the application.
- In the initial
DisabledSetupViewscreen, tap "Open settings". - You will be redirected directly into the system settings page for Recall.
- Toggle "Allow notification access" to ON and confirm the Android system security prompt.
- Return to the app. Returning to the app displays the active feed with the notification summary row in
ServiceStatusHeader("X notifications • Last 3 days").
Note
On sideloaded APKs on Android 13+ (API 33+), Android may mark notification listener permissions as "Restricted settings". If the toggle is greyed out:
- Go to Settings > Apps > Recall.
- Tap the three-dots menu (⋮) in the top right corner.
- Tap "Allow restricted settings" and authenticate with your device PIN or fingerprint.
- Re-open the app and grant notification access.
The application utilizes SettingsNavigationHelper for robust navigation across different Android OEM builds:
- Direct Target (Android 11+ / API 30+): Dispatches
Settings.ACTION_NOTIFICATION_LISTENER_DETAIL_SETTINGSpre-populated withNotificationCaptureServicecomponent name, jumping straight to this app's toggle page. - Graceful Fallback: If the OEM platform fails to resolve the direct detail intent, it falls back seamlessly to
Settings.ACTION_NOTIFICATION_LISTENER_SETTINGS(the global listener list).
Run all commands from the repository root:
# Compile Kotlin code across debug variants
./gradlew compileDebugKotlin
# Run all 45 JVM unit tests covering Repository, Card formatting, Search/Filter ViewModel logic, and ServiceStatusHeader
./gradlew testDebugUnitTest
# Assemble the debug APK (outputs to app/build/outputs/apk/debug/)
./gradlew assembleDebug
# Clean build cache and artifacts
./gradlew clean