# codelessly/codelesslysdk architecture

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

- Interactive diagram: https://gitdiagram.com/codelessly/codelesslysdk
- Repository: https://github.com/codelessly/codelesslysdk

## Overview

##### Project Type and Purpose
- This is a cross‐platform Flutter SDK (a Dart library) called **Codelessly CloudUI™ SDK**, designed to let Flutter apps render dynamic UIs and receive real-time updates from the Codelessly Editor/Cloud.
- It comprises two main parts:
- The **SDK library** under `lib/src/...`
- An **example Flutter app** under `example/` demonstrating usage on Android, iOS, macOS, Windows, Linux, and Web.

##### Top-Level Architectural View
- **Example App** (Flutter front end)
- Initializes and configures the SDK
- Embeds `CodelesslyWidget`
- Supplies optional data/functions
- **Codelessly SDK**
- **Initialization & Configuration** (`Codelessly.instance`, `CodelesslyConfig`)
- **Auth Module** (`auth_manager.dart`)
- **Data Module**
– DataManager orchestrates between `cloud_database.dart`, `firebase_data_repository.dart`, `network_data_repository.dart`, `local_database.dart`, and `web_data_repository.dart`
- **Cache Module** (`cache_manager.dart`, `codelessly_cache_manager.dart`)
- **Transformer Pipeline**
– `node_registry.dart`, `node_transformer_manager.dart`, + many `passive_*_transformer.dart`
– Converts JSON layout definitions into Flutter widget AST nodes
- **UI Renderer**
– `CodelesslyWidget`, widget controller, dialog & error screens
- **Functions Module** (`functions_repository.dart`, `async_functions.dart`)
– Handles “Call Function” actions and hooks into app callbacks
- **Logging & Metrics** (`debug_logger.dart`, `error_logger.dart`, `stat_tracker.dart`)
- **Utilities & Helpers** (HTTP client, font parser, image builder, etc.)
- **External Services**
- **Codelessly Cloud** (real-time layout streaming, REST endpoints)
- **Firebase** (optional analytics/crash reporting via `firebase_options_prod.dart`)

##### Component Relationships & Data Flow
- The **Example App** → calls → **Codelessly.instance.initialize(config)**
- **Auth Module** ↔ **Codelessly Cloud** (auth token verification)
- **Data Manager** → fetch layout JSON → from **Cloud** / **Firebase** / **Local Cache** / **Web Repo**
- **Cache Manager** ← caches layout JSON for offline/preload
- **Transformer Pipeline** → parses JSON → produces widget node tree
- **UI Renderer** → builds Flutter widgets from node tree → displays on screen
- **Functions Module** ← registers callbacks → invoked by UI on user actions
- **Logging** ← collects logs & metrics → optionally reports to Codelessly backend

##### Architectural Patterns & Principles
- **Modular Layers**: clear separation of concerns (Auth, Data, Cache, Transform, UI, Functions, Logging)
- **Repository Pattern** in `lib/src/data` to abstract multiple data sources
- **Transformer Pattern** for pluggable widget node transformations
- **Singleton / Facade** via `Codelessly.instance` to expose SDK surface
- **Plugin‐style Extensibility**: add or override transformers, functions, data sources

##### Detailing & Labels
- Notes on preview vs. production mode branching at Initialization

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Flutter App" 
        direction TB
        App["Example App"]:::app
    end

    subgraph "SDK Core"
        direction TB
        %% Initialization & Configuration
        subgraph "Initialization & Configuration"
            direction TB
            Init["Codelessly.instance & Config"]:::sdk
        end

        %% Auth Module
        subgraph "Auth Module"
            direction TB
            Auth["AuthManager"]:::sdk
        end

        %% Data Module
        subgraph "Data Module"
            direction TB
            DataMgr["DataManager"]:::sdk
            CloudDB["CloudDatabase"]:::sdk
            FirebaseRepo["FirebaseDataRepository"]:::sdk
            NetworkRepo["NetworkDataRepository"]:::sdk
            LocalDB["LocalDatabase"]:::sdk
            LocalRepo["LocalDataRepository"]:::sdk
            WebRepo["WebDataRepository"]:::sdk
        end

        %% Cache Module
        subgraph "Cache Module"
            direction TB
            CacheMgr["CacheManager"]:::sdk
            CodelesslyCache["CodelesslyCacheManager"]:::sdk
        end

        %% Transformer Pipeline
        subgraph "Transformer Pipeline"
            direction TB
            NodeReg["NodeRegistry"]:::sdk
            TransformerMgr["NodeTransformerManager"]:::sdk
            PassiveLoader["PassiveTransformerManager"]:::sdk
            WidgetNodeMgr["WidgetNodeTransformerManager"]:::sdk
            Defaults["DefaultPropertyMappings"]:::sdk
        end

        %% UI Renderer
        subgraph "UI Renderer"
            direction TB
            Widget["CodelesslyWidget"]:::sdk
            Controller["WidgetController"]:::sdk
            Loading["LoadingScreen"]:::sdk
            Error["ErrorScreen"]:::sdk
            Dialog["DialogWidget"]:::sdk
            LayoutBuilder["LayoutBuilder"]:::sdk
            ContextProv["ContextProvider"]:::sdk
        end

        %% Functions Module
        subgraph "Functions Module"
            direction TB
            AsyncFuncs["AsyncFunctions"]:::sdk
            FuncRepo["FunctionsRepository"]:::sdk
            FuncUtils["FunctionUtilities"]:::sdk
        end

        %% Logging & Metrics
        subgraph "Logging & Metrics"
            direction TB
            DebugLog["DebugLogger"]:::sdk
            ErrorLog["ErrorLogger"]:::sdk
            StatTracker["StatTracker"]:::sdk
        end

        %% Utilities & Helpers
        subgraph "Utilities & Helpers"
            direction TB
            HTTPClient["HTTPClient"]:::sdk
            FontParser["FontParser"]:::sdk
            ImageBuilder["ImageBuilder"]:::sdk
            Utils["Various Utils"]:::sdk
        end

        %% Constants & Models
        subgraph "Constants & Models"
            direction TB
            Constants["SDKConstants"]:::sdk
            FirebaseOpts["FirebaseOptionsProd"]:::sdk
            Models["DataModels"]:::sdk
        end
    end

    subgraph "External Services"
        direction TB
        CCloud["Codelessly Cloud"]:::external
        Firebase["Firebase"]:::external
    end

    %% Data flows and relationships
    App -->|"initialize(config)"| Init
    Init --> Auth
    Init --> DataMgr
    Init --> CacheMgr
    Init --> TransformerMgr
    Init --> Widget
    Auth <-->|"auth token"| CCloud
    DataMgr -->|"fetch JSON layout"| CloudDB
    DataMgr --> FirebaseRepo
    DataMgr --> NetworkRepo
    DataMgr --> LocalRepo
    DataMgr --> WebRepo
    CloudDB --> CCloud
    FirebaseRepo --> Firebase
    DataMgr --> TransformerMgr
    TransformerMgr --> NodeReg
    TransformerMgr --> PassiveLoader
    TransformerMgr --> WidgetNodeMgr
    TransformerMgr --> Defaults
    TransformerMgr -->|"Widget node list"| Widget
    Widget --> Controller
    Controller --> LayoutBuilder
    LayoutBuilder --> ContextProv
    Widget --> Loading
    Widget --> Error
    Widget --> Dialog
    Widget -->|"user event"| FuncRepo
    FuncRepo --> AsyncFuncs
    FuncRepo --> FuncUtils
    FuncRepo -->|"callback"| App
    DebugLog -->|"logs"| CCloud
    ErrorLog --> CCloud
    StatTracker --> CCloud

    %% Click Events
    click App "https://github.com/codelessly/codelesslysdk/blob/master/example/lib/main.dart"
    click Init "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/codelessly.dart"
    click Init "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/codelessly_config.dart"
    click Auth "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/auth/auth_manager.dart"
    click DataMgr "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/data/data_manager.dart"
    click CloudDB "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/data/cloud_database.dart"
    click FirebaseRepo "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/data/firebase_data_repository.dart"
    click NetworkRepo "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/data/network_data_repository.dart"
    click LocalDB "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/data/local_database.dart"
    click LocalRepo "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/data/local_data_repository.dart"
    click WebRepo "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/data/web_data_repository.dart"
    click CacheMgr "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/cache/cache_manager.dart"
    click CodelesslyCache "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/cache/codelessly_cache_manager.dart"
    click NodeReg "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/transformers/node_registry.dart"
    click TransformerMgr "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/transformers/node_transformer_manager.dart"
    click PassiveLoader "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/transformers/passive_transformer_manager.dart"
    click WidgetNodeMgr "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/transformers/widget_node_transformer_manager.dart"
    click Defaults "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/transformers/defaults/defaults.dart"
    click Widget "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/ui/codelessly_widget.dart"
    click Controller "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/ui/codelessly_widget_controller.dart"
    click Loading "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/ui/codelessly_loading_screen.dart"
    click Error "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/ui/codelessly_error_screen.dart"
    click Dialog "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/ui/codelessly_dialog_widget.dart"
    click LayoutBuilder "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/ui/layout_builder.dart"
    click ContextProv "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/ui/codelessly_context.dart"
    click AsyncFuncs "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/functions/async_functions.dart"
    click FuncRepo "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/functions/functions_repository.dart"
    click FuncUtils "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/functions/functions.dart"
    click DebugLog "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/logging/debug_logger.dart"
    click ErrorLog "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/logging/error_logger.dart"
    click StatTracker "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/logging/stat_tracker.dart"
    click HTTPClient "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/utils/codelessly_http_client.dart"
    click FontParser "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/utils/font_parser.dart"
    click ImageBuilder "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/utils/image_builder.dart"
    click Utils "https://github.com/codelessly/codelesslysdk/tree/master/lib/src/utils"
    click Constants "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/constants.dart"
    click FirebaseOpts "https://github.com/codelessly/codelesslysdk/blob/master/lib/src/firebase_options_prod.dart"
    click Models "https://github.com/codelessly/codelesslysdk/tree/master/lib/src/model"

    %% Styles
    classDef app fill:#fff2cc,stroke:#333,color:#000
    classDef sdk fill:#cfe2f3,stroke:#333,color:#000
    classDef external fill:#d9ead3,stroke:#333,color:#000
```
