# forgerock/forgerock-android-sdk architecture

> Architecture diagram of the GitHub repository forgerock/forgerock-android-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/forgerock/forgerock-android-sdk
- Repository: https://github.com/forgerock/forgerock-android-sdk

## Overview

##### Project Type and Purpose
- This is an Android SDK (library) for integrating Ping/ForgeRock Identity Platform into Android apps.
- It contains a sample “e2e” app, multiple SDK modules (auth UI, core auth, 2FA authenticator, risk plugin, core utilities), and integration-test modules.

##### File Structure
- Top-level Gradle modules:
– e2e/app: sample Android application demonstrating the SDK (MVVM + Jetpack Compose navigation).
– forgerock-auth-ui: UI components for authentication callbacks (Fragments, ViewModels).
– forgerock-auth: core authentication flows (network client, callback model, session manager, token manager).
– forgerock-authenticator: one-time password (TOTP/HOTP) and push-notification authenticator library.
– forgerock-core: shared low-level utilities—network interceptors, encryption, secure storage, key-store management.
– ping-protect: risk evaluation plugin module.
– forgerock-integration-tests: instrumentation tests against real or mocked services.
- Config and buildSrc directories contain Gradle plugin code, common build scripts, CI/CD configuration, and publishing logic.

##### README for Technical Stack and Use Cases
- Kotlin + Java libraries
- Gradle Kotlin DSL builds
- Android min API 23+
- Uses OkHttp for HTTP, Jetpack Compose (in e2e), AndroidX libraries
- Callback-driven auth tree traversal via REST calls to ForgeRock AM or Ping Cloud

##### Main Components and Their Relationships
a. Sample App (e2e/app)
– UI layer: Activities + Compose navigation + ViewModels
– Depends on: forgerock-auth-ui + forgerock-auth + forgerock-core
b. forgerock-auth-ui
– Android Fragments & Dialogs for each Callback type
– Publishes callback results to ViewModels
– Depends on: forgerock-auth (to request next node), forgerock-core (for interceptors)
c. forgerock-auth
– AuthServiceClient: orchestrates callback requests/responses
– FRAuth, FRSession, TokenManager: handles login, refresh, single-sign-on
– Uses: OkHttp interceptors, JSON parsing, secure cookie/storage from forgerock-core
– Emits callback objects that forgerock-auth-ui consumes
d. forgerock-authenticator
– MechanismFactory, Push & OATH generators, notification handlers
– Integrated into forgerock-auth self-service flows for 2FA
e. ping-protect
– Risk evaluation callbacks plugged into auth tree
f. forgerock-core
– Networking: OkHttpClientProvider, interceptors (AccessTokenInterceptor, CookieInterceptor)
– Encryption & storage: EncryptedSharedPreferences, KeyStoreManager
– Utility: Logger, JSON extensions, Supplier/Listener patterns
g. External Systems
– ForgeRock Identity Platform (Ping Cloud / PingAM REST API)
– Third-party Identity Providers (Google, Facebook, Apple)
– WebAuthn & device binding backends

##### Data Flow / Interaction Paths
- UI → Auth-UI fragments → forgerock-auth AuthServiceClient → HTTP → Identity Platform
- Responses (Callback tree) flow back through interceptors → AuthServiceClient → Auth-UI → UI
- Token and session state stored via forgerock-core secure storage
- 2FA (OATH/Push) flows triggered by forgerock-authenticator plugged into forgerock-auth self-service calls

##### Architectural Patterns & Principles
- Layered modularization: UI layer, domain/auth logic layer, core infrastructure layer
- Dependency injection by Gradle modules: core has zero upstream deps; auth depends on core; auth-UI depends on auth; sample depends on all
- Callback pipeline: tree of Callback objects serialized ↔ deserialized as JSON
- Interceptor pattern: OkHttp interceptors handle token injection, cookie marshalling
- Observer pattern: FRListener / SingleLiveEvent for asynchronous events

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Sample App Module
    subgraph "Sample App" 
        direction TB
        AppUI["Activities & Compose Navigation"]:::ui
        AppVM["ViewModels"]:::ui
    end
    click AppUI "https://github.com/forgerock/forgerock-android-sdk/tree/develop/e2e/app"
    click AppVM "https://github.com/forgerock/forgerock-android-sdk/tree/develop/e2e/app"

    %% Auth UI Module
    subgraph "Auth UI Module" 
        direction TB
        Fragments["Fragments & Dialogs"]:::ui
        AuthUIMV["ViewModels"]:::ui
    end
    click Fragments "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-auth-ui"
    click AuthUIMV "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-auth-ui"

    %% Core Auth Logic Module
    subgraph "Core Auth Module"
        direction TB
        AuthService["AuthServiceClient"]:::domain
        FRSession["FRSession & TokenManager"]:::domain
        CallbackModel["Callback Model"]:::domain
    end
    click AuthService "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-auth"
    click FRSession "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-auth"
    click CallbackModel "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-auth"

    %% 2FA Authenticator Module
    subgraph "2FA Authenticator"
        direction TB
        MechanismFactory["MechanismFactory"]:::domain
        OTPGenerators["OATH/TOTP Generators"]:::domain
        PushHandler["Push Notification Handler"]:::domain
    end
    click MechanismFactory "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-authenticator"
    click OTPGenerators "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-authenticator"
    click PushHandler "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-authenticator"

    %% Risk Evaluation Plugin
    subgraph "Risk Plugin"
        direction TB
        RiskCallback["Risk Evaluation Callbacks"]:::domain
    end
    click RiskCallback "https://github.com/forgerock/forgerock-android-sdk/tree/develop/ping-protect"

    %% Core Infrastructure Module
    subgraph "Core Infrastructure"
        direction TB
        HTTPProvider["OkHttpClientProvider & Interceptors"]:::infra
        SecureStorage["EncryptedSharedPreferences & KeyStore"]:::infra
        Utilities["Logger & JSON Utilities"]:::infra
    end
    click HTTPProvider "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-core"
    click SecureStorage "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-core"
    click Utilities "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-core"

    %% Integration Tests Module
    subgraph "Integration Tests"
        direction TB
        Tests["Instrumentation Tests"]:::infra
    end
    click Tests "https://github.com/forgerock/forgerock-android-sdk/tree/develop/forgerock-integration-tests"

    %% Build and Config
    subgraph "Build & Config"
        direction TB
        BuildSrc["Custom Gradle Plugins"]:::infra
        ConfigScripts["config/*.gradle"]:::infra
        CIWorkflows[".github/workflows"]:::infra
        ProjectSettings["settings.gradle.kts & gradle/libs.versions.toml & build.gradle.kts & gradle.properties"]:::infra
    end
    click BuildSrc "https://github.com/forgerock/forgerock-android-sdk/tree/develop/buildSrc"
    click ConfigScripts "https://github.com/forgerock/forgerock-android-sdk/tree/develop/config"
    click CIWorkflows "https://github.com/forgerock/forgerock-android-sdk/tree/develop/.github/workflows"
    click ProjectSettings "https://github.com/forgerock/forgerock-android-sdk/blob/develop/settings.gradle.kts"
    click ProjectSettings "https://github.com/forgerock/forgerock-android-sdk/blob/develop/gradle/libs.versions.toml"
    click ProjectSettings "https://github.com/forgerock/forgerock-android-sdk/blob/develop/build.gradle.kts"
    click ProjectSettings "https://github.com/forgerock/forgerock-android-sdk/blob/develop/gradle.properties"

    %% External Systems
    subgraph "External Systems"
        direction TB
        IdentityPlatform["ForgeRock Identity Platform\n(PingAM / Ping Cloud REST API)"]:::external
        IdP["Third-Party IdPs\n(Google, Facebook, Apple)"]:::external
        WebAuthn["WebAuthn & Device Binding Backend"]:::external
    end

    %% Dependencies (compile-time)
    AppUI -->|"uses Auth UI UI components"| Fragments
    AppVM -->|"depends on Core Auth"| AuthService
    AppVM -->|"depends on Core Infrastructure"| HTTPProvider

    Fragments -->|"calls Auth Service APIs"| AuthService
    Fragments -->|"uses interceptors"| HTTPProvider

    AuthService -->|"uses Secure Storage & Interceptors"| HTTPProvider
    AuthService -->|"emits Callback tree"| CallbackModel
    FRSession -->|"stores tokens in"| SecureStorage
    CallbackModel -->|"consumed by"| Fragments

    AuthService -->|"plugs in 2FA flows"| MechanismFactory
    AuthService -->|"plugs in risk plugin"| RiskCallback

    %% Runtime calls
    AuthService -->|"REST/JSON over HTTPS"| IdentityPlatform
    IdentityPlatform -.->|"Callback tree responses"| AuthService

    AuthService -->|"redirects to IdP via OAuth"| IdP
    AuthService -->|"WebAuthn flows"| WebAuthn

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef domain fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef infra fill:#E0E0E0,stroke:#424242,color:#424242
    classDef external fill:#FFCDD2,stroke:#B71C1C,color:#B71C1C
```
