# shinhyo/signin-with-apple architecture

> Architecture diagram of the GitHub repository shinhyo/signin-with-apple, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shinhyo/signin-with-apple
- Repository: https://github.com/shinhyo/signin-with-apple

## Overview

##### Project Type and Purpose
- This is an Android-centric multi-module library project (“sdk-signin-apple”) with a sample application (“sample”) demonstrating how to integrate Apple Sign-In in an Android app. It also includes “build-logic,” a Gradle convention-plugin module for shared build settings, and CI/CD workflows for publishing (via JitPack) and quality checks.

##### Main Components
a. **Build System & CI/CD**
- Gradle multi-project build
- Custom plugins in `build-logic`
- GitHub Actions workflows (`.github/workflows/ci.yml` and `cd.yml`)
- JitPack (artifact repository)
b. **Runtime Modules**
1. **Sample App** (`sample` module)
- UI layers (View system & Compose)
- Invokes the SignInWithApple SDK
2. **SignInWithApple SDK** (`sdk-signin-apple` module)
- Core OAuth/WebView flow
- State & nonce generation/validation
- JWT parsing
3. **Android WebView**
- Renders Apple’s OAuth pages
4. **External Apple ID Server**
- Authorizes the user, returns JWT (identity token) & authorization code
5. **Your Backend** (customer’s server)
- Verifies Apple’s JWT signature & nonce
- Exchanges authorization code for tokens
- Manages sessions/auth state

##### Relationships & Data Flows
- **Build & Release Flow**
- Developer → Gradle (using `build-logic`) → compile `sdk-signin-apple` & `sample`
- GitHub Actions → Run tests (`sdk-signin-apple/src/test`) → Publish SDK to JitPack
1. Sample App calls `SignInWithApple.init(...)` and `signIn(context, nonce)`
2. SDK generates state & nonce, then opens Android WebView with Apple OAuth URL
3. User authenticates on Apple ID Server page → Apple returns JWT + code to WebView
4. WebView redirects back into SDK → SDK validates state, extracts `identityToken`
5. SDK delivers `AppleIdCredential` (JWT) to the App via callback
6. App sends JWT to Your Backend
7. Backend verifies signature & nonce with Apple ID Server, exchanges code for tokens
8. Backend responds to App with session/auth success

##### Architectural Patterns & Principles
- **Modularization**: Clear separation between build logic (`build-logic`), core library (`sdk-signin-apple`), and consumer app (`sample`).
- **Separation of Concerns**:
- UI concerns in `sample` module (Activities, Compose)
- OAuth logic & security in `sdk-signin-apple`
- **Plugin-based Build**: Shared conventions for Android Compose, Hilt, Kotlin, code coverage via custom Gradle scripts.
- **Secure OAuth Flow**: Nonce & state for CSRF protection, server-side JWT verification.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "Developer & CI/CD" 
        direction TB
        Dev["Developer"]:::actor
        GitHubActions["GitHub Actions"]:::ci
        Dev -->|push code| GitHubActions
        GitHubActions -->|run tests & publish| JitPack["JitPack"]:::external
    end

    subgraph "Build System" 
        direction TB
        subgraph "Root Config"
            direction TB
            BG["build.gradle.kts"]:::build
            SG["settings.gradle.kts"]:::build
            GP["gradle.properties"]:::build
            LV["gradle/libs.versions.toml"]:::build
            GW["gradle/wrapper/gradle-wrapper.properties"]:::build
        end
        subgraph "Convention Plugin (build-logic)" 
            direction TB
            BL["build-logic/convention"]:::build
        end
        BL -->|provides| BG
    end

    subgraph "Runtime (Android App)" 
        direction TB
        subgraph "Sample App (sample)" 
            direction TB
            SB["sample/build.gradle.kts"]:::module
            MA["MainActivity.kt"]:::module
            CA["ComposeActivity.kt"]:::module
            AV["AndroidViewActivity.kt"]:::module
            SA["SampleApp.kt"]:::module
            SB --> MA
            SB --> CA
            SB --> AV
            SB --> SA
        end

        subgraph "SDK (sdk-signin-apple)" 
            direction TB
            SDKB["sdk-signin-apple/build.gradle.kts"]:::module
            API["SignInWithApple.kt"]:::module
            WVAct["AppleSignInWebViewActivity.kt"]:::module
            WVVM["AppleSignInWebViewViewModel.kt"]:::module
            Layout["activity_apple_sign_in_webview.xml"]:::module
            SDKB --> API
            API --> WVAct
            WVAct --> WVVM
            WVAct --> Layout
            subgraph "Tests"
                direction TB
                T1["SignInWithAppleTest.kt"]:::test
                T2["SignInWithAppleIntegrationTest.kt"]:::test
                T3["AppleSignInWebViewViewModelTest.kt"]:::test
            end
            SDKB --> T1
            SDKB --> T2
            SDKB --> T3
        end
    end

    subgraph "External Services" 
        direction TB
        Apple["Apple ID Server"]:::external
        Backend["Customer Backend"]:::external
    end

    %% Runtime Flow
    MA -->|calls init & signIn| API
    API -->|generate state/nonce| WVAct
    WVAct -->|load OAuth URL| Apple
    Apple -->|JWT + code| WVAct
    WVAct -->|validate state & extract token| API
    API -->|callback with AppleIdCredential| MA
    MA -->|send JWT| Backend
    Backend -->|verify & exchange code| Apple
    Backend -->|session success| MA

    %% Build Flow
    Dev -->|gradle build| BG
    Dev -->|gradle build| SB
    GitHubActions -->|run tests in SDK| T1
    GitHubActions -->|run tests in SDK| T2
    GitHubActions -->|run tests in SDK| T3

    %% Publishing
    GitHubActions -->|publish| JitPack

    %% Click Events
    click BG "https://github.com/shinhyo/signin-with-apple/blob/develop/build.gradle.kts"
    click SG "https://github.com/shinhyo/signin-with-apple/blob/develop/settings.gradle.kts"
    click GP "https://github.com/shinhyo/signin-with-apple/blob/develop/gradle.properties"
    click LV "https://github.com/shinhyo/signin-with-apple/blob/develop/gradle/libs.versions.toml"
    click GW "https://github.com/shinhyo/signin-with-apple/blob/develop/gradle/wrapper/gradle-wrapper.properties"
    click BL "https://github.com/shinhyo/signin-with-apple/tree/develop/build-logic/convention/"
    click GitHubActions "https://github.com/shinhyo/signin-with-apple/blob/develop/.github/workflows/ci.yml"
    click GitHubActions "https://github.com/shinhyo/signin-with-apple/blob/develop/.github/workflows/cd.yml"
    click JitPack "https://github.com/shinhyo/signin-with-apple/blob/develop/jitpack.yml"
    click SB "https://github.com/shinhyo/signin-with-apple/blob/develop/sample/build.gradle.kts"
    click MA "https://github.com/shinhyo/signin-with-apple/blob/develop/sample/src/main/java/io/github/shinhyo/signinwithapple/sample/MainActivity.kt"
    click CA "https://github.com/shinhyo/signin-with-apple/blob/develop/sample/src/main/java/io/github/shinhyo/signinwithapple/sample/ComposeActivity.kt"
    click AV "https://github.com/shinhyo/signin-with-apple/blob/develop/sample/src/main/java/io/github/shinhyo/signinwithapple/sample/AndroidViewActivity.kt"
    click SA "https://github.com/shinhyo/signin-with-apple/blob/develop/sample/src/main/java/io/github/shinhyo/signinwithapple/sample/SampleApp.kt"
    click SDKB "https://github.com/shinhyo/signin-with-apple/blob/develop/sdk-signin-apple/build.gradle.kts"
    click API "https://github.com/shinhyo/signin-with-apple/blob/develop/sdk-signin-apple/src/main/java/io/github/shinhyo/signinwithapple/SignInWithApple.kt"
    click WVAct "https://github.com/shinhyo/signin-with-apple/blob/develop/sdk-signin-apple/src/main/java/io/github/shinhyo/signinwithapple/AppleSignInWebViewActivity.kt"
    click WVVM "https://github.com/shinhyo/signin-with-apple/blob/develop/sdk-signin-apple/src/main/java/io/github/shinhyo/signinwithapple/AppleSignInWebViewViewModel.kt"
    click Layout "https://github.com/shinhyo/signin-with-apple/blob/develop/sdk-signin-apple/src/main/res/layout/activity_apple_sign_in_webview.xml"
    click T1 "https://github.com/shinhyo/signin-with-apple/blob/develop/sdk-signin-apple/src/test/java/io/github/shinhyo/signinwithapple/SignInWithAppleTest.kt"
    click T2 "https://github.com/shinhyo/signin-with-apple/blob/develop/sdk-signin-apple/src/test/java/io/github/shinhyo/signinwithapple/SignInWithAppleIntegrationTest.kt"
    click T3 "https://github.com/shinhyo/signin-with-apple/blob/develop/sdk-signin-apple/src/test/java/io/github/shinhyo/signinwithapple/AppleSignInWebViewViewModelTest.kt"

    %% Styles
    classDef build fill:#f9f,stroke:#333,stroke-width:1px
    classDef module fill:#bbf,stroke:#333,stroke-width:1px
    classDef test fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ffa,stroke:#333,stroke-width:1px
    classDef ci fill:#fcf,stroke:#333,stroke-width:1px
    classDef actor fill:#cff,stroke:#333,stroke-width:1px
```
