# douglasjunior/react-native-applifecycle architecture

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

- Interactive diagram: https://gitdiagram.com/douglasjunior/react-native-applifecycle
- Repository: https://github.com/douglasjunior/react-native-applifecycle

## Overview

##### Project type and purpose
- This is an open-source React Native library (“react-native-applifecycle”) that unifies app lifecycle events across Android and iOS.
- It provides a Java/Kotlin Native Module on Android (leveraging AndroidX Lifecycle) and falls back to React Native’s AppState on iOS, exposing a uniform JS API for “active”, “background”, and “inactive” events.

##### File structure
- Top-level: configuration files (`.eslintrc.js`, `babel.config.js`, `tsconfig.json`), CI/workflows under `.github`, publish scripts under `scripts/`.
- `src/`—TypeScript wrapper modules:
- AndroidLifecycleModule.ts (binds to NativeModule)
- AppLifecycle.ts (JS façade and event emitter)
- useAppLifecycle.ts (React hook)
- index.ts (public exports)
- `android/`—Android project implementing the native module:
- `AppLifecyclePackage.java`, `AppLifecycleModule.java`
- Gradle files, AndroidManifest
- `Sample/`—a demo React Native app to illustrate usage (contains both Android & iOS platform code + a TSX front-end).
- `jest/`—mock for unit tests.

##### Key insights from README
- Purpose: resolve mismatches in AppState behavior across platforms.
- API: `AppLifecycle.addEventListener('change', ...)` and `useAppLifecycle()`.
- Android uses Jetpack Lifecycle, iOS falls back to AppState.
- There’s a Jest mock for testing.

##### Main components
a. Consumer App (e.g., Sample)
b. Library JS Layer
- AppLifecycle API (EventEmitter façade)
- React Hook (`useAppLifecycle`)
c. Android Native Module
- AppLifecycleModule (bridged to JS)
- AppLifecyclePackage (registers the module)
- OS Lifecycle Observer (AndroidX)
d. iOS Fallback
- React Native Core AppState module
e. Build & Publish Pipeline
- TypeScript compilation (tsc)
- Babel/Metro for bundling
- npm publish script (`scripts/publish.js`)
- CI workflows (`.github/workflows`)
f. Tests
- Jest config + mocks

##### Relationships & interactions
- On Android: OS lifecycle events → AndroidX Lifecycle Observer → NativeModule (AppLifecycleModule) → JS via NativeEventEmitter → AppLifecycle.addEventListener / hook → Consumer UI
- On iOS: OS lifecycle events → RN Core AppState → JS AppState API → fallback path in AppLifecycle façade → Consumer UI
- Build scripts & CI run on push/publish → transpile TS → package for npm

##### Architectural patterns & design principles
- Platform-specific strategy pattern (Android vs. iOS implementation)
- Bridge pattern (NativeModule ↔ JS)
- Facade pattern (AppLifecycle façade over two platform implementations)
- Separation of concerns: Core logic in JS, platform logic in native code, sample app isolated.
- Extensibility: new events can be added in native modules and surfaced via the façade.

##### Detailed element checklist
- Consumer App (Sample or generic RN App)
- AppLifecycle façade (AppLifecycle.ts + Hook)
- Android Native Module (Package + Module)
- iOS Fallback (AppState)
- Build & Publish (scripts, Babel, npm)
- Tests (Jest + mocks)
- External dependencies (AndroidX Lifecycle, React Native Core)

## Diagram (Mermaid)

```mermaid
flowchart TB
    ConsumerApp["Consumer App\n(Sample/)"]:::consumer

    subgraph "Library JS Layer"
        Index["Public Exports\n(src/index.ts)"]:::js
        Façade["AppLifecycle Facade\n(src/AppLifecycle.ts)"]:::js
        Binding["AndroidLifecycleModule Binding\n(src/AndroidLifecycleModule.ts)"]:::js
        Hook["useAppLifecycle Hook\n(src/useAppLifecycle.ts)"]:::js
    end

    subgraph "Android Native Module"
        OSAndroid["Android OS Lifecycle Events"]:::android
        Observer["AndroidX Lifecycle Observer"]:::android
        Module["AppLifecycleModule\n(android/src/main/java/com/github/douglasjunior/reactNativeAppLifecycle/modules/AppLifecycleModule.java)"]:::android
        Package["AppLifecyclePackage\n(android/src/main/java/com/github/douglasjunior/reactNativeAppLifecycle/AppLifecyclePackage.java)"]:::android
    end

    subgraph "iOS Fallback"
        OSiOS["iOS OS Lifecycle Events"]:::ios
        AppState["RN Core AppState\n(src/AppLifecycle.ts)"]:::ios
    end

    subgraph "Build & Publish Pipeline"
        TS["TypeScript Config\n(tsconfig.json)"]:::tooling
        Babel["Babel Config\n(babel.config.js)"]:::tooling
        Publish["npm Publish Script\n(scripts/publish.js)"]:::tooling
        CI["CI Workflows\n(.github/workflows/)"]:::tooling
        NPM["npm Registry"]:::tooling
    end

    subgraph "Tests"
        Mock["Jest Mock\n(jest/AppLifecycleMock.js)"]:::tooling
        SampleTests["Sample App Tests\n(Sample/__tests__)"]:::tooling
    end

    OSAndroid -->|"lifecycle callbacks"| Observer
    Observer -->|"native events"| Module
    Module -->|"bridge via NativeEventEmitter"| Binding
    Binding -->|"emits events"| Façade

    OSiOS -->|"AppState events"| AppState
    AppState -->|"fallback path"| Façade

    Index -->|"exports API"| Façade
    Façade -->|"provides hook"| Hook
    Hook -->|"used by"| ConsumerApp
    Façade -->|"used by"| ConsumerApp

    CI -->|"runs build & tests"| TS
    TS -->|"transpile"| Babel
    Babel -->|"bundle"| Publish
    Publish -->|"publishes"| NPM
    NPM -->|"install package"| ConsumerApp

    CI -->|"runs tests"| SampleTests
    SampleTests -->|"uses mock"| Mock

    classDef js fill:#e0f7fa,stroke:#006064
    classDef android fill:#e8f5e9,stroke:#2e7d32
    classDef ios fill:#fff3e0,stroke:#ef6c00
    classDef tooling fill:#eceff1,stroke:#607d8b
    classDef consumer fill:#e3f2fd,stroke:#1565c0

    click ConsumerApp "https://github.com/douglasjunior/react-native-applifecycle/tree/main/Sample/"
    click Binding "https://github.com/douglasjunior/react-native-applifecycle/blob/main/src/AndroidLifecycleModule.ts"
    click Façade "https://github.com/douglasjunior/react-native-applifecycle/blob/main/src/AppLifecycle.ts"
    click Hook "https://github.com/douglasjunior/react-native-applifecycle/blob/main/src/useAppLifecycle.ts"
    click Index "https://github.com/douglasjunior/react-native-applifecycle/blob/main/src/index.ts"
    click Package "https://github.com/douglasjunior/react-native-applifecycle/blob/main/android/src/main/java/com/github/douglasjunior/reactNativeAppLifecycle/AppLifecyclePackage.java"
    click Module "https://github.com/douglasjunior/react-native-applifecycle/blob/main/android/src/main/java/com/github/douglasjunior/reactNativeAppLifecycle/modules/AppLifecycleModule.java"
    click TS "https://github.com/douglasjunior/react-native-applifecycle/blob/main/tsconfig.json"
    click Babel "https://github.com/douglasjunior/react-native-applifecycle/blob/main/babel.config.js"
    click Publish "https://github.com/douglasjunior/react-native-applifecycle/blob/main/scripts/publish.js"
    click CI "https://github.com/douglasjunior/react-native-applifecycle/tree/main/.github/workflows/"
    click Mock "https://github.com/douglasjunior/react-native-applifecycle/blob/main/jest/AppLifecycleMock.js"
    click SampleTests "https://github.com/douglasjunior/react-native-applifecycle/tree/main/Sample/__tests__/"
```
