# davidchow24/simple_controller architecture

> Architecture diagram of the GitHub repository davidchow24/simple_controller, 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/davidchow24/simple_controller
- Repository: https://github.com/davidchow24/simple_controller

## Overview

##### Project type and purpose
- Type: A Flutter “plugin” / Dart package that provides a lightweight state management solution.
- Purpose: To offer an intuitive API (SimpleController, createState, createCommand, Provider widgets, context.use, controller.build) for managing reactive UI state with minimal boilerplate.

##### File structure
- lib/simple_controller.dart: The single entry point containing all core classes and APIs.
- example/: A full Flutter project showcasing usage on Android, iOS, web, desktop.
- pubspec.yaml: Declares Flutter as dependency, marks package as a plugin.

##### README for additional insights
- Core concepts: SimpleController (extends ChangeNotifier), reactive state (createState, createRefState), commands (createCommand), Provider widgets, context.use<T>(), controller.build().
- No external services or databases—purely in-process state management.

##### Main components
A. Flutter Application (UI Layer)
– Widgets tree
– Example app’s CounterWidget, CounterButton, MainApp, etc.
B. simple_controller Package
– SimpleController (base class)
– State objects (State<T>, RefState<T>)
– Command objects (Command<T>)
– Provider widgets (SimpleControllerProvider, multi)
– Extension method (BuildContext.use<T>())
– Builder method (controller.build())
C. Underlying Flutter Framework
– ChangeNotifier (foundation)
– InheritedWidget mechanism (used by Provider)
– BuildContext, Element tree

##### Relationships and data flows
1. Provider widget injects one or more SimpleController instances into the Flutter widget tree (InheritedWidget).
2. Any descendant widget calls context.use<T>() to retrieve a controller instance.
3. Widgets invoke controller.createCommand().execute(...) or mutate state via controller.createState().value.
4. SimpleController (ChangeNotifier) calls notifyListeners().
5. controller.build(select:…, builder:…) listens to changes and triggers rebuild of only affected widgets.

##### Architectural patterns and design principles
- Observer Pattern: SimpleController notifies listeners upon state changes.
- Provider Pattern: Controllers are scoped to widget subtrees.
- Reactive Programming: createState and createRefState produce “reactive” state holders.
- Separation of Concerns: UI widgets remain stateless; logic lives in controllers.

##### Essential elements
– Clear labels for each component and subcomponent
– Highlight of key APIs and their interactions

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        MainApp["MainApp"]:::ui
        CounterWidget["CounterWidget"]:::ui
        CounterButton["CounterButton"]:::ui
    end

    subgraph "simple_controller Package"
        SCControl["SimpleController"]:::pkg
        State["State<T>, RefState<T>"]:::pkg
        Command["Command<T>"]:::pkg
        Provider["SimpleControllerProvider"]:::pkg
        Extension["BuildContext.use<T>()"]:::pkg
        Builder["controller.build()"]:::pkg
    end

    subgraph "Flutter Framework"
        ChangeNotifier["ChangeNotifier"]:::fw
        InheritedWidget["InheritedWidget"]:::fw
        BuildContextFW["BuildContext"]:::fw
    end

    PubspecPkg["pubspec.yaml"]:::pkg
    PubspecExample["example/pubspec.yaml"]:::ui

    MainApp -->|"wraps with Provider"| Provider
    Provider -->|"injects SimpleController"| SCControl
    CounterWidget -->|"calls context.use<T>()"| Extension
    Extension -->|"retrieves controller"| SCControl
    CounterWidget -->|"calls createCommand().execute()"| Command
    CounterWidget -->|"mutates state via createState().value"| State
    Command -->|"invokes action mutating state"| State
    State -->|"calls notifyListeners()"| ChangeNotifier
    ChangeNotifier -->|"triggers"| Builder
    Builder -->|"rebuilds widget"| CounterWidget
    SCControl -->|"extends"| ChangeNotifier
    PubspecPkg -->|"declares plugin"| SCControl
    PubspecExample -->|"integrates package"| MainApp

    click MainApp "https://github.com/davidchow24/simple_controller/blob/main/example/lib/main.dart"
    click CounterWidget "https://github.com/davidchow24/simple_controller/blob/main/example/lib/main.dart"
    click CounterButton "https://github.com/davidchow24/simple_controller/blob/main/example/lib/main.dart"
    click SCControl "https://github.com/davidchow24/simple_controller/blob/main/lib/simple_controller.dart"
    click State "https://github.com/davidchow24/simple_controller/blob/main/lib/simple_controller.dart"
    click Command "https://github.com/davidchow24/simple_controller/blob/main/lib/simple_controller.dart"
    click Provider "https://github.com/davidchow24/simple_controller/blob/main/lib/simple_controller.dart"
    click Extension "https://github.com/davidchow24/simple_controller/blob/main/lib/simple_controller.dart"
    click Builder "https://github.com/davidchow24/simple_controller/blob/main/lib/simple_controller.dart"
    click PubspecPkg "https://github.com/davidchow24/simple_controller/blob/main/pubspec.yaml"
    click PubspecExample "https://github.com/davidchow24/simple_controller/blob/main/example/pubspec.yaml"

    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef pkg fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef fw fill:#E0E0E0,stroke:#333,stroke-width:1px
```
