# xvrh/lottie-flutter architecture

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

- Interactive diagram: https://gitdiagram.com/xvrh/lottie-flutter
- Repository: https://github.com/xvrh/lottie-flutter

## Overview

##### Project type and purpose
- This is an open-source Flutter/Dart library (“lottie_flutter”) that parses and renders Adobe After Effects animations (exported as JSON, TGS, or .lottie) in Flutter apps on Android, iOS, macOS, Linux, Windows, and Web.
- The project also includes an “example” Flutter application, unit/integration tests, and several CLI tools for code style, file-list generation, README generation, and publish automation.

##### File structure
- Top-level directories:
- lib/        → core library code (animation, parser, model, rendering, caching, providers, utils)
- example/    → sample Flutter app demonstrating usage on mobile, desktop, web
- test/       → unit, parser, rendering, golden tests
- tool/       → Dart scripts for code style, README generation, publish workflow
- .github/    → CI workflows (analysis, test coverage, publish on pub.dev)
- Core lib is itself layered into animation (runtime engine), model (data structures), parser (JSON→model), providers (asset I/O), render cache, drawable/rendering surfaces, and widget integration (LottieBuilder, Lottie widget).

##### README for additional insights
- The README explains
- Widget APIs (Lottie.asset, network, memory)
- Custom controllers and drawing (CustomPainter)
- ValueDelegates for runtime property overrides
- Frame rate control and renderCache mode
- Support for TGS and .lottie with custom decoders
- It positions the library as a drop-in solution in any Flutter UI, with key extension points at asset loading (providers), parsing, and rendering.

##### Detail is crucial
- Core packages under lib/src (parser, model, animation, providers, render_cache, drawable)
- Optional branches (e.g., renderCache enabled vs default rendering)
- Extension points (ValueDelegate, custom decoders)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "Example Application" 
        direction TB
        MainApp["example/lib/main.dart\n(example app)"]:::ui
    end

    %% Library Entry Points
    subgraph "Library Entry Points"
        direction TB
        LottieD["lib/lottie.dart"]:::entry
        LottieSrc["lib/src/lottie.dart"]:::entry
        Builder["lib/src/lottie_builder.dart"]:::entry
    end

    %% Providers Layer
    subgraph "Providers Layer"
        direction TB
        AssetProv["AssetProvider"]:::provider
        FileIO["FileProviderIO"]:::provider
        NetworkProv["NetworkProvider"]:::provider
        MemoryProv["MemoryProvider"]:::provider
        NoIO["FileProviderNoIO"]:::provider
        LottieProv["LottieProvider"]:::provider
    end

    %% Parsing Layer
    subgraph "Parsing Layer"
        direction TB
        JSONReader["moshi/json_reader.dart"]:::parser
        JSONUtf8["moshi/json_utf8_reader.dart"]:::parser
        ParserUtils["json_utils.dart"]:::parser
        CompositionParser["lottie_composition_parser.dart"]:::parser
        AllParsers["other parsers"]:::parser
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        Composition["composition.dart"]:::model
        Animatable["model/animatable"]:::model
        ContentModel["model/content"]:::model
        Layers["model/layer"]:::model
        Marker["marker.dart"]:::model
    end

    %% Animation Engine
    subgraph "Animation Engine"
        direction TB
        KeyframeAnim["animation/keyframe"]:::animation
        ContentAnim["animation/content"]:::animation
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        direction TB
        Drawable["lottie_drawable.dart"]:::render
        RenderLottie["render_lottie.dart"]:::render
        DrawingContent["drawing_content"]:::render
    end

    %% Render Cache
    subgraph "Render Cache"
        direction TB
        CacheCore["render_cache.dart"]:::cache
        CacheKey["key"]:::cache
        Store["store"]:::cache
        StoreDraw["store_drawing"]:::cache
        StoreRaster["store_raster"]:::cache
    end

    %% Utility Modules
    subgraph "Utility Modules"
        direction TB
        Utils["utils/utils.dart"]:::util
        AllUtils["utils/*"]:::util
        PerfTrack["performance_tracker.dart"]:::util
    end

    %% Value Delegates
    subgraph "Value Delegates & Callbacks"
        direction TB
        ValueDel["value_delegate.dart"]:::util
        ValueCB["value/*"]:::util
        Delegates["lottie_delegates.dart"]:::util
    end

    %% Core Flow
    MainApp -->|uses| Builder
    Builder -->|imports| LottieSrc
    LottieSrc -->|constructs| AssetProv
    LottieSrc -->|constructs| FileIO
    LottieSrc -->|constructs| NetworkProv
    LottieSrc -->|constructs| MemoryProv
    AssetProv -->|reads| JSONUtf8
    FileIO -->|reads| JSONReader
    NetworkProv -->|reads| JSONReader
    MemoryProv -->|provides| ParserUtils
    JSONUtf8 --> CompositionParser --> Composition
    JSONReader --> CompositionParser
    Composition -->|drives| KeyframeAnim
    Composition -->|drives| ContentAnim
    KeyframeAnim --> Drawable
    ContentAnim --> Drawable
    Drawable --> RenderLottie --> DrawingContent
    Drawable -->|cache check| CacheCore
    CacheCore --> StoreDraw
    CacheCore --> StoreRaster
    Drawable -->|helpers| Utils
    Drawable -->|track| PerfTrack
    KeyframeAnim -->|callbacks| ValueDel
    ValueDel --> ValueCB

    %% Click Events
    click LottieD "https://github.com/xvrh/lottie-flutter/blob/master/lib/lottie.dart"
    click LottieSrc "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/lottie.dart"
    click Builder "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/lottie_builder.dart"
    click AssetProv "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/providers/asset_provider.dart"
    click FileIO "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/providers/file_provider_io.dart"
    click NetworkProv "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/providers/network_provider.dart"
    click MemoryProv "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/providers/memory_provider.dart"
    click NoIO "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/providers/file_provider_no_io.dart"
    click LottieProv "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/providers/lottie_provider.dart"
    click CompositionParser "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/parser/lottie_composition_parser.dart"
    click ParserUtils "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/parser/json_utils.dart"
    click JSONReader "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/parser/moshi/json_reader.dart"
    click JSONUtf8 "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/parser/moshi/json_utf8_reader.dart"
    click AllParsers "https://github.com/xvrh/lottie-flutter/tree/master/lib/src/parser/"
    click Composition "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/composition.dart"
    click Animatable "https://github.com/xvrh/lottie-flutter/tree/master/lib/src/model/animatable"
    click ContentModel "https://github.com/xvrh/lottie-flutter/tree/master/lib/src/model/content"
    click Layers "https://github.com/xvrh/lottie-flutter/tree/master/lib/src/model/layer"
    click Marker "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/model/marker.dart"
    click KeyframeAnim "https://github.com/xvrh/lottie-flutter/tree/master/lib/src/animation/keyframe/"
    click ContentAnim "https://github.com/xvrh/lottie-flutter/tree/master/lib/src/animation/content/"
    click Drawable "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/lottie_drawable.dart"
    click RenderLottie "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/render_lottie.dart"
    click DrawingContent "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/animation/content/drawing_content.dart"
    click CacheCore "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/render_cache.dart"
    click CacheKey "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/render_cache/key.dart"
    click Store "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/render_cache/store.dart"
    click StoreDraw "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/render_cache/store_drawing.dart"
    click StoreRaster "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/render_cache/store_raster.dart"
    click Utils "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/utils/utils.dart"
    click AllUtils "https://github.com/xvrh/lottie-flutter/tree/master/lib/src/utils/"
    click PerfTrack "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/performance_tracker.dart"
    click ValueDel "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/value_delegate.dart"
    click ValueCB "https://github.com/xvrh/lottie-flutter/tree/master/lib/src/value/"
    click Delegates "https://github.com/xvrh/lottie-flutter/blob/master/lib/src/lottie_delegates.dart"

    %% Styles
    classDef ui fill:#9f6,stroke:#333,stroke-width:1px
    classDef entry fill:#6cf,stroke:#333,stroke-width:1px
    classDef provider fill:#fc6,stroke:#333,stroke-width:1px
    classDef parser fill:#ffb,stroke:#333,stroke-width:1px
    classDef model fill:#bbf,stroke:#333,stroke-width:1px
    classDef animation fill:#f96,stroke:#333,stroke-width:1px
    classDef render fill:#f63,stroke:#333,stroke-width:1px
    classDef cache fill:#fc9,stroke:#333,stroke-width:1px
    classDef util fill:#ccc,stroke:#333,stroke-width:1px
```
