# instagram/iglistkit architecture

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

- Interactive diagram: https://gitdiagram.com/instagram/iglistkit
- Repository: https://github.com/instagram/iglistkit

## Overview

##### Project type and purpose
- IGListKit is an open-source, data-driven UICollectionView framework (iOS/tvOS/macOS) that decouples the diffing algorithm from UI, provides a reusable adapter/section-controller architecture, and ships with Swift interop and code-generation plugin support.
- Key indicators: README (“A data-driven UICollectionView framework…”), top-level folders: Source (core), Examples (sample apps), Tests, docs, remodel-plugin, scripts, spm, Podspecs, Package.swift.

##### File structure
- Top-level modules:
- Source/IGListDiffKit – pure Objective-C diffing engine
- Source/IGListKit – adapter + SectionController UI layer
- Source/IGListSwiftKit – Swift extensions on IGListKit
- remodel-plugin – a codegen plugin to mark models as IGListDiffable
- Examples – platform sample applications (iOS, macOS, tvOS) demonstrating IGListKit usage
- Tests – unit and integration tests for DiffKit, Kit, SwiftKit
- docs – generated API reference and guides
- scripts – build, docs generation, linting, versioning
- Package/Pod/Carthage manifests – integration points for SPM/CocoaPods/Carthage
- .github/workflows/CI.yml – CI pipeline

##### README for additional insights
- Project purpose: performant collection updates (batch updates), flexible multi-type collections, fully tested, extendable API.
- Architectural vision: “Never call performBatchUpdates or reloadData again,” “decoupled diffing algorithm,” “extendable API.”
- Installation via CocoaPods/Carthage/SPM.

##### Main components
a. IGListDiffKit (Diff Engine)
b. IGListKit (Adapter + UI Layer)
c. IGListSwiftKit (Swift API sugar)
d. Codegen Plugin (remodel-plugin)
e. Example Applications (iOS, macOS, tvOS)
f. Tests (unit/integration harness)
g. Documentation (docs)
h. Build & CI (scripts, GitHub Actions)
i. Package Managers (CocoaPods, Carthage, SPM manifests)

##### Relationships & interactions
- IGListKit → depends on → IGListDiffKit for diff computation
- IGListSwiftKit → extends → IGListKit
- remodel-plugin → generates → Swift/ObjC model code conforming to IGListDiffable
- Example apps → import → IGListKit (+ optionally SwiftKit + DiffKit)
- Tests → invoke → DiffKit / Kit / SwiftKit APIs
- scripts/CI → orchestrate → linting, building, docs generation, packaging
- Package manifests → expose → modules to consumer build tools (Pod, Carthage, SPM)

##### Architectural patterns & design principles
- Adapter pattern: IGListAdapter mediates between data objects and UICollectionView
- SectionController pattern: one controller per section type, encapsulating cell config & interaction
- Strategy/Decoupling: diffing algorithm isolated in IGListDiffKit
- Extension & plugin architecture: remodel-plugin for code generation, SwiftKit for language interop
- Modular design: clear folder separation (core, UI, Swift extensions, tooling)

##### Essential details to capture
- Module boundaries and dependencies (no code internals)
- Public API layers vs. internal components
- Extension points (protocols, plugins)
- Consumer surface (Example apps, Package managers)
- OSS pipeline (CI, docs, linting)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Modules
    subgraph "Core Modules"
        Diff["IGListDiffKit\n(Diff Engine)"]:::core
        Kit["IGListKit\n(Adapter + UI Layer)"]:::core
        SwiftKit["IGListSwiftKit\n(Swift API Extensions)"]:::core
    end

    %% Extensibility
    subgraph "Extensibility"
        Plugin["remodel-plugin\n(Codegen Plugin)"]:::plugin
    end

    %% Consumers
    subgraph "Consumers"
        Examples["Examples\n(iOS/macOS/tvOS samples)"]:::consumer
        Tests["Tests\n(Unit & Integration)"]:::consumer
    end

    %% Tooling & CI
    subgraph "Tooling & CI"
        Scripts["scripts\n(Build & Utility)"]:::tooling
        CI["CI Workflow\n(.github/workflows/CI.yml)"]:::tooling
        Docs["docs\n(API Reference & Guides)"]:::tooling
    end

    %% Packaging & Integration
    subgraph "Packaging & Integration"
        SPM["Package.swift\n+ spm/"]:::packaging
        CocoaPods["Podspecs & Podfile"]:::packaging
    end

    %% Dependencies
    Kit -->|"uses diff engine"| Diff
    SwiftKit -->|"extends API"| Kit
    Plugin -->|"generates IGListDiffable models"| Diff
    Plugin -->|"generates IGListDiffable models"| Kit
    Plugin -->|"generates IGListDiffable models"| SwiftKit
    Examples -->|"import & demo"| Kit
    Examples -->|"import & demo"| SwiftKit
    Examples -->|"import & demo"| Diff
    Tests -->|"tests APIs"| Diff
    Tests -->|"tests APIs"| Kit
    Tests -->|"tests APIs"| SwiftKit
    Scripts -->|"orchestrates"| CI
    CI -->|"runs scripts"| Scripts
    Scripts -->|"generates docs"| Docs
    SPM -->|"exposes modules"| Diff
    SPM -->|"exposes modules"| Kit
    SPM -->|"exposes modules"| SwiftKit
    CocoaPods -->|"exposes modules"| Diff
    CocoaPods -->|"exposes modules"| Kit
    CocoaPods -->|"exposes modules"| SwiftKit

    %% Click Events
    click Diff "https://github.com/instagram/iglistkit/tree/main/Source/IGListDiffKit"
    click Kit "https://github.com/instagram/iglistkit/tree/main/Source/IGListKit"
    click SwiftKit "https://github.com/instagram/iglistkit/tree/main/Source/IGListSwiftKit"
    click Plugin "https://github.com/instagram/iglistkit/tree/main/remodel-plugin"
    click Examples "https://github.com/instagram/iglistkit/tree/main/Examples/"
    click Tests "https://github.com/instagram/iglistkit/tree/main/Tests/"
    click Docs "https://github.com/instagram/iglistkit/tree/main/docs/"
    click Scripts "https://github.com/instagram/iglistkit/tree/main/scripts/"
    click CI "https://github.com/instagram/iglistkit/blob/main/.github/workflows/CI.yml"
    click SPM "https://github.com/instagram/iglistkit/blob/main/Package.swift"
    click CocoaPods "https://github.com/instagram/iglistkit/blob/main/IGListKit.podspec"

    %% Styles
    classDef core fill:#cce5ff,stroke:#006bb3
    classDef tooling fill:#d4edda,stroke:#155724
    classDef consumer fill:#fff3cd,stroke:#856404
    classDef packaging fill:#e2e3e5,stroke:#6c757d
    classDef plugin fill:#e2d4f0,stroke:#6f42c1
```
