shopify/flash-list

<explanation>

1. Identify 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/

2. Analyze 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

3. Key Components to Represent

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

4. 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

5. 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

6. Diagram Guidelines for This Full‑Stack Library

- Use distinct shapes/colors:

• Blue boxes for JS/TS layer

• Green boxes for Android native modules

• Purple boxes for iOS native modules

• Gray boxes for examples & docs

• Orange boxes for CI/CD

- Draw directional arrows:

• From Host App → JS API → Native wrappers → Bridge → Native managers

• From Native managers → Event callbacks → JS viewability

• From repo → CI workflows → npm/CocoaPods & website deployment

- Label each component:

• Include file paths or module names (e.g., AutoLayoutViewManager.kt, AutoLayoutViewManager.swift)

• Note external dependencies (React Native core, Docusaurus, fastlane/CocoaPods)

7. Tailoring to This Project

- Emphasize cross‑platform bridge: show parallel Android/iOS flows

- Highlight example fixtures to illustrate real‑world integration

- Show documentation pipeline separately—Docusaurus sources → static site

- Include release pipeline to npm & CocoaPods via GitHub Actions

8. Essential Diagram Elements Checklist

- Clear labels for:

• JS Source (src/)

• Native Modules (android/src/, ios/Sources/)

• Bridge & Spec definitions (src/specs/)

• Examples (fixture/)

• Documentation (documentation/, website/)

• CI Workflows (.github/workflows/)

- Arrows for:

• Data flow (App ➔ JS ➔ Native ➔ UI)

• Event flow (Native ➔ JS)

• CI build/deploy (Repo ➔ CI ➔ Registry & Website)

- Color/shape distinctions to group layers

By following these steps and using the components, interactions, and flows specific to the FlashList project, you’ll produce a detailed, accurate system design diagram that clearly communicates the architecture of this cross‑platform React Native library.

</explanation>