# okta/okta-mobile-kotlin architecture

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

- Interactive diagram: https://gitdiagram.com/okta/okta-mobile-kotlin
- Repository: https://github.com/okta/okta-mobile-kotlin

## Overview

##### Project Type & Purpose
- This is an Android SDK that provides modularized authentication flows. It is composed of multiple libraries ( AuthFoundation, OAuth2, and WebAuthenticationUI) that together offer mechanisms to mint, manage, and exchange tokens in various OAuth flows. There are also additional samples (for device authorization, legacy migration, session token, etc.) that show practical integrations.
- The README clearly describes the SDK’s purpose to simplify authentication (using OAuth2, token storage, and web-based OIDC flows) for Android apps while supporting new use cases (like token exchange and device authorization).

##### Overall Modular Structure (Nodes/Components)
- Client Application/Sample Layer:
– Contains sample apps (e.g., “app”, “session-token-sample”, “legacy-token-migration-sample”, “web-authentication-ui”) that demonstrate how to integrate the underlying SDK libraries.
– Typically uses activities, fragments, and view models (evident in the “app” module with MainActivity, various fragments, and corresponding view model classes) which adopt MVVM or similar architectural patterns.
- SDK Core Libraries:
– AuthFoundation Module: Acts as the foundation for token management, encryption (including biometric support), credential storage, and common services. It includes configuration files, schemas, and utility classes.
– OAuth2 Module: Implements the OAuth flows needed (authorization code, device authorization, token exchange, etc.). It manages the network calls (using OkHttp), token validation and device authorization flows.
– WebAuthenticationUI Module: Provides a ready-to-use UI layer for web-based authentication. It uses web view components (Chrome Custom Tabs) and coordinates redirection and browser logout flows.
- Supporting and Ancillary Components:
– Legacy migration modules (legacy-token-migration and legacy-token-migration-sample) that show how to migrate tokens from the legacy system.
– Test-helpers, sample scripts, GitHub workflows, and documentation files that support build, testing, and CI/CD.
– Configuration and integration points (like the “bom” module for Bill Of Materials, and gradle files for dependency management).

##### Relationships and Data Flow
- The sample applications instantiate the SDK by initializing the AuthFoundation in the Android context and configuring the default OIDC settings.
- The main authentication flows (via OAuth2 and WebAuthenticationUI) are invoked by the client app. For example, user actions trigger:
∘ WebAuthentication → Initiates a browser flow (via Chrome Custom Tabs).
∘ TokenExchangeFlow and DeviceAuthorizationFlow → For exchanging tokens or handling limited-input devices.
- Upon success, credentials (managed by AuthFoundation) are stored securely (with support for biometric encryption) and later used to validate or refresh tokens.
- Network calls are made using OkHttp under the hood and are possibly customized via interceptors or custom Call.Factory implementations.
- Components interact primarily through clear API boundaries: the SDK exposes flows (like login, logout, token refresh) that a client application uses; in turn, the SDK communicates with external authorization servers (Okta endpoints).

##### Design Patterns & Architectural Principles
- A modular, layered architecture where each module’s responsibilities are clearly separated.
- Usage of MVVM patterns in sample apps (with Fragments, ViewModels, and helper classes).
- Emphasis on asynchronous processing with Kotlin Coroutines to offload network IO and compute work from the main thread.
- Separation of concerns: UI interactions (WebAuthenticationUI) are kept distinct from token management (AuthFoundation) and networking (OAuth2).
- Security by design: Supporting encryption, biometric authentication, and automatic migration of token storage to ensure secure handling of credentials.

##### Key Technologies/Frameworks
- Kotlin, including its coroutine framework.
- Android’s component model (Activities, Fragments, and related XML resources).
- OkHttp for networking.
- Android’s BiometricPrompt and encryption APIs.
- Gradle for build scripts and BOM for version alignment.

- Data flow: Initialization → Authentication flow (via browser or device auth) → Token issuance → Credential storage → Subsequent API calls.
- Distinguish between synchronous API calls and asynchronous/suspend functions (noting the use of Coroutines).
- Migration pathways for legacy tokens and how the migration modules interact with the main SDK.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application/Sample Layer
    subgraph "Client Application/Sample Layer"
        A["Sample App (app)"]:::client
        B["Legacy Token Migration Sample"]:::client
        C["Session Token Sample"]:::client
    end

    %% SDK Core Libraries
    subgraph "SDK Core Libraries"
        D["AuthFoundation – Credential & Token Storage Manager"]:::sdk
        E["OAuth2 – Token Flow Manager"]:::sdk
        F["WebAuthenticationUI – Web-based Authentication UI"]:::sdk
    end

    %% Supporting and Ancillary Components
    subgraph "Supporting and Ancillary Components"
        G["Legacy Migration – Legacy Token Migration"]:::support
        H["BOM – Configuration Manager"]:::support
        I["Test Helpers – Testing Utilities"]:::support
    end

    %% External Services
    subgraph "External Services"
        J["Okta Authorization Server"]:::external
    end

    %% Relationships: Client initializing SDK & invoking flows
    A -->|"initializes"| D
    B -->|"initializes"| D
    C -->|"initializes"| D

    A -->|"triggers_OAuth_flow"| E
    A -->|"triggers_Web_flow"| F

    %% SDK modules interacting with External Services
    E -->|"calls"| J
    F -->|"calls"| J
    J -->|"responds_to"| E
    J -->|"responds_to"| F

    %% SDK modules storing tokens
    E -->|"delivers_token"| D
    F -->|"delivers_token"| D

    %% Legacy Migration flows
    G -->|"migrates_tokens_to"| D

    %% BOM configuration supporting SDK modules
    H -->|"configures"| D
    H -->|"configures"| E
    H -->|"configures"| F

    %% Test Helpers support
    I -->|"supports_testing_of"| D
    I -->|"supports_testing_of"| E
    I -->|"supports_testing_of"| F

    %% Click Events for Client Application/Sample Layer
    click A "https://github.com/okta/okta-mobile-kotlin/tree/master/app"
    click B "https://github.com/okta/okta-mobile-kotlin/tree/master/legacy-token-migration-sample"
    click C "https://github.com/okta/okta-mobile-kotlin/tree/master/session-token-sample"

    %% Click Events for SDK Core Libraries
    click D "https://github.com/okta/okta-mobile-kotlin/tree/master/auth-foundation"
    click E "https://github.com/okta/okta-mobile-kotlin/tree/master/oauth2"
    click F "https://github.com/okta/okta-mobile-kotlin/tree/master/web-authentication-ui"

    %% Click Events for Supporting and Ancillary Components
    click G "https://github.com/okta/okta-mobile-kotlin/tree/master/legacy-token-migration"
    click H "https://github.com/okta/okta-mobile-kotlin/tree/master/bom"
    click I "https://github.com/okta/okta-mobile-kotlin/tree/master/test-helpers"

    %% Styles
    classDef client fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef sdk fill:#f8bbd0,stroke:#ad1457,stroke-width:2px;
    classDef support fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef external fill:#ffcdd2,stroke:#d32f2f,stroke-width:2px;
```
