# yuyakaido/cardstackview architecture

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

- Interactive diagram: https://gitdiagram.com/yuyakaido/cardstackview
- Repository: https://github.com/yuyakaido/cardstackview

## Overview

##### Project type and purpose
- This is an Android UI component library (“cardstackview”) complemented by a sample Android app module.
- The library provides a highly customizable, swipeable card stack (built on RecyclerView), and the sample app demonstrates usage, configuration, and API callbacks.

##### File structure
Top-level:
- .circleci/config.yml – CI pipeline for build + tests
- gradle.properties, settings.gradle, gradle/… – Gradle build system + wrapper
- build.gradle – root build configuration
- cardstackview/ – library module
– src/main/java/com/yuyakaido/android/cardstackview/
- CardStackView (RecyclerView subclass)
- CardStackLayoutManager (custom LayoutManager)
- CardStackListener (callback interface)
- Direction, Duration, SwipeAnimationSetting.Builder, RewindAnimationSetting.Builder, etc.
– src/main/java/com/yuyakaido/android/cardstackview/internal/
- AnimationSetting, CardStackState, CardStackSmoothScroller, SnapHelper, DataObserver, DisplayUtil
– src/main/res/layout, overlay.xml – resource definitions
- sample/ – demo Android app module
– MainActivity.kt – initializes CardStackView
– CardStackAdapter.kt (RecyclerView.Adapter)
– Spot.kt & SpotDiffCallback.kt – data model + DiffUtil for paging
– res/layout, drawables, menu, mipmap – UI layouts & assets

##### README for insights
- Describes features (manual swipe, automatic swipe, rewind, overlays, paging, stack-from, thresholds, directions)
- Shows public interfaces & callbacks
- Emphasizes integration code snippets (Kotlin)
- Calls out migration from v1.x → v2.x

##### Components & interactions
- Developer Workflow & CI
– GitHub repo → CircleCI pipeline → build & test → publish artifact
– Gradle wrapper & settings drive build
- Library Module (“cardstackview”)
– CardStackView (UI component)
– CardStackLayoutManager (positioning & swipe logic)
– AnimationSetting (Swipe, Rewind builders)
– CardStackListener (event callbacks)
– Internal utilities (State, Scroller, SnapHelper, DisplayUtil, DataObserver)
– Resources (layouts, overlay XMLs)
– API boundary: public classes & methods
- Android Framework
– RecyclerView base class
– LayoutManager interface
– Adapter / DiffUtil
– Interpolator, View, FrameLayout (overlays)
- Sample App
– MainActivity (sets up CardStackView + LayoutManager + Listener)
– CardStackAdapter (binds Spot data to item_spot.xml)
– Spot model + DiffCallback (paging)

1. Developer → Git push → CI → Gradle build → library + sample
2. Sample App module depends on library module (compile-time)
3. At runtime: User swipe gesture → CardStackView → CardStackLayoutManager → AnimationSetting/InternalState
4. LayoutManager invokes internal Scroller & SnapHelper to animate view
5. CardStackListener callbacks propagate to MainActivity
6. Adapter updates via notifyItemRangeInserted or DiffUtil → DataObserver → UI refresh

c. Architectural patterns & design principles
- Adapter pattern (RecyclerView.Adapter for data binding)
- Builder pattern (SwipeAnimationSetting.Builder, RewindAnimationSetting.Builder)
- Observer pattern (CardStackDataObserver monitors adapter changes)
- Single Responsibility (separate classes for layout, state, animation, callbacks)
- Modularity (core library vs sample app)

d. Key technologies, frameworks, libraries
- Language: Java (library), Kotlin (sample)
- Build: Gradle (multi-module), CircleCI
- Android SDK: RecyclerView, LayoutManager, Interpolator, FrameLayout
- Testing/CI: CircleCI config (build/test pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workflow & CI
    subgraph "Developer Workflow & CI"
        direction TB
        Repo(("GitHub Repository")):::ci
        CircleCI["CircleCI Pipeline"]:::ci
        GradleWrapper["Gradle Wrapper & Properties"]:::ci
        RootBuild["Root Build Config"]:::ci
        CIConfig[".circleci/config.yml"]:::ci
        Settings["settings.gradle"]:::ci
        RootBuildFile["build.gradle"]:::ci

        Repo -->|push| CircleCI
        CircleCI -->|reads| CIConfig
        CircleCI -->|reads| Settings
        CircleCI -->|reads| RootBuildFile
        CircleCI -->|executes| GradleWrapper
    end

    %% Library Module
    subgraph "Library Module: cardstackview"
        direction TB
        LibBuild["cardstackview/build.gradle"]:::library

        subgraph "Public API"
            direction TB
            CSV["CardStackView"]:::library
            CSLM["CardStackLayoutManager"]:::library
            CSLsn["CardStackListener"]:::library
            Dir["Direction"]:::library
            Dur["Duration"]:::library
            SAS["SwipeAnimationSetting (Builder)"]:::library
            RAS["RewindAnimationSetting (Builder)"]:::library
            SF["StackFrom"]:::library
            SM["SwipeableMethod"]:::library
        end

        subgraph "Internal Utilities"
            direction TB
            AnimSet["AnimationSetting"]:::library
            State["CardStackState"]:::library
            Scroller["CardStackSmoothScroller"]:::library
            Snap["CardStackSnapHelper"]:::library
            Observer["CardStackDataObserver"]:::library
            Setting["CardStackSetting"]:::library
            Display["DisplayUtil"]:::library
        end

        subgraph "Resources"
            direction TB
            Overlay["overlay.xml"]:::library
        end

        LibBuild --> CSV
        LibBuild --> CSLM
        LibBuild --> CSLsn
        CSV -->|uses| CSLM
        CSLM -->|uses| AnimSet
        CSLM -->|uses| Scroller
        CSLM -->|uses| Snap
        AnimSet --> State
        Observer --> CSV
        CSV --> Overlay
    end

    %% Android Framework
    subgraph "Android Framework"
        direction TB
        RecyclerView["RecyclerView"]:::framework
        LayoutMgrIF["LayoutManager Interface"]:::framework
        AdapterDiff["Adapter / DiffUtil"]:::framework
        Interpolator["Interpolator"]:::framework
        View["View"]:::framework
        FrameLayout["FrameLayout (Overlay)"]:::framework
    end

    %% Sample App Module
    subgraph "Sample App Module: sample"
        direction TB
        SampleBuild["sample/build.gradle"]:::sample
        MainAct["MainActivity"]:::sample
        Adapter["CardStackAdapter"]:::sample
        SpotModel["Spot"]:::sample
        SpotDiff["SpotDiffCallback"]:::sample
        ActivityLayout["activity_main.xml"]:::sample
        ItemLayout["item_spot.xml"]:::sample
        Drawables["Drawable Resources"]:::sample
        MenuRes["navigation_main_activity.xml"]:::sample
        Mipmap["Mipmap Icons"]:::sample
        Values["strings.xml"]:::sample

        SampleBuild --> MainAct
        SampleBuild --> Adapter
        MainAct --> CSV
        MainAct --> CSLsn
        Adapter --> SpotModel
        Adapter --> SpotDiff
        MainAct --> ActivityLayout
        Adapter --> ItemLayout
        MainAct --> Drawables
        MainAct --> MenuRes
        MainAct --> Mipmap
        MainAct --> Values
        SampleBuild -->|compile-depends| LibBuild
    end

    %% Runtime Flow
    User["User"]:::external
    User -->|swipe gesture| CSV
    CSV -->|delegates| CSLM
    CSLM -->|applies| AnimSet
    AnimSet -->|updates| State
    State -->|drives| Scroller
    Scroller -->|animates| CSV
    Snap -->|snaps view| CSV
    CSV -->|callback| CSLsn
    CSLsn -->|invokes| MainAct
    Adapter -->|notifyItemRangeInserted| Observer
    Observer -->|refresh| CSV

    %% Framework Links
    CSV -->|extends| RecyclerView
    CSLM -->|implements| LayoutMgrIF
    Adapter -->|extends| AdapterDiff
    AnimSet -->|uses| Interpolator
    Overlay -->|uses| FrameLayout

    %% Click Events
    click CIConfig "https://github.com/yuyakaido/cardstackview/blob/master/.circleci/config.yml"
    click Settings "https://github.com/yuyakaido/cardstackview/blob/master/settings.gradle"
    click RootBuildFile "https://github.com/yuyakaido/cardstackview/blob/master/build.gradle"
    click GradleWrapper "https://github.com/yuyakaido/cardstackview/tree/master/gradle/wrapper"
    click LibBuild "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/build.gradle"
    click CSV "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/CardStackView.java"
    click CSLM "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/CardStackLayoutManager.java"
    click CSLsn "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/CardStackListener.java"
    click Dir "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/Direction.java"
    click Dur "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/Duration.java"
    click SAS "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/SwipeAnimationSetting.java"
    click RAS "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/RewindAnimationSetting.java"
    click SF "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/StackFrom.java"
    click SM "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/SwipeableMethod.java"
    click AnimSet "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/internal/AnimationSetting.java"
    click State "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/internal/CardStackState.java"
    click Scroller "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/internal/CardStackSmoothScroller.java"
    click Snap "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/internal/CardStackSnapHelper.java"
    click Observer "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/internal/CardStackDataObserver.java"
    click Setting "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/internal/CardStackSetting.java"
    click Display "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/java/com/yuyakaido/android/cardstackview/internal/DisplayUtil.java"
    click Overlay "https://github.com/yuyakaido/cardstackview/blob/master/cardstackview/src/main/res/layout/overlay.xml"
    click SampleBuild "https://github.com/yuyakaido/cardstackview/blob/master/sample/build.gradle"
    click MainAct "https://github.com/yuyakaido/cardstackview/blob/master/sample/src/main/java/com/yuyakaido/android/cardstackview/sample/MainActivity.kt"
    click Adapter "https://github.com/yuyakaido/cardstackview/blob/master/sample/src/main/java/com/yuyakaido/android/cardstackview/sample/CardStackAdapter.kt"
    click SpotModel "https://github.com/yuyakaido/cardstackview/blob/master/sample/src/main/java/com/yuyakaido/android/cardstackview/sample/Spot.kt"
    click SpotDiff "https://github.com/yuyakaido/cardstackview/blob/master/sample/src/main/java/com/yuyakaido/android/cardstackview/sample/SpotDiffCallback.kt"
    click ActivityLayout "https://github.com/yuyakaido/cardstackview/blob/master/sample/src/main/res/layout/activity_main.xml"
    click ItemLayout "https://github.com/yuyakaido/cardstackview/blob/master/sample/src/main/res/layout/item_spot.xml"
    click Drawables "https://github.com/yuyakaido/cardstackview/tree/master/sample/src/main/res/drawable"
    click MenuRes "https://github.com/yuyakaido/cardstackview/blob/master/sample/src/main/res/menu/navigation_main_activity.xml"
    click Mipmap "https://github.com/yuyakaido/cardstackview/tree/master/sample/src/main/res/mipmap"
    click Values "https://github.com/yuyakaido/cardstackview/blob/master/sample/src/main/res/values/strings.xml"

    %% Styles
    classDef ci fill:#dddddd,stroke:#888888,color:#333333
    classDef library fill:#bbdefb,stroke:#1976d2,color:#0d47a1
    classDef framework fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef sample fill:#fff9c4,stroke:#fbc02d,color:#f57f17
    classDef external fill:#eeeeee,stroke:#999999,color:#555555
    class User external
```
