# revenuecat/purchases-flutter architecture

> Architecture diagram of the GitHub repository revenuecat/purchases-flutter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/revenuecat/purchases-flutter
- Repository: https://github.com/revenuecat/purchases-flutter

## Overview

#### Purpose and entry points
`purchases_flutter` is a Flutter plugin exposing RevenueCat subscription, purchase, entitlement, and receipt-status capabilities over native store SDKs and the RevenueCat backend. Its public Dart entry point is `lib/purchases_flutter.dart`; shared error and domain APIs start at `lib/errors.dart` and `lib/models/`. A companion UI package provides native paywall and customer-center views via `purchases_ui_flutter/lib/purchases_ui_flutter.dart`.

#### Core Dart API and domain contract
The main package presents a Dart-facing API, configuration, purchase parameters/results, and strongly typed wrappers for native/RevenueCat payloads. Models isolate app consumers from platform-channel map shapes and encode offerings, customer info, products, transactions, subscriptions, virtual currencies, and web redemption.
- `lib/purchases_flutter.dart`
- `lib/models/purchases_configuration.dart`
- `lib/models/customer_info_wrapper.dart`

#### Flutter-to-native purchase boundary
Dart calls are bridged through the Flutter plugin implementations into RevenueCat’s native SDK integrations. Android registers the plugin in Java; iOS/macOS package native implementations are Objective-C. This boundary owns interaction with Google Play Billing and Apple StoreKit rather than implementing store transactions in Dart.
- `android/src/main/java/com/revenuecat/purchases_flutter/PurchasesFlutterPlugin.java`
- `ios/purchases_flutter/Sources/purchases_flutter/PurchasesFlutterPlugin.m`
- `macos/purchases_flutter/Sources/purchases_flutter/PurchasesFlutterPlugin.m`

#### Web runtime path
Web is a separate implementation layer, backed by a JavaScript hybrid mapping asset. It adapts the same Dart API to browser-compatible RevenueCat functionality; it is not routed through Android/iOS platform channels.
- `lib/web/purchases_flutter_web.dart`
- `assets/web/purchases_js_hybrid_mappings.js`

#### Purchase and entitlement flow
Application code configures the SDK, identifies/configures a user, retrieves offerings/products, initiates a purchase or restore, then receives typed purchase/customer-info results. Native SDKs communicate with the applicable store and RevenueCat services; RevenueCat performs server-side receipt validation and returns subscription/entitlement state. Dart wrappers deserialize the result boundary for Flutter callers.
- `lib/models/offering_wrapper.dart`
- `lib/models/purchase_params.dart`
- `lib/models/purchase_result.dart`

#### Native UI package
`purchases_ui_flutter` is a distinct Flutter plugin layered over the core purchasing SDK. Its Dart widgets/method handlers host platform-native paywall, footer, and customer-center views; Android uses platform view factories/views, while iOS uses Swift native view wrappers. UI results and presentation configuration cross the same plugin boundary.
- `purchases_ui_flutter/lib/views/paywall_view.dart`
- `purchases_ui_flutter/android/src/main/kotlin/com/revenuecat/purchases_ui_flutter/views/PaywallView.kt`
- `purchases_ui_flutter/ios/purchases_ui_flutter/Sources/purchases_ui_flutter/PurchasesUiPaywallView.swift`

#### Runtimes, delivery, and validation clients
The repository is primarily Dart/Flutter, with Android Gradle/Java/Kotlin and Apple CocoaPods/Swift Package Manager/Objective-C/Swift host integrations. The core package is defined for pub publishing in `pubspec.yaml`; native package manifests support direct Apple dependency integration. `api_tester` is a Flutter executable that exercises the exposed API surface, while Maestro runs end-to-end purchase-through-paywall validation against a dedicated test app.
- `pubspec.yaml`
- `api_tester/lib/main.dart`
- `e2e-tests/maestro/e2e_tests/purchase_through_paywall.yaml`

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Flutter SDK"]
  node_dart_api["Public Dart API<br/>Flutter API"]
  node_domain_models["Typed domain models<br/>Dart models"]
  node_configuration["Purchase configuration<br/>Dart configuration"]
  node_purchase_contract["Purchase contracts<br/>Dart models"]
  node_web_adapter["Web implementation<br/>Flutter web adapter"]
  node_web_js_bridge["Hybrid JS mappings<br/>JavaScript bridge"]
end

subgraph group_native["Native runtimes"]
  node_android_plugin["Android plugin bridge<br/>Java plugin"]
  node_apple_plugin["iOS/macOS plugin bridges<br/>Objective-C plugins"]
  node_stores["App stores<br/>Google Play / StoreKit"]
  node_revenuecat[("RevenueCat services<br/>Backend")]
end

subgraph group_ui["Native UI plugin"]
  node_ui_dart["UI Flutter API<br/>Flutter UI plugin<br/>[paywall_view.dart]"]
  node_ui_android["Android paywall view<br/>Kotlin platform view<br/>[PaywallView.kt]"]
  node_ui_ios["iOS paywall view<br/>Swift native view"]
end

subgraph group_validation["Delivery &amp; validation"]
  node_package_manifest["Published package<br/>pub package<br/>[pubspec.yaml]"]
  node_api_tester["API tester<br/>Flutter executable<br/>[main.dart]"]
  node_maestro_e2e["Purchase E2E flow<br/>Maestro test flow"]
end

node_package_manifest -->|"publishes"| node_dart_api
node_dart_api -->|"configures"| node_configuration
node_dart_api -->|"uses"| node_purchase_contract
node_dart_api -->|"returns"| node_domain_models
node_dart_api -->|"platform channel"| node_android_plugin
node_dart_api -->|"platform channel"| node_apple_plugin
node_dart_api -->|"web runtime"| node_web_adapter
node_web_adapter -->|"uses"| node_web_js_bridge
node_android_plugin -->|"purchase operations"| node_stores
node_apple_plugin -->|"purchase operations"| node_stores
node_android_plugin -->|"customer and receipt state"| node_revenuecat
node_apple_plugin -->|"customer and receipt state"| node_revenuecat
node_stores -->|"receipts"| node_revenuecat
node_revenuecat -.->|"typed state response"| node_domain_models
node_ui_dart -->|"layers on core SDK"| node_dart_api
node_ui_dart -->|"platform view"| node_ui_android
node_ui_dart -->|"native view"| node_ui_ios
node_api_tester -.->|"exercises"| node_dart_api
node_maestro_e2e -.->|"validates paywall purchase"| node_ui_dart

click node_dart_api "https://github.com/revenuecat/purchases-flutter/blob/main/lib/purchases_flutter.dart"
click node_domain_models "https://github.com/revenuecat/purchases-flutter/blob/main/lib/models/customer_info_wrapper.dart"
click node_configuration "https://github.com/revenuecat/purchases-flutter/blob/main/lib/models/purchases_configuration.dart"
click node_purchase_contract "https://github.com/revenuecat/purchases-flutter/blob/main/lib/models/purchase_result.dart"
click node_web_adapter "https://github.com/revenuecat/purchases-flutter/blob/main/lib/web/purchases_flutter_web.dart"
click node_web_js_bridge "https://github.com/revenuecat/purchases-flutter/blob/main/assets/web/purchases_js_hybrid_mappings.js"
click node_android_plugin "https://github.com/revenuecat/purchases-flutter/blob/main/android/src/main/java/com/revenuecat/purchases_flutter/PurchasesFlutterPlugin.java"
click node_apple_plugin "https://github.com/revenuecat/purchases-flutter/blob/main/ios/purchases_flutter/Sources/purchases_flutter/PurchasesFlutterPlugin.m"
click node_ui_dart "https://github.com/revenuecat/purchases-flutter/blob/main/purchases_ui_flutter/lib/views/paywall_view.dart"
click node_ui_android "https://github.com/revenuecat/purchases-flutter/blob/main/purchases_ui_flutter/android/src/main/kotlin/com/revenuecat/purchases_ui_flutter/views/PaywallView.kt"
click node_ui_ios "https://github.com/revenuecat/purchases-flutter/blob/main/purchases_ui_flutter/ios/purchases_ui_flutter/Sources/purchases_ui_flutter/PurchasesUiPaywallView.swift"
click node_package_manifest "https://github.com/revenuecat/purchases-flutter/blob/main/pubspec.yaml"
click node_api_tester "https://github.com/revenuecat/purchases-flutter/blob/main/api_tester/lib/main.dart"
click node_maestro_e2e "https://github.com/revenuecat/purchases-flutter/blob/main/e2e-tests/maestro/e2e_tests/purchase_through_paywall.yaml"

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_dart_api,node_domain_models,node_configuration,node_purchase_contract,node_web_adapter,node_web_js_bridge toneBlue
class node_android_plugin,node_apple_plugin,node_stores,node_revenuecat toneAmber
class node_ui_dart,node_ui_android,node_ui_ios toneMint
class node_package_manifest,node_api_tester,node_maestro_e2e toneRose
```

## Components

### Core Flutter SDK

- [Public Dart API](https://github.com/revenuecat/purchases-flutter/blob/main/lib/purchases_flutter.dart): Flutter API · Configuration and purchase APIs exposed to apps. · `lib/purchases_flutter.dart`
- [Typed domain models](https://github.com/revenuecat/purchases-flutter/blob/main/lib/models/customer_info_wrapper.dart): Dart models · Wraps offerings, customer state, products, and transactions. · `lib/models/customer_info_wrapper.dart`
- [Purchase configuration](https://github.com/revenuecat/purchases-flutter/blob/main/lib/models/purchases_configuration.dart): Dart configuration · `lib/models/purchases_configuration.dart`
- [Purchase contracts](https://github.com/revenuecat/purchases-flutter/blob/main/lib/models/purchase_result.dart): Dart models · Parameters and typed purchase outcomes. · `lib/models/purchase_result.dart`
- [Web implementation](https://github.com/revenuecat/purchases-flutter/blob/main/lib/web/purchases_flutter_web.dart): Flutter web adapter · `lib/web/purchases_flutter_web.dart`
- [Hybrid JS mappings](https://github.com/revenuecat/purchases-flutter/blob/main/assets/web/purchases_js_hybrid_mappings.js): JavaScript bridge · `assets/web/purchases_js_hybrid_mappings.js`

### Native runtimes

- [Android plugin bridge](https://github.com/revenuecat/purchases-flutter/blob/main/android/src/main/java/com/revenuecat/purchases_flutter/PurchasesFlutterPlugin.java): Java plugin · Bridges Dart calls to the Android RevenueCat SDK. · `android/src/main/java/com/revenuecat/purchases_flutter/PurchasesFlutterPlugin.java`
- [iOS/macOS plugin bridges](https://github.com/revenuecat/purchases-flutter/blob/main/ios/purchases_flutter/Sources/purchases_flutter/PurchasesFlutterPlugin.m): Objective-C plugins · Bridge Dart calls to Apple RevenueCat SDK integrations. · `ios/purchases_flutter/Sources/purchases_flutter/PurchasesFlutterPlugin.m`
- **App stores**: Google Play / StoreKit
- **RevenueCat services**: Backend · Validates receipts and returns subscription and entitlement state.

### Native UI plugin

- [UI Flutter API](https://github.com/revenuecat/purchases-flutter/blob/main/purchases_ui_flutter/lib/views/paywall_view.dart): Flutter UI plugin · Hosts paywall and customer-center presentation APIs. · `purchases_ui_flutter/lib/views/paywall_view.dart`
- [Android paywall view](https://github.com/revenuecat/purchases-flutter/blob/main/purchases_ui_flutter/android/src/main/kotlin/com/revenuecat/purchases_ui_flutter/views/PaywallView.kt): Kotlin platform view · `purchases_ui_flutter/android/src/main/kotlin/com/revenuecat/purchases_ui_flutter/views/PaywallView.kt`
- [iOS paywall view](https://github.com/revenuecat/purchases-flutter/blob/main/purchases_ui_flutter/ios/purchases_ui_flutter/Sources/purchases_ui_flutter/PurchasesUiPaywallView.swift): Swift native view · `purchases_ui_flutter/ios/purchases_ui_flutter/Sources/purchases_ui_flutter/PurchasesUiPaywallView.swift`

### Delivery & validation

- [Published package](https://github.com/revenuecat/purchases-flutter/blob/main/pubspec.yaml): pub package · `pubspec.yaml`
- [API tester](https://github.com/revenuecat/purchases-flutter/blob/main/api_tester/lib/main.dart): Flutter executable · Exercises the exposed SDK API surface. · `api_tester/lib/main.dart`
- [Purchase E2E flow](https://github.com/revenuecat/purchases-flutter/blob/main/e2e-tests/maestro/e2e_tests/purchase_through_paywall.yaml): Maestro test flow · Validates purchase through native paywall. · `e2e-tests/maestro/e2e_tests/purchase_through_paywall.yaml`

## Connections

- Published package → Public Dart API: publishes
- Public Dart API → Purchase configuration: configures
- Public Dart API → Purchase contracts: uses
- Public Dart API → Typed domain models: returns
- Public Dart API → Android plugin bridge: platform channel
- Public Dart API → iOS/macOS plugin bridges: platform channel
- Public Dart API → Web implementation: web runtime
- Web implementation → Hybrid JS mappings: uses
- Android plugin bridge → App stores: purchase operations
- iOS/macOS plugin bridges → App stores: purchase operations
- Android plugin bridge → RevenueCat services: customer and receipt state
- iOS/macOS plugin bridges → RevenueCat services: customer and receipt state
- App stores → RevenueCat services: receipts
- RevenueCat services → Typed domain models: typed state response
- UI Flutter API → Public Dart API: layers on core SDK
- UI Flutter API → Android paywall view: platform view
- UI Flutter API → iOS paywall view: native view
- API tester → Public Dart API: exercises
- Purchase E2E flow → UI Flutter API: validates paywall purchase
