diff --git a/README.md b/README.md
index dbf80c2..b907701 100644
--- a/README.md
+++ b/README.md
@@ -63,34 +63,9 @@ https://github.com/anthony1810/ScreenStateKit.git
ScreenStateKit promotes a clean architecture pattern for building features with three core components:
-```
-┌─────────────────────────────────────────────────────────────┐
-│ SwiftUI View │
-│ - Owns @State for ViewState and ViewModel │
-│ - Binds state to ViewModel in .task modifier │
-│ - Dispatches actions via viewModel.receive(action:) │
-└─────────────────────────────────────────────────────────────┘
- │
- │ binds & dispatches
- ▼
-┌─────────────────────────────────────────────────────────────┐
-│ ViewModel / Store (Actor) │
-│ - Conforms to ScreenActionStore protocol │
-│ - Holds weak reference to state │
-│ - Processes actions with ActionLocker │
-│ - Updates state on @MainActor │
-└─────────────────────────────────────────────────────────────┘
- │
- │ updates
- ▼
-┌─────────────────────────────────────────────────────────────┐
-│ ViewState (Observable) │
-│ - Extends ScreenState │
-│ - @Observable @MainActor class │
-│ - Contains all UI state properties │
-│ - Inherits loading/error handling │
-└─────────────────────────────────────────────────────────────┘
-```
+
+ 
+
### The Three Pillars
@@ -206,6 +181,12 @@ actor FeatureViewStore: ScreenActionStore {
}
```
+**Action Flow:** Here's how actions are processed through `ActionLocker` and `LoadingTrackable`:
+
+
+ 
+
+
### 3. Build the View
```swift
@@ -338,6 +319,10 @@ await viewState?.updateState({ state in
`ScreenState` supports parent-child relationships, where loading and error states propagate upward from a child state to a parent.
+
+ 
+
+
```swift
public struct BindingParentStateOption: OptionSet, Sendable {
public static let loading // Propagate loading state
diff --git a/docs/images/action-flow.drawio b/docs/images/action-flow.drawio
new file mode 100644
index 0000000..3ed3453
--- /dev/null
+++ b/docs/images/action-flow.drawio
@@ -0,0 +1,99 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/images/action-flow.png b/docs/images/action-flow.png
new file mode 100644
index 0000000..8367c57
Binary files /dev/null and b/docs/images/action-flow.png differ
diff --git a/docs/images/architecture-overview.drawio b/docs/images/architecture-overview.drawio
new file mode 100644
index 0000000..11817eb
--- /dev/null
+++ b/docs/images/architecture-overview.drawio
@@ -0,0 +1,86 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/images/architecture-overview.png b/docs/images/architecture-overview.png
new file mode 100644
index 0000000..1f02fa1
Binary files /dev/null and b/docs/images/architecture-overview.png differ
diff --git a/docs/images/parent-child-binding.drawio b/docs/images/parent-child-binding.drawio
new file mode 100644
index 0000000..4401295
--- /dev/null
+++ b/docs/images/parent-child-binding.drawio
@@ -0,0 +1,104 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/images/parent-child-binding.png b/docs/images/parent-child-binding.png
new file mode 100644
index 0000000..67129e8
Binary files /dev/null and b/docs/images/parent-child-binding.png differ