# epicshaggy/capacitor-native-biometric architecture

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

- Interactive diagram: https://gitdiagram.com/epicshaggy/capacitor-native-biometric
- Repository: https://github.com/epicshaggy/capacitor-native-biometric

## Overview

##### Major Components
- Frontend/JavaScript Layer – The plugin exposes its API via TypeScript/JavaScript in the “src” directory (files such as index.ts, web.ts, and definitions.ts). This is the entry point for app developers.
- Capacitor Bridge – The mechanism that connects the plugin’s JavaScript side with the native layers on iOS and Android.
- Android Native Component – Located under the “android” directory; it contains Java classes (such as NativeBiometric.java and AuthActivity.java), AndroidManifest, resource files, and tests. This component uses Android’s BiometricPrompt API and handles secure storage with the Keystore.
- iOS Native Component – Found in the “ios” directory, including an Xcode project, Plugin header/source files, and Swift files. This component interacts with iOS’s biometric frameworks (e.g., FaceID/TouchID) and performs secure storage using Keychain.
- Operating System Biometric Services – External services (on each platform) that actually execute the device’s biometric authentication.
- Secure Credential Store – Represents the storage system (iOS Keychain and Android Keystore) used to store/retrieve user credentials.

##### Out Relationships and Data Flow
- The application’s developer invokes a function (for example, verifyIdentity or setCredentials) via the JavaScript API.
- The invocation goes through the Capacitor Bridge which directs the request to the native platform’s plugin implementation.
- On Android, the request triggers biometric authentication (using classes like NativeBiometric and AuthActivity), which then communicates with Android’s biometric services through the native APIs.
- On iOS, similarly, the request invokes the native biometric methods defined in the Plugin folder to display biometric prompts and interact with FaceID/TouchID.
- After the biometric verification is complete, native modules interact with secure storage (Keychain/Keystore) to save or retrieve credentials securely.
- The response (success/failure, errors, or credentials) then flows back from the native modules through the Capacitor Bridge to the JavaScript API, which returns a Promise to the app’s code.

##### Architectural Patterns & Design Principles
- Bridge Pattern – The Capacitor Bridge acts as a mediator between the JS code and native implementations.
- Platform Abstraction – Unified API design so that the web-side developer does not worry about platform differences.
- Secure Storage and Authentication – Emphasis on security by using native secure storage and leveraging native biometric frameworks.
- Modular Design – Separation of concerns with independent modules (JS, Android, iOS) that interact through defined interfaces.

##### Following Elements
- “JavaScript API (src)”
- “Capacitor Bridge”
- “Android Plugin Module” with its key classes (e.g., NativeBiometric, AuthActivity)
- “iOS Plugin Module” (with Plugin.swift/Plugin.h implementations)
- “Native Biometric Services (Android API / iOS FaceID/TouchID)”
- “Secure Credential Store (Keystore / Keychain)”
- Data flow: e.g., API call from JS → Capacitor Bridge → Native Plugin
- Response flow: native verification result back up the chain.
- Dependency connections: native plugin’s dependency on OS services.
- “Credential Storage using Keychain (iOS)” and “Encryption via Keystore (Android)”
- “Biometric Prompt parameters and customization (see BiometricOptions in README)”

##### Final Advice
- Secure, modular, and cross-platform aspects of the plugin.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        DEV["Developer"]:::external
        JS["JavaScript API (src)\n(index.ts, web.ts, definitions.ts)"]:::js
        BRIDGE["Capacitor Bridge"]:::js
    end

    %% Native Modules Layer
    subgraph "Native Modules"
        ANDROID["Android Plugin Module\n(NativeBiometric, AuthActivity)"]:::android
        IOS["iOS Plugin Module\n(Plugin.h, Plugin.m, Plugin.swift)"]:::ios
    end

    %% External Services Layer
    subgraph "External Services"
        OSBIO["Native Biometric Services\n(Android API / iOS FaceID/TouchID)"]:::external
        STORE["Secure Credential Store\n(Keystore/Keychain)"]:::external
    end

    %% Flow of requests from Developer to JS API
    DEV -->|"callsAPI"| JS
    JS -->|"invokes"| BRIDGE

    %% Bridge routes request to native modules
    BRIDGE -->|"routesTo"| ANDROID
    BRIDGE -->|"routesTo"| IOS

    %% Native modules interact with external services
    ANDROID -->|"calls"| OSBIO
    ANDROID -->|"calls"| STORE
    IOS -->|"calls"| OSBIO
    IOS -->|"calls"| STORE

    %% External services return responses to native modules
    OSBIO -->|"returns"| ANDROID
    STORE -->|"returns"| ANDROID
    OSBIO -->|"returns"| IOS
    STORE -->|"returns"| IOS

    %% Native modules send responses back via the bridge
    ANDROID -->|"sendsResponse"| BRIDGE
    IOS -->|"sendsResponse"| BRIDGE
    BRIDGE -->|"returnsResponse"| JS
    JS -->|"resolvesPromise"| DEV

    %% Click Events
    click JS "https://github.com/epicshaggy/capacitor-native-biometric/blob/master/src/index.ts"
    click ANDROID "https://github.com/epicshaggy/capacitor-native-biometric/tree/master/android/src/main/java/com/epicshaggy/biometric"
    click IOS "https://github.com/epicshaggy/capacitor-native-biometric/tree/master/ios/Plugin"

    %% Styles
    classDef js fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef android fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef ios fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;

    class JS,BRIDGE js;
    class ANDROID android;
    class IOS ios;
    class DEV,OSBIO,STORE external
```
