# hyochan/expo-iap architecture

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

- Interactive diagram: https://gitdiagram.com/hyochan/expo-iap
- Repository: https://github.com/hyochan/expo-iap

## Overview

##### Project type and purpose
- This is an open-source Expo “in-app purchases” (IAP) module conforming to the Open IAP specification.
- It’s a library (not a standalone app) that exposes a JavaScript API, bridges into native Android/iOS modules, and includes an Expo plugin for project configuration.

##### Main components
a. Host Application (Expo/React-Native)
b. JS Layer (expo-iap package)
- src/index.ts, useIAP.ts, helpers, utils
c. Native Modules
- Android: ExpoIapModule.kt, PlayUtils.kt, Types.kt
- iOS: ExpoIapModule.swift, Podspec
d. Expo Module Infrastructure
- expo-module.config.json, expo-modules-core at runtime
e. Expo Plugin
- plugin/src/withIAP.ts, withLocalOpenIAP.ts – configures Android build properties
f. External Services
- Google Play Billing (Android)
- Apple App Store StoreKit (iOS)
- Open IAP specification endpoint (for standardization)
g. Example App & Test Harness
- example/ directory: demonstrates usage, test files, metro/jest configs
h. Documentation Site
- docs/ directory powered by Docusaurus

##### Relationships & data flows
- Host App → JS Layer: imports `expo-iap` API calls (e.g., getProducts, requestPurchase)
- JS Layer → Native Module: through the Expo Modules bridge
- Native Module ↔ External Service:
- Android native module ↔ Google Play Billing Library v8
- iOS native module ↔ StoreKit API
- Responses flow back: Store → Native → JS → Host
- Plugin at build time modifies Gradle/Kotlin settings to support required billing library version
- Example App illustrates end-to-end flow and triggers tests
- Documentation site is static content—no runtime flow but part of repo

##### Architectural patterns & design principles
- Bridge pattern: JS calls bridged into native code
- Adapter pattern: Native modules adapt to the Open IAP spec
- Modular layering: clear separation between JS, native, build-time plugin, and docs
- Platform abstraction: `src/modules/android.ts` & `src/modules/ios.ts` select platform-specific implementations

##### Detailed elements to capture
- JS entrypoint (`src/index.ts`) and hooks (`useIAP.ts`)
- Platform files (`modules/android.ts`, `modules/ios.ts`)
- Native code under android/src/main/java and ios/
- Expo plugin folder (`plugin/src/...`) and `expo-module.config.json`
- Example app illustrating consumption of the module
- Documentation site driven by `docs/docusaurus.config.ts`

- Top: Host Application
- Next row: JS Layer (expo-iap API) invoking helper/util modules
- Middle: Platform selection → native modules
- Bottom: External Billing Services
- Side: Build-time plugin modifying project config

This detailed breakdown ensures you capture every key part—JS API, native bridge, external services, build-time configuration, docs, and example usage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Application
    HostApp["Host Application (Expo/React-Native)"]:::host

    %% JS Layer
    subgraph "JS Layer (expo-iap API)"
        direction TB
        Index["src/index.ts"]:::js
        UseIAP["src/useIAP.ts"]:::js
        Subscription["src/helpers/subscription.ts"]:::js
        ErrorMapping["src/utils/errorMapping.ts"]:::js
        Constants["src/utils/constants.ts"]:::js
    end

    %% Platform Abstraction
    subgraph "Platform Abstraction"
        direction TB
        AndroidPlatform["src/modules/android.ts"]:::js
        IOSPlatform["src/modules/ios.ts"]:::js
    end

    %% Native Modules
    subgraph "Native Android Module"
        direction TB
        ExpoIapModule["ExpoIapModule.kt"]:::native
        PlayUtils["PlayUtils.kt"]:::native
        Types["Types.kt"]:::native
        MissingCurrentActivityException["MissingCurrentActivityException.kt"]:::native
    end

    subgraph "Native iOS Module"
        direction TB
        ExpoIapModuleIOS["ExpoIapModule.swift"]:::native
        Podspec["ExpoIap.podspec"]:::native
    end

    %% External Services
    subgraph "External Billing Services"
        direction TB
        GooglePlay["Google Play Billing"]:::external
        StoreKit["Apple StoreKit"]:::external
        OpenIAPSpec["Open IAP Spec Endpoint"]:::external
    end

    %% Expo Module Infrastructure
    subgraph "Expo Module Infrastructure"
        direction TB
        ModuleConfig["expo-module.config.json"]:::infra
        ExpoIapModuleTS["src/ExpoIapModule.ts"]:::infra
    end

    %% Expo Plugin
    subgraph "Expo Plugin (build-time)"
        direction TB
        WithIAP["plugin/src/withIAP.ts"]:::plugin
        WithLocalOpenIAP["plugin/src/withLocalOpenIAP.ts"]:::plugin
        PluginTSConfig["plugin/tsconfig.json"]:::plugin
        PluginJest["plugin/jest.config.js"]:::plugin
    end

    %% Example App & Test Harness
    subgraph "Example App & Test Harness"
        direction TB
        ExampleAppMain["example/App.tsx"]:::example
        ExampleTests["example/__tests__/"]:::example
        ExampleMetro["example/metro.config.js"]:::example
        ExampleJest["example/jest.config.js"]:::example
        ExampleIntegration1["example/app/index.tsx"]:::example
        ExampleIntegration2["example/app/purchase-flow.tsx"]:::example
        ExampleIntegration3["example/app/subscription-flow.tsx"]:::example
    end

    %% Documentation Site
    subgraph "Documentation Site"
        direction TB
        DocusaurusConfig["docs/docusaurus.config.ts"]:::docs
        DocsAPI["docs/docs/api/"]:::docs
        DocsIndex["docs/src/pages/index.tsx"]:::docs
        Sidebars["docs/sidebars.ts"]:::docs
    end

    %% Connections - Runtime Flow
    HostApp -->|"calls API"| Index
    Index --> UseIAP
    UseIAP -->|"select platform"| AndroidPlatform
    UseIAP -->|"select platform"| IOSPlatform

    AndroidPlatform --> ExpoIapModule
    AndroidPlatform --> PlayUtils
    AndroidPlatform --> Types
    AndroidPlatform --> MissingCurrentActivityException

    IOSPlatform --> ExpoIapModuleIOS
    IOSPlatform --> Podspec

    ExpoIapModule --> GooglePlay
    PlayUtils --> GooglePlay
    ExpoIapModuleIOS --> StoreKit

    %% Open IAP Spec used by adapters
    ExpoIapModule --> OpenIAPSpec
    ExpoIapModuleIOS --> OpenIAPSpec

    %% Build-Time Config Flow
    WithIAP ---|modifies| HostApp
    WithLocalOpenIAP ---|modifies| HostApp

    %% Infrastructure hooks at runtime
    ModuleConfig --> ExpoIapModuleTS
    ExpoIapModuleTS --> Index

    %% Example & Docs connections
    ExampleAppMain --> Index
    ExampleIntegration1 --> Index
    DocusaurusConfig -.-> DocsAPI
    DocusaurusConfig -.-> DocsIndex
    DocusaurusConfig -.-> Sidebars

    %% Click Events
    click Index "https://github.com/hyochan/expo-iap/blob/main/src/index.ts"
    click UseIAP "https://github.com/hyochan/expo-iap/blob/main/src/useIAP.ts"
    click Subscription "https://github.com/hyochan/expo-iap/blob/main/src/helpers/subscription.ts"
    click ErrorMapping "https://github.com/hyochan/expo-iap/blob/main/src/utils/errorMapping.ts"
    click Constants "https://github.com/hyochan/expo-iap/blob/main/src/utils/constants.ts"
    click AndroidPlatform "https://github.com/hyochan/expo-iap/blob/main/src/modules/android.ts"
    click IOSPlatform "https://github.com/hyochan/expo-iap/blob/main/src/modules/ios.ts"
    click ExpoIapModule "https://github.com/hyochan/expo-iap/blob/main/android/src/main/java/expo/modules/iap/ExpoIapModule.kt"
    click PlayUtils "https://github.com/hyochan/expo-iap/blob/main/android/src/main/java/expo/modules/iap/PlayUtils.kt"
    click Types "https://github.com/hyochan/expo-iap/blob/main/android/src/main/java/expo/modules/iap/Types.kt"
    click MissingCurrentActivityException "https://github.com/hyochan/expo-iap/blob/main/android/src/main/java/expo/modules/iap/MissingCurrentActivityException.kt"
    click ExpoIapModuleIOS "https://github.com/hyochan/expo-iap/blob/main/ios/ExpoIapModule.swift"
    click Podspec "https://github.com/hyochan/expo-iap/blob/main/ios/ExpoIap.podspec"
    click ModuleConfig "https://github.com/hyochan/expo-iap/blob/main/expo-module.config.json"
    click ExpoIapModuleTS "https://github.com/hyochan/expo-iap/blob/main/src/ExpoIapModule.ts"
    click WithIAP "https://github.com/hyochan/expo-iap/blob/main/plugin/src/withIAP.ts"
    click WithLocalOpenIAP "https://github.com/hyochan/expo-iap/blob/main/plugin/src/withLocalOpenIAP.ts"
    click PluginTSConfig "https://github.com/hyochan/expo-iap/blob/main/plugin/tsconfig.json"
    click PluginJest "https://github.com/hyochan/expo-iap/blob/main/plugin/jest.config.js"
    click ExampleAppMain "https://github.com/hyochan/expo-iap/blob/main/example/App.tsx"
    click ExampleTests "https://github.com/hyochan/expo-iap/tree/main/example/__tests__/"
    click ExampleMetro "https://github.com/hyochan/expo-iap/blob/main/example/metro.config.js"
    click ExampleJest "https://github.com/hyochan/expo-iap/blob/main/example/jest.config.js"
    click ExampleIntegration1 "https://github.com/hyochan/expo-iap/blob/main/example/app/index.tsx"
    click ExampleIntegration2 "https://github.com/hyochan/expo-iap/blob/main/example/app/purchase-flow.tsx"
    click ExampleIntegration3 "https://github.com/hyochan/expo-iap/blob/main/example/app/subscription-flow.tsx"
    click DocusaurusConfig "https://github.com/hyochan/expo-iap/blob/main/docs/docusaurus.config.ts"
    click DocsAPI "https://github.com/hyochan/expo-iap/tree/main/docs/docs/api/"
    click DocsIndex "https://github.com/hyochan/expo-iap/blob/main/docs/src/pages/index.tsx"
    click Sidebars "https://github.com/hyochan/expo-iap/blob/main/docs/sidebars.ts"

    %% Styles
    classDef js fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef native fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef plugin fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef docs fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef example fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef host fill:#f0f0f0,stroke:#333,stroke-width:1px
```
