# kingstinct/react-native-device-activity architecture

> Architecture diagram of the GitHub repository kingstinct/react-native-device-activity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kingstinct/react-native-device-activity
- Repository: https://github.com/kingstinct/react-native-device-activity

## Overview

##### Project type and purpose
- This is a monorepo containing:
– A React Native “example” app (under apps/example) for demonstration and manual testing.
– An open-source React Native module (packages/react-native-device-activity) that exposes Apple’s Screen Time, Device Activity, and Shield APIs to JS.
– An Expo Config Plugin (in packages/.../config-plugin) that injects native iOS targets into the host app at build/prebuild time.
- Purpose: Provide a JS/TS interface plus an Expo plugin to configure and bundle iOS app extensions that implement family-control features on iOS 15+.

##### File structure
- Top-level monorepo with:
– apps/ (the example consumer app, containing React Native UI, Android and iOS projects, Swift UI views, native extensions under ios/targets).
– packages/react-native-device-activity/ (the library):
- src/ – JS/TS wrappers and types for the NativeModule bridge.
- ios/ – Swift implementation of the NativeModule plus view factories.
- config-plugin/ – Node scripts that hook into Expo prebuild to copy & configure three iOS app extensions: ActivityMonitorExtension, ShieldAction, ShieldConfiguration.
- expo-module.config.json – declares the module to the Expo plugin system.
– scripts/ – workspace maintenance.
- Build orchestration files (.github/workflows, husky, metro.config.js, tsconfig.json, babel.config.js, etc.)

##### README for architectural clues
- Describes:
– JS API for requesting authorization, starting/stopping monitors, listening to events, blocking selections, updating shield UI.
– Under-the-hood: uses UserDefaults for persisting configurations and history; runs background processes in iOS app extensions to respond to OS events; requires custom Dev Client.

##### Main components
A. Example App (apps/example):
– React Native UI (TypeScript, React components, SwiftUI wrappers).
– JS code invoking ReactNativeDeviceActivity.* APIs.
B. JS Bridge Layer (packages/.../src):
– Exposed methods: requestAuthorization, startMonitoring, blockSelection, updateShield, DeviceActivitySelectionView, event listeners.
– Internally calls React Native’s NativeModules to route calls to Swift.
C. Expo Config Plugin (packages/.../config-plugin):
– Build/prebuild plugin hooks.
– Reads expo config (appleTeamId, appGroup), invokes withCopyTargetFolder, withEntitlements, withInfoPlist, withXcodeSettings.
– Outputs three iOS extensions into the host app’s targets folder.
D. iOS Native Module (packages/.../ios):
– Swift implementation of ReactNativeDeviceActivityModule.
– Implements methods that call Apple’s DeviceActivityMonitor, Shielding APIs, persists to UserDefaults.
– Exposes DeviceActivitySelectionView using SwiftUI bridged into React Native.
E. iOS App Extension Targets (both in packages and copied into apps/example/targets):
– ActivityMonitorExtension – background monitor handling.
– ShieldAction – shield UI renderer and action handler.
– ShieldConfiguration – provides configuration/PrivacyInfo for Shield UI.
– These run in separate processes invoked by iOS when an event fires.
F. Apple’s Screen Time / Device Activity / Family Controls OS APIs:
– The system services that the Swift code calls into.
G. Data persistence:
– UserDefaults store for familyActivitySelectionId mappings, triggers, event history, shieldIds.

##### Relationships & interactions
- Build Time (prebuild/expo prebuild):
1. User runs expo prebuild / eas build.
2. Expo config plugin activates:
– Reads app.json, copies Swift target folders from node_modules into apps/xxx/targets.
– Modifies Info.plist, entitlements, Xcode project settings.
- Runtime (app launch & usage):
1. JS UI calls ReactNativeDeviceActivity.requestAuthorization() → JS Bridge → Swift NativeModule.
2. Swift module calls ScreenTime API → OS permission dialog → callback → JS.
3. JS invokes startMonitoring → Swift schedules monitors in ActivityMonitorExtension.
4. OS triggers ActivityMonitorExtension when time interval starts/ends or threshold reached → Swift extension writes to UserDefaults, may trigger ShieldAction or send events.
5. If Shield UI is needed, OS launches ShieldActionExtension → renders custom UI.
6. JS can listen to events via onDeviceActivityMonitorEvent (active app) or query history using getEvents().

##### Architectural patterns and design principles
- Monorepo with clear separation: example app vs library package.
- React Native NativeModule bridging pattern.
- Expo Config Plugin pattern for build-time configuration.
- iOS App Extension pattern for background processes.
- Modular TS code with clear types and test coverage.
- Persistence via UserDefaults as a lightweight local store.

##### Detail without overthinking
- How the config-plugin ties node_modules → Xcode targets.
- Persistence in UserDefaults as a shared storage block.
- Don’t omit the DeviceActivitySelectionView (SwiftUI + JS wrapper).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build Time
    subgraph "Build Time" 
        direction TB
        ExpoCLI["Expo CLI"]:::build
        ConfigPlugin["Expo Config Plugin"]:::build
        NodeModules["react-native-device-activity (node_modules)"]:::build
        XcodeProject["Xcode Project (apps/example)"]:::build
        TargetsFolder["Copied iOS App Extensions"]:::build
    end

    ExpoCLI -->|"run expo prebuild / eas build"| ConfigPlugin
    ConfigPlugin -->|"reads expo config & copies targets"| TargetsFolder
    ConfigPlugin -->|"modifies Info.plist, entitlements, Xcode settings"| XcodeProject
    ConfigPlugin -->|"reads templates from"| NodeModules
    NodeModules --> TargetsFolder

    %% Runtime
    subgraph "Runtime" 
        direction TB
        subgraph "Main App Process" 
            direction TB
            ReactUI["React Native UI"]:::js
            JSBridge["JS Bridge Layer"]:::js
            NativeModule["ReactNativeDeviceActivityModule (Swift)"]:::native
            DeviceActivitySelectionView["DeviceActivitySelectionView"]:::js
            UserDefaults["UserDefaults Store"]:::native
        end

        subgraph "iOS Extension Processes" 
            direction TB
            MonitorExt["ActivityMonitorExtension"]:::native
            ShieldActionExt["ShieldActionExtension"]:::native
            ShieldConfigExt["ShieldConfigurationExtension"]:::native
        end

        subgraph "iOS System Services" 
            direction TB
            ScreenTimeAPI["ScreenTime/DeviceActivity OS APIs"]:::os
        end
    end

    %% Runtime flows
    ReactUI -->|"calls requestAuthorization(), startMonitoring(), updateShield()"| JSBridge
    JSBridge -->|"NativeModules.invoke()"| NativeModule
    NativeModule -->|"calls ScreenTime APIs"| ScreenTimeAPI
    JSBridge -->|"renders view"| DeviceActivitySelectionView
    JSBridge -->|"persists configs/events"| UserDefaults

    NativeModule -->|"schedule monitors"| MonitorExt
    ScreenTimeAPI -->|"invokes when threshold reached"| MonitorExt
    MonitorExt -->|"writes events to UserDefaults & triggers shield"| UserDefaults
    MonitorExt -->|"triggers ShieldAction"| ShieldActionExt
    ShieldActionExt -->|"renders UI & user actions"| UserDefaults
    ShieldActionExt -->|"callback events"| ReactUI
    ScreenTimeAPI -->|"invokes config info"| ShieldConfigExt
    ShieldConfigExt -->|"provides config to UI"| ShieldActionExt

    %% Click Events
    click ReactUI "https://github.com/kingstinct/react-native-device-activity/blob/main/apps/example/App.tsx"
    click ReactUI "https://github.com/kingstinct/react-native-device-activity/tree/main/apps/example"
    click JSBridge "https://github.com/kingstinct/react-native-device-activity/tree/main/packages/react-native-device-activity/src"
    click DeviceActivitySelectionView "https://github.com/kingstinct/react-native-device-activity/blob/main/packages/react-native-device-activity/src/DeviceActivitySelectionView.tsx"
    click ConfigPlugin "https://github.com/kingstinct/react-native-device-activity/blob/main/packages/react-native-device-activity/app.plugin.js"
    click ConfigPlugin "https://github.com/kingstinct/react-native-device-activity/blob/main/packages/react-native-device-activity/config-plugin/withCopyTargetFolder.js"
    click ConfigPlugin "https://github.com/kingstinct/react-native-device-activity/blob/main/packages/react-native-device-activity/config-plugin/withEntitlements.js"
    click ConfigPlugin "https://github.com/kingstinct/react-native-device-activity/blob/main/packages/react-native-device-activity/config-plugin/withInfoPlistAppGroup.js"
    click ConfigPlugin "https://github.com/kingstinct/react-native-device-activity/blob/main/packages/react-native-device-activity/config-plugin/withXCodeSettings.js"
    click MonitorExt "https://github.com/kingstinct/react-native-device-activity/blob/main/packages/react-native-device-activity/targets/ActivityMonitorExtension/DeviceActivityMonitorExtension.swift"
    click ShieldActionExt "https://github.com/kingstinct/react-native-device-activity/blob/main/packages/react-native-device-activity/targets/ShieldAction/ShieldActionExtension.swift"
    click ShieldConfigExt "https://github.com/kingstinct/react-native-device-activity/blob/main/packages/react-native-device-activity/targets/ShieldConfiguration/ShieldConfigurationExtension.swift"

    %% Styles
    classDef js fill:#c8f7c5,stroke:#6ca46c,stroke-width:1px
    classDef native fill:#c5dbf7,stroke:#4a78b5,stroke-width:1px
    classDef os fill:#fce5cd,stroke:#e69138,stroke-width:1px
    classDef build fill:#ffffff,stroke:#999999,stroke-dasharray: 5 5,stroke-width:1px
```
