# myreach-sa/capacitor-native-share architecture

> Architecture diagram of the GitHub repository myreach-sa/capacitor-native-share, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/myreach-sa/capacitor-native-share
- Repository: https://github.com/myreach-sa/capacitor-native-share

## Overview

##### Project type and purpose
- This is a Capacitor plugin (“@rea.ch/capacitor-native-share”) that exposes native Android and iOS share‐target functionality as JavaScript events.
- It provides a unified JS API (`getLastSharedItems`, `addListener`) and bridges to two platform‐specific modules plus a web fallback.

##### File structure
- Top-level:
- src/ – JS interface, web fallback, TypeScript definitions
- android/ – Android plugin module (Java code, Gradle files, intent filters)
- ios/ – Xcode project for the plugin, Swift/Obj-C bridges, share extension helpers
- example/ – A sample Capacitor/Ionic app demonstrating integration on Android and iOS
- rollup.config.js, package.json – build & packaging of the plugin
- Patterns:
- Bridge pattern: JS → Capacitor bridge → native module
- Plugin/extension pattern on iOS: host app + share extension + app group storage

##### Key insights from README
- JS side: exposes two methods and an event type
- Android: relies on intent-filters in AndroidManifest.xml
- iOS: uses an App Extension, App Group, URL schemes, and delegates in AppDelegate

##### Main components & their interactions
a. Components
1. Host Application (Ionic/Capacitor app)
2. Plugin JS Layer (src/index.ts, src/web.ts)
3. Capacitor Runtime/Bridge
4. Android Native Plugin (android/src/main/java/.../NativeSharePlugin.java)
5. iOS Native Plugin (ios/Plugin/NativeSharePlugin.swift)
6. iOS Share Extension (ios/Plugin/NativeShareExtension.swift subclass)
7. Shared Data Store (iOS App Group container; Android temporary storage via Intent extras)
8. Example App (example/native-share-example)

b. Relationships & data flows
- At runtime, the host app invokes `NativeShare.getLastSharedItems()` or registers `NativeShare.addListener()`.
- The plugin JS calls `Capacitor.Plugins.NativeShare.getLastSharedItems()` → bridge → native module.
- Android:
– OS issues a SHARE intent → the plugin’s intent filter catches it → NativeSharePlugin reads Intent extras → passes data back to JS via the bridge.
- iOS:
– Share Extension intercepts share → writes shared items to the App Group container → invokes host via custom URL scheme → AppDelegate receives URL → `NativeShareDelegateUtils.handleApplicationUrl` loads items from the shared container → plugin dispatches JS event.
- Web: fallback in src/web.ts returns empty or dummy.

c. Architectural patterns & principles
- Cross‐platform plugin abstraction layer
- Bridge pattern courtesy of Capacitor runtime
- Separation of concerns: JS API vs. platform implementations vs. example app
- Modular design: Android and iOS code co-exist but remain platform-specific

d. Relevant technologies
- TypeScript, Rollup for bundling
- Capacitor plugin API
- Android intents, Gradle build system
- iOS App Extensions, App Groups, Swift/Obj-C bridging
- Example uses Angular/Ionic

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Application"
        HA["Example App"]:::example
    end

    subgraph "JS Layer"
        JSAPI["Plugin JS API\n(src/index.ts)"]:::js
        WEB_FALLBACK["Web Fallback\n(src/web.ts)"]:::js
        DEF["Definitions\n(src/definitions.ts)"]:::js
    end

    BR["Capacitor Bridge"]:::bridge

    subgraph "Native Modules"
        subgraph Android
            AND_INTENT["Intent Filter"]:::android
            AND_PLUG1["NativeSharePlugin.java"]:::android
            AND_PLUG2["NativeShare.java"]:::android
        end
        subgraph iOS
            IOS_PLUGIN_SWIFT["NativeSharePlugin.swift"]:::ios
            IOS_PLUGIN_H["NativeSharePlugin.h"]:::ios
            IOS_PLUGIN_M["NativeSharePlugin.m"]:::ios
            IOS_EXT["Share Extension\n(NativeShareExtension.swift)"]:::ios
            IOS_STORE1["NativeShareStore.swift"]:::ios
            IOS_STORE2["NativeShareItem.swift"]:::ios
            IOS_DELEG["NativeShareDelegateUtils.swift"]:::ios
            IOS_POD["Rea.chCapacitorNativeShare.podspec"]:::ios
        end
        subgraph Web
            WEB_FALL["Web WebFallback"]:::web
        end
    end

    subgraph "Build & Packaging"
        ROLLUP["rollup.config.js"]:::build
        PKG["package.json"]:::build
    end

    subgraph "OS / Platform"
        OS_AND["Android OS\n(Share Intent)"]:::android
        OS_IOS["iOS OS\n(Custom URL Scheme)"]:::ios
    end

    HA -->|"calls getLastSharedItems()/addListener()"| JSAPI
    JSAPI -->|"calls"| BR
    BR -->|"invoke plugin"| AND_PLUG1
    BR -->|"invoke plugin"| AND_PLUG2
    BR -->|"invoke plugin"| IOS_PLUGIN_SWIFT
    BR -->|"invoke plugin"| WEB_FALL
    OS_AND -->|"triggers intent"| AND_INTENT
    AND_INTENT -->|"caught by filter"| AND_PLUG1
    AND_PLUG1 -->|"reads intent extras"| AND_PLUG2
    AND_PLUG2 -->|"event via bridge"| JSAPI
    IOS_EXT -->|"stores items"| IOS_STORE1
    IOS_EXT -->|"stores items"| IOS_STORE2
    IOS_EXT -->|"invokes URL scheme"| OS_IOS
    OS_IOS -->|"AppDelegate handles URL"| IOS_DELEG
    IOS_DELEG -->|"loads from store"| IOS_STORE1
    IOS_DELEG -->|"loads from store"| IOS_STORE2
    IOS_DELEG -->|"dispatches JS event"| IOS_PLUGIN_SWIFT
    IOS_PLUGIN_SWIFT -->|"event via bridge"| JSAPI
    JSAPI -->|"fallback returns dummy"| WEB_FALL

    BR --- ROLLUP
    ROLLUP --- PKG

    click HA "https://github.com/myreach-sa/capacitor-native-share/tree/main/example/native-share-example"
    click JSAPI "https://github.com/myreach-sa/capacitor-native-share/blob/main/src/index.ts"
    click WEB_FALLBACK "https://github.com/myreach-sa/capacitor-native-share/blob/main/src/web.ts"
    click DEF "https://github.com/myreach-sa/capacitor-native-share/blob/main/src/definitions.ts"
    click AND_PLUG1 "https://github.com/myreach-sa/capacitor-native-share/blob/main/android/src/main/java/ch/rea/plugins/nativeshare/NativeSharePlugin.java"
    click AND_PLUG2 "https://github.com/myreach-sa/capacitor-native-share/blob/main/android/src/main/java/ch/rea/plugins/nativeshare/NativeShare.java"
    click IOS_PLUGIN_SWIFT "https://github.com/myreach-sa/capacitor-native-share/blob/main/ios/Plugin/NativeSharePlugin.swift"
    click IOS_PLUGIN_H "https://github.com/myreach-sa/capacitor-native-share/blob/main/ios/Plugin/NativeSharePlugin.h"
    click IOS_PLUGIN_M "https://github.com/myreach-sa/capacitor-native-share/blob/main/ios/Plugin/NativeSharePlugin.m"
    click IOS_EXT "https://github.com/myreach-sa/capacitor-native-share/blob/main/ios/Plugin/NativeShareExtension.swift"
    click IOS_STORE1 "https://github.com/myreach-sa/capacitor-native-share/blob/main/ios/Plugin/NativeShareStore.swift"
    click IOS_STORE2 "https://github.com/myreach-sa/capacitor-native-share/blob/main/ios/Plugin/NativeShareItem.swift"
    click IOS_DELEG "https://github.com/myreach-sa/capacitor-native-share/blob/main/ios/Plugin/NativeShareDelegateUtils.swift"
    click IOS_POD "https://github.com/myreach-sa/capacitor-native-share/blob/main/Rea.chCapacitorNativeShare.podspec"
    click ROLLUP "https://github.com/myreach-sa/capacitor-native-share/blob/main/rollup.config.js"
    click PKG "https://github.com/myreach-sa/capacitor-native-share/blob/main/package.json"

    classDef example fill:#fff1c4,stroke:#333,stroke-width:1px
    classDef js fill:#e0e0e0,stroke:#333
    classDef bridge fill:#ffd54f,stroke:#333
    classDef android fill:#c8e6c9,stroke:#333
    classDef ios fill:#bbdefb,stroke:#333
    classDef web fill:#f5f5f5,stroke:#333
    classDef build fill:#dcedc8,stroke:#333
```
