# aparajita/capacitor-secure-storage architecture

> Architecture diagram of the GitHub repository aparajita/capacitor-secure-storage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aparajita/capacitor-secure-storage
- Repository: https://github.com/aparajita/capacitor-secure-storage

## Overview

This is a Capacitor plugin for storing JSON-compatible key/value data securely on iOS and Android, with an explicitly debug-only web implementation. The workflow is: callers use the registered plugin API; a shared layer handles prefixes, serialization, sync/access options, and errors; platform adapters perform storage operations. iOS uses the system keychain with optional iCloud synchronization, while Android encrypts values with AES-GCM using Android KeyStore keys and stores them in app-specific SharedPreferences. The README documents platform behavior; unsampled implementation details and links are omitted where not evidenced.

Main entry points: [`src/index.ts`](https://github.com/aparajita/capacitor-secure-storage/blob/main/src/index.ts) (Platform registration), [`src/native.ts`](https://github.com/aparajita/capacitor-secure-storage/blob/main/src/native.ts) (Native adapter), [`android/src/main/java/com/aparajita/capacitor/securestorage/SecureStorage.java`](https://github.com/aparajita/capacitor-secure-storage/blob/main/android/src/main/java/com/aparajita/capacitor/securestorage/SecureStorage.java) (Android plugin), [`src/web.ts`](https://github.com/aparajita/capacitor-secure-storage/blob/main/src/web.ts) (Web adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Plugin API"]
  node_api["Public API<br/>[definitions.ts]"]
  node_registration["Platform registration<br/>[index.ts]"]
end

subgraph group_shared["Shared runtime"]
  node_base["Storage operations<br/>[base.ts]"]
  node_native["Native adapter<br/>[native.ts]"]
  node_web["Web adapter<br/>[web.ts]"]
  node_localstorage[("Browser storage")]
end

subgraph group_ios["iOS storage"]
  node_iosplugin["Keychain plugin<br/>[Plugin.swift]"]
  node_ioserrors["Keychain errors"]
  node_keychain[("System keychain")]
end

subgraph group_android["Android storage"]
  node_androidplugin["Android plugin<br/>[SecureStorage.java]"]
  node_androiderrors["Storage errors"]
  node_keystore[("Android KeyStore")]
  node_preferences[("SharedPreferences")]
end

node_caller(("Application"))

node_caller -->|"uses plugin"| node_registration
node_registration -->|"loads native"| node_native
node_registration -->|"loads web"| node_web
node_registration -->|"exposes types"| node_api
node_native -->|"extends operations"| node_base
node_web -->|"extends operations"| node_base
node_base -->|"implements contract"| node_api
node_web -.->|"stores values"| node_localstorage
node_native -.->|"dispatches calls"| node_iosplugin
node_native -.->|"dispatches calls"| node_androidplugin
node_iosplugin -->|"reads and writes"| node_keychain
node_iosplugin -->|"rejects errors"| node_ioserrors
node_androidplugin -->|"encrypts with keys"| node_keystore
node_androidplugin -->|"stores ciphertext"| node_preferences
node_androidplugin -->|"reports failures"| node_androiderrors

click node_api "https://github.com/aparajita/capacitor-secure-storage/blob/main/src/definitions.ts"
click node_registration "https://github.com/aparajita/capacitor-secure-storage/blob/main/src/index.ts"
click node_base "https://github.com/aparajita/capacitor-secure-storage/blob/main/src/base.ts"
click node_native "https://github.com/aparajita/capacitor-secure-storage/blob/main/src/native.ts"
click node_web "https://github.com/aparajita/capacitor-secure-storage/blob/main/src/web.ts"
click node_iosplugin "https://github.com/aparajita/capacitor-secure-storage/blob/main/ios/Sources/SecureStoragePlugin/Plugin.swift"
click node_ioserrors "https://github.com/aparajita/capacitor-secure-storage/blob/main/ios/Sources/SecureStoragePlugin/KeychainError.swift"
click node_androidplugin "https://github.com/aparajita/capacitor-secure-storage/blob/main/android/src/main/java/com/aparajita/capacitor/securestorage/SecureStorage.java"
click node_androiderrors "https://github.com/aparajita/capacitor-secure-storage/blob/main/android/src/main/java/com/aparajita/capacitor/securestorage/KeyStoreException.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_registration toneBlue
class node_base,node_native,node_web,node_localstorage toneAmber
class node_iosplugin,node_ioserrors,node_keychain toneMint
class node_androidplugin,node_androiderrors,node_keystore,node_preferences toneRose
class node_caller toneIndigo
```

## Components

### Plugin API

- [Public API](https://github.com/aparajita/capacitor-secure-storage/blob/main/src/definitions.ts): `src/definitions.ts`
- [Platform registration](https://github.com/aparajita/capacitor-secure-storage/blob/main/src/index.ts): `src/index.ts`

### Shared runtime

- [Storage operations](https://github.com/aparajita/capacitor-secure-storage/blob/main/src/base.ts): `src/base.ts`
- [Native adapter](https://github.com/aparajita/capacitor-secure-storage/blob/main/src/native.ts): `src/native.ts`
- [Web adapter](https://github.com/aparajita/capacitor-secure-storage/blob/main/src/web.ts): `src/web.ts`
- **Browser storage**

### iOS storage

- [Keychain plugin](https://github.com/aparajita/capacitor-secure-storage/blob/main/ios/Sources/SecureStoragePlugin/Plugin.swift): `ios/Sources/SecureStoragePlugin/Plugin.swift`
- [Keychain errors](https://github.com/aparajita/capacitor-secure-storage/blob/main/ios/Sources/SecureStoragePlugin/KeychainError.swift): `ios/Sources/SecureStoragePlugin/KeychainError.swift`
- **System keychain**

### Android storage

- [Android plugin](https://github.com/aparajita/capacitor-secure-storage/blob/main/android/src/main/java/com/aparajita/capacitor/securestorage/SecureStorage.java): `android/src/main/java/com/aparajita/capacitor/securestorage/SecureStorage.java`
- [Storage errors](https://github.com/aparajita/capacitor-secure-storage/blob/main/android/src/main/java/com/aparajita/capacitor/securestorage/KeyStoreException.java): `android/src/main/java/com/aparajita/capacitor/securestorage/KeyStoreException.java`
- **Android KeyStore**
- **SharedPreferences**

### Other components

- **Application**

## Connections

- Application → Platform registration: uses plugin (evidence: `src/index.ts`)
- Platform registration → Native adapter: loads native (evidence: `src/index.ts`)
- Platform registration → Web adapter: loads web (evidence: `src/index.ts`)
- Platform registration → Public API: exposes types (evidence: `src/index.ts`)
- Native adapter → Storage operations: extends operations (evidence: `src/native.ts`)
- Web adapter → Storage operations: extends operations (evidence: `src/web.ts`)
- Storage operations → Public API: implements contract (evidence: `src/base.ts`)
- Web adapter → Browser storage: stores values (evidence: `README.md`)
- Native adapter → Keychain plugin: dispatches calls
- Native adapter → Android plugin: dispatches calls
- Keychain plugin → System keychain: reads and writes (evidence: `ios/Sources/SecureStoragePlugin/Plugin.swift`)
- Keychain plugin → Keychain errors: rejects errors (evidence: `ios/Sources/SecureStoragePlugin/Plugin.swift`)
- Android plugin → Android KeyStore: encrypts with keys (evidence: `README.md`)
- Android plugin → SharedPreferences: stores ciphertext (evidence: `README.md`)
- Android plugin → Storage errors: reports failures (evidence: `android/src/main/java/com/aparajita/capacitor/securestorage/SecureStorage.java`)
