# aloisdeniel/flutter_device_preview architecture

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

- Interactive diagram: https://gitdiagram.com/aloisdeniel/flutter_device_preview
- Repository: https://github.com/aloisdeniel/flutter_device_preview

## Overview

##### Project type and purpose
- This is a multi‐package Flutter/Dart monorepo hosting three related libraries (device_frame, device_preview, devtools_device_preview), plus a plugins folder and documentation site.
- The primary package (described in the README) is device_preview: a Flutter widget library that simulates various mobile and desktop devices, orientations, locales, themes, and hosts a plugin system (screenshots, file explorer, etc.).

##### High-level file-structure/architecture analysis
- **Top-level packages**
- device_frame – a Dart package containing data and drawing logic for device frames (Android, iOS, generic, Linux, macOS, Windows).
- device_preview – the core Flutter package providing the UI “shell” around your app to simulate devices.
- devtools_device_preview – a package that embeds Device Preview into Flutter DevTools.
- plugins/device_preview_screenshot – example of a Device Preview plugin handling screenshot capture.
- docs – static website content generated from the packages’ markdown documentation.
- **Common pattern inside each package**
- lib/src – package code, split into subfolders by concern (e.g., state, storage, views, utilities).
- example – a Flutter host app demonstrating how to integrate the package on Android, iOS, Web, macOS, Linux, Windows.
- pubspec.yaml – Dart/Flutter package configuration.
- test – unit or golden tests.

##### Core device_preview package component breakdown
a. **Entry-point**
- device_preview.dart – exports public API, including the DevicePreview widget.
b. **UI Layer (Presentation)**
- lib/src/views – Flutter widgets rendering the device preview shell, tool panel (sections: device, locale, settings, accessibility…), small/large views, theme toggles.
c. **State Management**
- lib/src/state – immutable state (freezed data classes), a Store class driving current device, orientation, locale, theme, and triggers updates.
d. **Persistence (Storage Layer)**
- lib/src/storage – abstract Storage interface, with implementations for file‐based and in‐memory (mock) on I/O and Web, and preferences backend (SharedPreferences, Web localStorage).
e. **Utilities**
- lib/src/utilities – media‐query observer, screenshot helpers, JSON converters, assertion helpers.
f. **Plugins System**
- DevicePreview exposes extension points: plugins register panels or actions (e.g., screenshot, file explorer).
g. **Dependencies**
- Depends on Flutter framework, provider or built_value-style libs (freezed), JSON serialization (json_serializable), and device_frame for frame drawing.

##### Relationships and data flow
- **DevicePreview widget (Presentation)**
→ reads from **State Store**
→ renders **Views** (tool panels, device canvas)
→ when user interacts (e.g., change orientation, theme, plugin action), dispatches actions to **State Store**
→ **State Store** updates state, notifies **Views**
→ **State Store** persists new state via **Storage Layer**
→ **Utilities** (media query observer) pick up environment changes, feed back into store
- **device_frame** package is imported by device_preview to supply `Frame` and `Screen` geometry & drawing logic.

##### Architectural patterns & design principles
- **Layered architecture**: Presentation (views) → Application state → Persistence (storage)
- **Unidirectional data flow**: UI events → State store → View updates
- **Modular package structure**: each package encapsulates its concern with examples
- **Plugin extensibility**: design a plugin API (register panels, actions) so third‐party plugins can hook into the tool panel

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-level packages
    subgraph "device_frame" 
        direction TB
        device_frame_pkg["device_frame"]:::package
        df_entry["device_frame.dart"]:::internal
        df_devices["/src/devices/"]:::internal
        device_frame_pkg --> df_entry
        device_frame_pkg --> df_devices
    end

    subgraph "device_preview" 
        direction TB
        device_preview_pkg["device_preview"]:::package
        dp_entry["device_preview.dart"]:::internal
        dp_core["device_preview.dart (core)"]:::internal
        dp_views["/src/views/"]:::internal
        dp_state["/src/state/"]:::internal
        dp_storage["/src/storage/"]:::internal
        dp_utils["/src/utilities/"]:::internal
        dp_plugin_api["Plugin API"]:::internal

        device_preview_pkg --> dp_entry
        dp_entry --> dp_core
        dp_core --> dp_views
        dp_core --> dp_state
        dp_state --> dp_storage
        dp_utils --> dp_state
        dp_plugin_api --> dp_core
        dp_plugin_api --> ps_pkg
        dp_core --> device_frame_pkg
    end

    subgraph "devtools_device_preview" 
        direction TB
        devtools_pkg["devtools_device_preview"]:::package
        dt_entry["devtools_device_preview.dart"]:::internal
        dt_binding["/src/binding/"]:::internal
        dt_helpers["/src/helpers & tools"]:::internal

        devtools_pkg --> dt_entry
        dt_entry --> dt_binding
        dt_entry --> dt_helpers
        dt_entry --> device_preview_pkg
    end

    subgraph "plugins/device_preview_screenshot" 
        direction TB
        ps_pkg["device_preview_screenshot"]:::package
        ps_entry["device_preview_screenshot.dart"]:::internal
        ps_processors["/src/processors/"]:::internal

        ps_pkg --> ps_entry
        ps_pkg --> ps_processors
        ps_pkg --> dp_plugin_api
    end

    subgraph "Documentation Site" 
        direction TB
        docs_pkg["docs"]:::example
        docs_content["/content/"]:::example

        docs_pkg --> docs_content
    end

    %% Example host apps
    ExampleApp["Example Host Apps"]:::example
    ExampleApp --> device_preview_pkg

    %% Click Events
    click device_frame_pkg "https://github.com/aloisdeniel/flutter_device_preview/tree/master/device_frame/"
    click df_entry "https://github.com/aloisdeniel/flutter_device_preview/blob/master/device_frame/lib/device_frame.dart"
    click df_devices "https://github.com/aloisdeniel/flutter_device_preview/tree/master/device_frame/lib/src/devices/"
    click device_preview_pkg "https://github.com/aloisdeniel/flutter_device_preview/tree/master/device_preview/"
    click dp_entry "https://github.com/aloisdeniel/flutter_device_preview/blob/master/device_preview/lib/device_preview.dart"
    click dp_core "https://github.com/aloisdeniel/flutter_device_preview/blob/master/device_preview/lib/src/device_preview.dart"
    click dp_views "https://github.com/aloisdeniel/flutter_device_preview/tree/master/device_preview/lib/src/views/"
    click dp_state "https://github.com/aloisdeniel/flutter_device_preview/tree/master/device_preview/lib/src/state/"
    click dp_storage "https://github.com/aloisdeniel/flutter_device_preview/tree/master/device_preview/lib/src/storage/"
    click dp_utils "https://github.com/aloisdeniel/flutter_device_preview/tree/master/device_preview/lib/src/utilities/"
    click devtools_pkg "https://github.com/aloisdeniel/flutter_device_preview/tree/master/devtools_device_preview/"
    click dt_entry "https://github.com/aloisdeniel/flutter_device_preview/blob/master/devtools_device_preview/lib/devtools_device_preview.dart"
    click dt_binding "https://github.com/aloisdeniel/flutter_device_preview/tree/master/devtools_device_preview/lib/src/binding/"
    click dt_helpers "https://github.com/aloisdeniel/flutter_device_preview/tree/master/devtools_device_preview/lib/src/helpers/"
    click ps_pkg "https://github.com/aloisdeniel/flutter_device_preview/tree/master/plugins/device_preview_screenshot/"
    click ps_entry "https://github.com/aloisdeniel/flutter_device_preview/blob/master/plugins/device_preview_screenshot/lib/device_preview_screenshot.dart"
    click ps_processors "https://github.com/aloisdeniel/flutter_device_preview/tree/master/plugins/device_preview_screenshot/lib/src/processors/"
    click docs_pkg "https://github.com/aloisdeniel/flutter_device_preview/tree/master/docs/"
    click docs_content "https://github.com/aloisdeniel/flutter_device_preview/tree/master/docs/content/"

    %% Styles
    classDef package fill:#f9f,stroke:#333,stroke-width:2px
    classDef internal fill:#9f9,stroke:#333,stroke-width:1px
    classDef example fill:#9cf,stroke:#333,stroke-width:1px
```
