# agencyenterprise/react-native-health architecture

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

- Interactive diagram: https://gitdiagram.com/agencyenterprise/react-native-health
- Repository: https://github.com/agencyenterprise/react-native-health

## Overview

##### Project type and purpose
- This is an open-source React Native library named “react-native-health” that provides a native bridge to Apple’s HealthKit framework on iOS.
- Its purpose is to expose HealthKit’s read/write and observer APIs to JavaScript through the React Native bridge.

##### File structure
- Top-level native module folder: RCTAppleHealthKit/ (Objective-C source and headers, divided by domain: Activity, Body, ClinicalRecords, etc.).
- JavaScript interface: index.js (exports), index.d.ts (TypeScript definitions), src/constants/ (Permissions, Units, Activities, Observers).
- Example app under example/: a typical RN project demonstrating Android placeholders and a working iOS HealthKit integration.
- Docs folder: markdown files for every exposed method and concept.
- Build configs: RNAppleHealthKit.xcodeproj, RNAppleHealthKit.podspec, CocoaPods settings, iOS info.plist instructions.

##### README
- Confirms use of the React Native Bridge to invoke native Objective-C code.
- Details initialization, permission flow, background observers, and method categories (Activity, Body, Clinical, etc.).
- Suggests linking via CocoaPods or manual linking, enabling HealthKit capability in Xcode.

##### Core components
a. JavaScript layer:
- Your app’s JS code calls methods on the react-native-health API (index.js).
- Constants and Types in src/constants help you define read/write permissions and units.
b. React Native Bridge:
- index.js invokes NativeModules.RCTAppleHealthKit through React Native’s built-in bridge mechanism.
c. Native Module (RCTAppleHealthKit):
- The Objective-C classes in RCTAppleHealthKit implement methods grouped by domain (Activity, Body, ClinicalRecords, …).
- They translate JS arguments into HealthKit queries or save operations.
d. Apple HealthKit Framework:
- The native module uses HKHealthStore, HKQuery, HKObserverQuery, and other HealthKit APIs.
e. iOS Host App (Example):
- Contains AppDelegate changes to initialize background observers and configures Info.plist with NSHealth…UsageDescription keys.
- Demonstrates end-to-end flow from JS calls to native invocation to HealthKit data retrieval/storage.
f. External Dependencies:
- CocoaPods for dependency management (podspec).
- Xcode project settings for HealthKit capability.

##### Relationships and interactions
- JS layer → Bridge → Native Module → HealthKit framework → iOS OS.
- Native Module may also register long-running observer queries at startup via AppDelegate → Bridge.
- Responses and data flow from HealthKit back up the chain (native → bridge → JS callback or Promise resolution).

##### Architectural patterns and principles
- Bridge Pattern: React Native Bridge decouples JS from native code.
- Modular Domain Separation: Each category of HealthKit functionality is defined in its own file pair (Methods_*, Queries, TypesAndPermissions).
- Single Responsibility: Constants, API exports, and native implementation are cleanly separated.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% JavaScript Layer
  subgraph "JavaScript Layer"
    direction TB
    JSIndex["index.js"]:::js
    JSTypes["index.d.ts"]:::js
    subgraph "src/constants"
      direction TB
      ConstActivities["Activities.js"]:::js
      ConstObservers["Observers.js"]:::js
      ConstPermissions["Permissions.js"]:::js
      ConstUnits["Units.js"]:::js
      ConstIndex["index.js"]:::js
    end
  end

  %% React Native Bridge
  subgraph "React Native Bridge"
    direction TB
    BridgeH["RCTAppleHealthKit.h"]:::bridge
    BridgeM["RCTAppleHealthKit.m"]:::bridge
  end

  %% Native Module
  subgraph "Native Module"
    direction TB
    MethodsActivity["RCTAppleHealthKit+Methods_Activity.{h,m}"]:::native
    MethodsBody["RCTAppleHealthKit+Methods_Body.{h,m}"]:::native
    MethodsClinical["RCTAppleHealthKit+Methods_ClinicalRecords.{h,m}"]:::native
    MethodsQueries["RCTAppleHealthKit+Queries.{h,m}"]:::native
    MethodsTypes["RCTAppleHealthKit+TypesAndPermissions.{h,m}"]:::native
    MethodsUtils["RCTAppleHealthKit+Utils.{h,m}"]:::native
  end

  %% External Frameworks & Config
  subgraph "External Frameworks & Config"
    direction TB
    Podspec["RNAppleHealthKit.podspec"]:::framework
    XcodeProj["RCTAppleHealthKit.xcodeproj"]:::framework
    HealthKitFW["Apple HealthKit Framework"]:::framework
  end

  %% Documentation
  subgraph "Documentation"
    direction TB
    DocsList["docs/*.md"]:::doc
    Summary["SUMMARY.md"]:::doc
  end

  %% Example App
  subgraph "Example App"
    direction TB
    subgraph "iOS Host App"
      direction TB
      AppDelegateH["AppDelegate.h"]:::example
      AppDelegateM["AppDelegate.m"]:::example
      InfoPlist["Info.plist"]:::example
    end
    subgraph "React Native Example"
      direction TB
      ExampleTSX["App.tsx"]:::example
      ExampleIndex["index.js"]:::example
    end
    subgraph "Android Placeholder"
      direction TB
      MainActivity["MainActivity.java"]:::example
      MainApplication["MainApplication.java"]:::example
    end
  end

  %% iOS OS
  iOSOS["iOS OS / Device"]:::os

  %% Connections
  JSIndex -->|"calls API"| BridgeM
  JSTypes --> BridgeM
  ConstActivities --> JSIndex
  ConstObservers --> JSIndex
  ConstPermissions --> JSIndex
  ConstUnits --> JSIndex
  ConstIndex --> JSIndex

  BridgeM -->|"RCT_EXPORT_METHOD"| MethodsActivity
  BridgeM --> MethodsBody
  BridgeM --> MethodsClinical
  BridgeM --> MethodsQueries
  BridgeM --> MethodsTypes
  BridgeM --> MethodsUtils

  MethodsActivity -->|"HKSampleQuery"| HealthKitFW
  MethodsBody --> HealthKitFW
  MethodsClinical --> HealthKitFW
  MethodsQueries --> HealthKitFW
  MethodsTypes --> HealthKitFW
  MethodsUtils --> HealthKitFW

  HealthKitFW -->|data/events| BridgeM
  BridgeM -->|callback/Promise| JSIndex

  AppDelegateM -->|"initializeBackgroundObservers"| BridgeM
  InfoPlist --> AppDelegateM

  Podspec --> BridgeM
  XcodeProj --> BridgeM

  HealthKitFW --> iOSOS

  %% Click Events
  click JSIndex "https://github.com/agencyenterprise/react-native-health/blob/master/index.js"
  click JSTypes "https://github.com/agencyenterprise/react-native-health/blob/master/index.d.ts"
  click ConstActivities "https://github.com/agencyenterprise/react-native-health/blob/master/src/constants/Activities.js"
  click ConstObservers "https://github.com/agencyenterprise/react-native-health/blob/master/src/constants/Observers.js"
  click ConstPermissions "https://github.com/agencyenterprise/react-native-health/blob/master/src/constants/Permissions.js"
  click ConstUnits "https://github.com/agencyenterprise/react-native-health/blob/master/src/constants/Units.js"
  click ConstIndex "https://github.com/agencyenterprise/react-native-health/blob/master/src/constants/index.js"
  click BridgeH "https://github.com/agencyenterprise/react-native-health/blob/master/RCTAppleHealthKit/RCTAppleHealthKit.h"
  click BridgeM "https://github.com/agencyenterprise/react-native-health/blob/master/RCTAppleHealthKit/RCTAppleHealthKit.m"
  click MethodsActivity "https://github.com/agencyenterprise/react-native-health/blob/master/RCTAppleHealthKit/RCTAppleHealthKit+Methods_Activity.h"
  click MethodsBody "https://github.com/agencyenterprise/react-native-health/blob/master/RCTAppleHealthKit/RCTAppleHealthKit+Methods_Body.h"
  click MethodsClinical "https://github.com/agencyenterprise/react-native-health/blob/master/RCTAppleHealthKit/RCTAppleHealthKit+Methods_ClinicalRecords.h"
  click MethodsQueries "https://github.com/agencyenterprise/react-native-health/blob/master/RCTAppleHealthKit/RCTAppleHealthKit+Queries.h"
  click MethodsTypes "https://github.com/agencyenterprise/react-native-health/blob/master/RCTAppleHealthKit/RCTAppleHealthKit+TypesAndPermissions.h"
  click MethodsUtils "https://github.com/agencyenterprise/react-native-health/blob/master/RCTAppleHealthKit/RCTAppleHealthKit+Utils.h"
  click Podspec "https://github.com/agencyenterprise/react-native-health/blob/master/RNAppleHealthKit.podspec"
  click XcodeProj "https://github.com/agencyenterprise/react-native-health/blob/master/RCTAppleHealthKit.xcodeproj"
  click DocsList "https://github.com/agencyenterprise/react-native-health/tree/master/docs/"
  click Summary "https://github.com/agencyenterprise/react-native-health/blob/master/docs/SUMMARY.md"
  click AppDelegateH "https://github.com/agencyenterprise/react-native-health/blob/master/example/ios/example/AppDelegate.h"
  click AppDelegateM "https://github.com/agencyenterprise/react-native-health/blob/master/example/ios/example/AppDelegate.m"
  click InfoPlist "https://github.com/agencyenterprise/react-native-health/blob/master/example/ios/example/Info.plist"
  click ExampleTSX "https://github.com/agencyenterprise/react-native-health/blob/master/example/App.tsx"
  click ExampleIndex "https://github.com/agencyenterprise/react-native-health/blob/master/example/index.js"
  click MainActivity "https://github.com/agencyenterprise/react-native-health/blob/master/example/android/app/src/main/java/com/example/MainActivity.java"
  click MainApplication "https://github.com/agencyenterprise/react-native-health/blob/master/example/android/app/src/main/java/com/example/MainApplication.java"

  %% Styles
  classDef js fill:#E5F0FF,stroke:#0366D6,color:#0366D6
  classDef bridge fill:#E6FFEA,stroke:#28A745,color:#28A745
  classDef native fill:#E6FFEA,stroke:#28A745,color:#28A745
  classDef framework fill:#FFF4E5,stroke:#D9822B,color:#D9822B
  classDef doc fill:#F0F0F0,stroke:#CCCCCC,color:#333333
  classDef example fill:#FFF5F7,stroke:#A626A4,color:#A626A4
  classDef os fill:#F5F5F5,stroke:#666666,color:#666666
```
