# shopify/flash-list architecture

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

- Interactive diagram: https://gitdiagram.com/shopify/flash-list
- Repository: https://github.com/shopify/flash-list

## Overview

##### Project Type and Purpose
- This is a cross‑platform React Native library (“FlashList”) that provides a performant List component.
- It consists of:
- A JS/TS layer (`src/…`) exposing the `FlashList` API to React Native apps
- Native modules for Android (`android/src/...`) and iOS (`ios/Sources/...`)
- Example/demo apps under `fixture/`
- Documentation website under `documentation/` and `website/`
- CI/CD workflows in `.github/workflows/`

##### File Structure
- Top‑level directories:
- `src/`—core JS/TS implementation, utils, specs, benchmarks, tests
- `android/`—Kotlin/Java code for native view managers, bridge to JS
- `ios/`—Swift/Obj‑C code for native view managers, bridging header
- `fixture/`—sample React Native apps (Expo and bare RN) exercising the library
- `documentation/` & `website/`—Docusaurus site and static site
- `.github/workflows/`—build, test, deploy pipelines
- Config files: `package.json`, `babel.config.js`, `tsconfig.json`, `Gemfile` for docs

##### Key Components
a. JS Layer (FlashList package)
- API entry point (`FlashList.tsx`, `AnimatedFlashList.ts`, `MasonryFlashList.tsx`)
- Utilities, viewability manager, layout providers in `src/utils`, `src/viewability`
- Native component wrappers (`src/native/...`) forwarding props to native
- Tests (`src/__tests__`) and benchmarks (`src/benchmark`)
b. React Native Bridge
- Auto‑generated Paper bindings under `android/src/paper/java/...`
- NativeComponent specs in `src/specs/`
- Bridging code in iOS header (`FlatListPro‑Bridging‑Header.h`)
c. Android Native Module
- `AutoLayoutViewManager.kt`, `CellContainerManager.kt`, `FlashListPackage.kt`
- Event emitters (`BlankAreaEvent.kt`)
d. iOS Native Module
- `AutoLayoutViewManager.swift`, `CellContainerManager.swift`
- Component view classes (`ComponentView.h/.mm`)
e. Host App / Examples
- Expo and bare RN examples calling into `@shopify/flash-list`
f. Documentation Site
- Docusaurus config, Markdown docs, and static site deploy
g. CI/CD
- GitHub Actions: lint, test, build package, deploy website, release

##### Relationships and Data Flow
- Host React Native App → imports `@shopify/flash-list` → calls JS API
- JS API → NativeComponent wrappers → React Native Bridge
- Bridge → Android/iOS native managers → native views
- Native modules → emit layout/scroll events → JS viewability manager
- CI pipelines → two paths:
- Build & test JS + native code → publish npm & CocoaPods
- Build docs → deploy to GitHub Pages or Shopify site

##### Architectural Patterns and Principles
- Layered architecture: JS layer, bridge, native implementation
- Separation of concerns: rendering (native), business logic (JS), configuration
- Reusability: common `PlatformHelper` code, shared specs, component wrappers
- Test‑driven: Jest for JS, unit/instrumentation tests on native sides
- Documentation as code: Docusaurus site under version control

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host App / Examples
    subgraph "Host Apps & Examples"
        ExpoApp["Expo Sample App"]:::examples
        BareRNApp["Bare RN Sample App"]:::examples
    end

    %% JS/TS Layer
    subgraph "JS/TS Layer" 
        FL_TSX["FlashList.tsx"]:::js
        AFL["AnimatedFlashList.ts"]:::js
        MFL["MasonryFlashList.tsx"]:::js
        INDEX["index.ts"]:::js
        PROPS["FlashListProps.ts"]:::js
        Utils["utils/"]:::js
        Viewability["viewability/"]:::js
        NativeWrappers["native/"]:::js
        Tests["__tests__/"]:::js
        Benchmarks["benchmark/"]:::js
    end

    %% Bridge & Specs
    subgraph "React Native Bridge & Specs"
        AL_NC["AutoLayoutNativeComponent.ts"]:::js
        CC_NC["CellContainerNativeComponent.ts"]:::js
        Bridging_Header["FlatListPro-Bridging-Header.h"]:::js
        PaperViewmanagers["android/src/paper/java/..."]:::android
    end

    %% Native Modules
    subgraph "Android Native Module"
        AL_VMM["AutoLayoutViewManager.kt"]:::android
        CC_MM["CellContainerManager.kt"]:::android
        FL_PKG["FlashListPackage.kt"]:::android
        BA_Event["BlankAreaEvent.kt"]:::android
        AL_Shadow["AutoLayoutShadow.kt"]:::android
        CC_Impl["CellContainerImpl.kt"]:::android
    end

    subgraph "iOS Native Module"
        AL_VM_iOS["AutoLayoutViewManager.swift"]:::ios
        AL_ViewComp["AutoLayoutViewComponentView.h/.mm"]:::ios
        CC_Mgr_iOS["CellContainerManager.swift"]:::ios
        CC_ViewComp["CellContainerComponentView.h/.mm"]:::ios
        iOS_Tests["AutoLayoutViewTests.swift"]:::ios
    end

    %% Documentation Site
    subgraph "Documentation"
        Docusaurus["documentation/"]:::examples
        StaticSite["website/"]:::examples
    end

    %% CI/CD Workflows
    subgraph "CI/CD (GitHub Actions)"
        FlashListYml["flash-list.yml"]:::ci
        ReleaseYml["release.yml"]:::ci
        DeployWebsiteYml["deploy-website-on-main.yml"]:::ci
        WebsiteYml["website.yml"]:::ci
        CLA["cla.yml"]:::ci
    end

    Registry["npm & CocoaPods"]:::ci
    SiteDeploy["Site Deployment"]:::ci

    %% Data Flow
    ExpoApp -->|"imports"| FL_TSX
    BareRNApp -->|"imports"| FL_TSX

    FL_TSX -->|"calls API"| AL_NC
    AFL -->|"calls API"| AL_NC
    MFL -->|"calls API"| AL_NC
    NativeWrappers -->|"wraps props"| AL_NC

    AL_NC -->|"bridge to"| AL_VMM
    AL_NC -->|"bridge to"| AL_VM_iOS
    CC_NC -->|"bridge to"| CC_MM
    CC_NC -->|"bridge to"| CC_Mgr_iOS
    Bridging_Header -->|"iOS bridge"| AL_VM_iOS

    AL_VMM -->|"renders"| AndroidPaper
    CC_MM -->|"renders"| AndroidPaper
    AL_VM_iOS -->|"renders"| AL_ViewComp
    CC_Mgr_iOS -->|"renders"| CC_ViewComp

    AL_VMM -->|"events"| Viewability
    CC_MM -->|"events"| Viewability
    AL_VM_iOS -->|"events"| Viewability
    CC_Mgr_iOS -->|"events"| Viewability

    %% CI/CD Flow
    subgraph "Repository"
        Repo["FlashList Repo"]
    end
    Repo -->|"triggers"| FlashListYml
    Repo -->|"triggers"| ReleaseYml
    Repo -->|"triggers"| DeployWebsiteYml
    Repo -->|"triggers"| WebsiteYml
    Repo -->|"triggers"| CLA

    FlashListYml -->|"build & test"| Registry
    ReleaseYml -->|"publish"| Registry
    DeployWebsiteYml -->|"deploy docs"| SiteDeploy
    WebsiteYml -->|"build site"| SiteDeploy

    %% Documentation pipeline
    Docusaurus -->|"source for"| SiteDeploy
    StaticSite -->|"deployed at"| SiteDeploy

    %% Click Events
    click FL_TSX "https://github.com/shopify/flash-list/blob/main/src/FlashList.tsx"
    click AFL "https://github.com/shopify/flash-list/blob/main/src/AnimatedFlashList.ts"
    click MFL "https://github.com/shopify/flash-list/blob/main/src/MasonryFlashList.tsx"
    click PROPS "https://github.com/shopify/flash-list/blob/main/src/FlashListProps.ts"
    click INDEX "https://github.com/shopify/flash-list/blob/main/src/index.ts"
    click Utils "https://github.com/shopify/flash-list/tree/main/src/utils"
    click Viewability "https://github.com/shopify/flash-list/tree/main/src/viewability"
    click NativeWrappers "https://github.com/shopify/flash-list/tree/main/src/native"
    click Tests "https://github.com/shopify/flash-list/tree/main/src/__tests__"
    click Benchmarks "https://github.com/shopify/flash-list/tree/main/src/benchmark"
    click AL_NC "https://github.com/shopify/flash-list/blob/main/src/specs/AutoLayoutNativeComponent.ts"
    click CC_NC "https://github.com/shopify/flash-list/blob/main/src/specs/CellContainerNativeComponent.ts"
    click Bridging_Header "https://github.com/shopify/flash-list/blob/main/ios/Sources/FlatListPro-Bridging-Header.h"
    click PaperViewmanagers "https://github.com/shopify/flash-list/tree/main/android/src/paper/java/com/facebook/react/viewmanagers"
    click AL_VMM "https://github.com/shopify/flash-list/blob/main/android/src/main/kotlin/com/shopify/reactnative/flash_list/AutoLayoutViewManager.kt"
    click CC_MM "https://github.com/shopify/flash-list/blob/main/android/src/main/kotlin/com/shopify/reactnative/flash_list/CellContainerManager.kt"
    click FL_PKG "https://github.com/shopify/flash-list/blob/main/android/src/main/kotlin/com/shopify/reactnative/flash_list/FlashListPackage.kt"
    click BA_Event "https://github.com/shopify/flash-list/blob/main/android/src/main/kotlin/com/shopify/reactnative/flash_list/BlankAreaEvent.kt"
    click AL_Shadow "https://github.com/shopify/flash-list/blob/main/android/src/main/kotlin/com/shopify/reactnative/flash_list/AutoLayoutShadow.kt"
    click CC_Impl "https://github.com/shopify/flash-list/blob/main/android/src/main/kotlin/com/shopify/reactnative/flash_list/CellContainerImpl.kt"
    click AL_VM_iOS "https://github.com/shopify/flash-list/blob/main/ios/Sources/AutoLayoutViewManager.swift"
    click AL_ViewComp "https://github.com/shopify/flash-list/blob/main/ios/Sources/AutoLayoutViewComponentView.h"
    click CC_Mgr_iOS "https://github.com/shopify/flash-list/blob/main/ios/Sources/CellContainerManager.swift"
    click CC_ViewComp "https://github.com/shopify/flash-list/blob/main/ios/Sources/CellContainerComponentView.h"
    click iOS_Tests "https://github.com/shopify/flash-list/blob/main/ios/Tests/AutoLayoutViewTests.swift"
    click Docusaurus "https://github.com/shopify/flash-list/tree/main/documentation/"
    click StaticSite "https://github.com/shopify/flash-list/tree/main/website/"
    click FlashListYml "https://github.com/shopify/flash-list/blob/main/.github/workflows/flash-list.yml"
    click ReleaseYml "https://github.com/shopify/flash-list/blob/main/.github/workflows/release.yml"
    click DeployWebsiteYml "https://github.com/shopify/flash-list/blob/main/.github/workflows/deploy-website-on-main.yml"
    click WebsiteYml "https://github.com/shopify/flash-list/blob/main/.github/workflows/website.yml"
    click CLA "https://github.com/shopify/flash-list/blob/main/.github/workflows/cla.yml"

    %% Styles
    classDef js fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef android fill:#D0F0D0,stroke:#333,stroke-width:1px
    classDef ios fill:#F0E0FF,stroke:#333,stroke-width:1px
    classDef examples fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef ci fill:#FFE4B5,stroke:#333,stroke-width:1px
```
