Summary
This module acts as the “brain” of the data layer. It takes raw, messy signals from the phone (like screen touches, app opens, and unlock events) and transforms them into human-readable statistics. It calculates how long you spend in apps, how far you scroll, and whether your phone usage is intentional or compulsive. It also connects to a remote server to categorize apps (e.g., identifying if an app is “Social” or “Productivity”).Data Flow
Processing Pipeline
This diagram shows how raw phone events are turned into daily insights.Input Collection
The processor gathers all raw events (screen on/off, app resumes, scrolls) and notifications for a specific date.
Session Calculation
Specialized calculators break the data into “sessions.” For example, it determines if a phone unlock was a quick “glance” or a long “intentional” session.
Usage Aggregation
The system calculates total screen time and “active time” (time spent actually interacting with the screen) for each app.
Remote Categorization
This diagram shows how the app determines what category an app belongs to.Processors & Logic
This module contains the core logic for interpreting user behavior.Daily Data Processor
Role: The conductor. It coordinates all other calculators to process a full day of data. Key Responsibilities:- Filters out system events and hidden apps.
- Prevents “future-crediting” (ensuring usage isn’t calculated for time that hasn’t happened yet).
- Bundles all statistics into a single
DailyProcessingResult.
Unlock Session Calculator
Role: Analyzes how and why the user unlocks their phone. Logic:| Concept | Definition |
|---|---|
| Glance | A session shorter than the minimum threshold (e.g., checking the time). |
| Intentional | A session where the user stays on the phone for a significant duration. |
| Compulsive Check | Unlocking, opening an app, closing it, and unlocking again rapidly. |
| Ghost Session | A data anomaly where a session appears to start without the previous one ending (automatically fixed). |
Scroll Session Calculator
Role: Measures how far the user scrolls in pixels or micrometers. Logic:- Priority: Prefers “Measured” data (precise hardware reports) over “Inferred” data (estimates based on gestures).
- Unit Handling: Converts legacy pixel data and modern micrometer data into a unified metric.
- Merging: Combines small, rapid scroll events into a single continuous “scroll session.”
App Usage Calculator
Role: Calculates Screen Time and Active Time. Active Time Strategy: Unlike standard Screen Time (which just measures how long an app is open), Active Time measures engagement. It assigns a “window of attention” after every touch or scroll. The length of this window depends on the app category:| App Category | Attention Window | Reasoning |
|---|---|---|
| Passive (Video, Books) | Long (~30s) | You touch once, then read/watch for a while. |
| Social / Games | Medium (~5s) | Requires frequent interaction. |
| Utility (Tools, Weather) | Short (~2s) | Get in, check info, get out. |
Insight Generator
Role: Finds interesting patterns in the data. Generated Insights:- Morning Ramp Time: How long between your first unlock and your first meaningful usage.
- Busiest Hour: The hour of the day with the most unlocks.
- Night Owl: Identifies apps used late at night.
- Notification Response: How quickly you unlock the phone after receiving a notification.
Remote Data Sources
The app connects to a remote API to enrich local data.- Category API
Endpoint:
POST v1/getBatchPurpose: To fetch category labels (e.g., “Social”, “Productivity”) for a list of installed apps.Data Flow:- App sends a list of package names (e.g.,
com.instagram.android). - Server returns known categories.
- App caches these categories locally to avoid repeated calls.
x-api-key) for authentication.Data Models
Daily Processing Result
This is the final output object stored or displayed by the UI.| Field | Description |
|---|---|
unlockSessions | List of every time the phone was unlocked. |
scrollSessions | List of scrolling activity. |
usageRecords | Time spent in each specific app. |
deviceSummary | High-level totals (Total time, total unlocks). |
insights | Behavioral observations (e.g., “You are a night owl today”). |
Caching & Offline Strategy
| Strategy | Description |
|---|---|
| Batch Processing | Data is processed in large chunks (usually daily) rather than real-time to save battery. |
| Synthetic Events | If a day ends while an app is still open, the processor creates a “Synthetic” event to close the session cleanly for that day’s records. |
| Local-First Categories | The app only requests categories from the API for new apps that haven’t been seen before. |