feat: move store plan to ArchitecturePlan

Author: okwasniewski

brownfield-store-plan.md packages/brownie/ArchitectureOverview.mdbrownfield-store-plan.md renamed to packages/brownie/ArchitectureOverview.md

@@ -1,8 +1,8 @@
-# Brownfield Store
+# Brownie Architecture
 
-Shared state management between React Native and Native apps (iOS/Android).
+Shared state management between React Native and Native apps (iOS).
 
-## Architecture
+## High-Level Architecture
 
 ```
 ┌─────────────────┐       ┌──────────────────┐       ┌─────────────────┐
@@ -23,18 +23,14 @@ Shared state management between React Native and Native apps (iOS/Android).
         │                                                 ▼
 ┌───────────────────┐                          ┌───────────────────────┐
 │   JS/React Hook   │                          │   Native Store        │
-│   useBrownfield() │                          │   (Swift/Kotlin)      │
+│   useBrownfield() │                          │   (Swift)             │
 └───────────────────┘                          └───────────────────────┘
 ```
 
 ## CLI
 
 The `brownie` CLI generates native store types from TypeScript schema.
 
-### Installation
-
-CLI is included in `@callstack/brownie` package.
-
 ### Usage
 
 ```bash
@@ -217,7 +213,7 @@ Output goes to `lib/scripts/` and is exposed via `bin` field in `package.json`.
 │  │  BrownieHostObject (jsi::HostObject)                      │  │
 │  │  - get(prop) -> converts folly::dynamic to jsi::Value     │  │
 │  │  - set(prop, val) -> converts jsi::Value to folly::dynamic│  │
-│  │  - unbox() -> full snapshot as jsi::Object                │  │
+│  │  - getPropertyNames() -> list of property names           │  │
 │  └───────────────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────────┘
                                │
@@ -269,8 +265,9 @@ packages/brownie/
 
 - `get(prop)` - Read property, converts `folly::dynamic` → `jsi::Value`
 - `set(prop, value)` - Write property, converts `jsi::Value` → `folly::dynamic`
-- `unbox()` - Returns full state snapshot
-- Custom `dynamicToJSI`/`jsiToDynamic` converters
+- `unbox()` - Returns full state snapshot as JSI object
+- `getPropertyNames()` - Returns list of all property names
+- Uses built-in `jsi::valueFromDynamic`/`jsi::dynamicFromValue` converters
 
 ### iOS Bridge
 
@@ -291,6 +288,7 @@ packages/brownie/
 - `init(_ initialState, key:)` - Create store, register with C++, push initial state
 - `set(_:)` - Update state with closure
 - `set(_:to:)` - Update via keypath
+- `get(_:)` - Get property via keypath
 - Observes `BrownieStoreUpdated` notification, rebuilds typed state from C++ snapshot
 - `deinit` removes notification observer
 
@@ -302,9 +300,8 @@ packages/brownie/
 
 **@UseStore** - SwiftUI property wrapper:
 
-- `init(_ keyPath, key:)` - Access specific property
-- `wrappedValue` - Current value
-- `projectedValue` - Access to full store for mutations
+- Uses `BrownieStoreProtocol` to automatically derive store key via `storeName`
+- `wrappedValue` - Access to full `Store<State>`
 
 ## JS API
 
@@ -346,127 +343,104 @@ Internal `Map<string, StoreCache>` holds:
 - Current snapshot
 - Registered listeners
 
-Snapshots refresh on `BrownieStoreUpdated` native event.
+Snapshots refresh on native store change callback.
 
-## Auto-generation Hooks
+## Data Transfer & Memory Model
 
-### iOS (Podfile)
+### Overview
 
-```ruby
-pre_install do |installer|
-  system("npx", "brownie", "codegen", "-p", "swift")
-end
-```
-
-### Android (build.gradle.kts)
+Data flows through multiple layers with **full copies** at each boundary crossing. There is no shared memory or zero-copy optimization - each layer maintains its own representation.
 
-```kotlin
-tasks.register("generateBrownfieldStore") {
-  exec { commandLine("npx", "brownie", "codegen", "-p", "kotlin") }
-}
-preBuild.dependsOn("generateBrownfieldStore")
+```
+┌─────────────┐    copy    ┌─────────────┐    copy    ┌─────────────┐
+│  JS Object  │ ─────────▶ │   folly::   │ ─────────▶ │ NSDictionary│
+│  (jsi)      │ ◀───────── │   dynamic   │ ◀───────── │   / Swift   │
+└─────────────┘    copy    └─────────────┘    copy    └─────────────┘
 ```
 
-## TODO
-
-### Codegen
-
-- [x] Support multiple stores in package.json config (array of store configs)
-- [x] Auto-discover stores from `*.brownie.ts` files (no manual config needed)
-- [x] Add CLI tests
-- [x] Generate store keys enum/constants for type safety between JS and Native
-
-### Native Runtime
-
-- [x] Improve iOS runtime code (C++ core with folly::dynamic)
-- [x] Extract C++ JSI layer to be shared across Android and iOS
-- [ ] Android native runtime implementation (Store, StoreManager, JSI bridge)
-- [ ] Keypath→string codegen for optimized single-key updates (future)
+Note: In the future we may explore optimizations like shared memory or zero-copy techniques, but for now simplicity and correctness are prioritized.
 
-### JS Runtime
+### C++ Layer (Source of Truth)
 
-- [x] useState-like hook API (`useBrownieStore` returns `[state, setState]`)
-- [x] setState supports callback pattern `(prev) => partial`
-- [ ] Optimize re-renders on the JS side (selector support)
-- [ ] Zustand integration
+**Writes use move semantics where possible:**
 
-## Re-render Optimization Plan
+- `BrownieStore::set(key, value)` - value is moved into state: `state_[key] = std::move(value)`
+- `BrownieStore::setState(state)` - entire state is moved: `state_ = std::move(state)`
+- `BrownieStoreManager::registerStore(key, store)` - shared_ptr is moved into map
 
-### Problem
+**Reads always copy:**
 
-Both JS and Swift currently re-render all subscribers when any property changes.
+- `BrownieStore::get(key)` - returns copy of `folly::dynamic` value
+- `BrownieStore::getSnapshot()` - returns copy of entire state
 
-**JS**: `useBrownieStore` returns full state → any change triggers all consumers
-**Swift**: `@Published state` replaced wholesale → all `@UseStore` views re-render
+### JSI Boundary (JS ↔ C++)
 
-### JavaScript Solution: Selector Hook
+**JS → C++ (writes):**
 
-Add `useBrownieStoreSelector` that only re-renders when selected value changes:
+1. `jsi::dynamicFromValue(rt, value)` creates new `folly::dynamic` from JS value
+2. Value is then moved into C++ store
 
-```ts
-function useBrownieStoreSelector<K extends keyof BrownieStores, T>(
-  key: K,
-  selector: (state: BrownieStores[K]) => T,
-  isEqual?: (a: T, b: T) => boolean
-): T;
-```
+**C++ → JS (reads):**
 
-**Usage:**
+1. `folly::dynamic` is copied from store
+2. `jsi::valueFromDynamic(rt, dynamic)` creates new JS value
 
-```ts
-const counter = useBrownieStoreSelector('BrownfieldStore', (s) => s.counter);
-const user = useBrownieStoreSelector('BrownfieldStore', (s) => s.user);
-```
+### ObjC++ Bridge (C++ ↔ Swift)
 
-**Implementation:**
+**Swift → C++ (writes):**
 
-1. Store previous selected value in `useRef`
-2. On store change, run selector on new snapshot
-3. Compare with previous using `isEqual` (default: `Object.is`)
-4. Only trigger re-render if different
+1. Swift encodes `Codable` state to JSON via `JSONEncoder`
+2. JSON deserialized to `NSDictionary`
+3. `convertIdToFollyDynamic(dict)` creates `folly::dynamic` copy
+4. Value moved into C++ store
 
-### Swift Solution: Selector Property Wrapper
+**C++ → Swift (reads):**
 
-Add `@UseStoreSelector` that subscribes to specific keypath:
+1. `folly::dynamic` copied from store via `getSnapshot()`
+2. `convertFollyDynamicToId(dynamic)` creates `NSDictionary` copy
+3. `JSONSerialization.data(withJSONObject:)` serializes to JSON
+4. `JSONDecoder` deserializes to typed Swift struct (another copy)
 
-```swift
-@propertyWrapper
-struct UseStoreSelector<State: BrownieStoreProtocol, Value: Equatable>: DynamicProperty {
-  let keyPath: KeyPath<State, Value>
-  @State private var value: Value
+### Performance Implications
 
-  init(_ keyPath: KeyPath<State, Value>)
-  var wrappedValue: Value { get }
-}
-```
+| Operation                | Copies | Notes                             |
+| ------------------------ | ------ | --------------------------------- |
+| JS read single property  | 2      | dynamic copy + JSI conversion     |
+| JS read snapshot (unbox) | 2      | dynamic copy + JSI conversion     |
+| JS write single property | 2      | JSI→dynamic + move into store     |
+| Swift read snapshot      | 4      | dynamic→NSDictionary→JSON→Codable |
+| Swift write full state   | 4      | Codable→JSON→NSDictionary→dynamic |
 
-**Usage:**
+### Thread Safety
 
-```swift
-@UseStoreSelector(\.counter) var counter: Int
-@UseStoreSelector(\.user) var user: String
-```
+- C++ store protected by `std::mutex` on all operations
+- Swift `StoreManager` uses `NSLock` for registry access
+- Change notifications dispatched to main queue via `dispatch_async`
 
-**Implementation:**
+### Future Optimization Opportunities
 
-1. Use `@State` instead of `@StateObject` (no `ObservableObject` dependency)
-2. Listen to `BrownieStoreUpdated` notification
-3. Extract value via keyPath from C++ snapshot
-4. Only update `@State` if value differs (Equatable check)
+The ObjC++ bridge layer has the most room for optimization:
 
-### Tasks
+- **Skip JSON serialization** - Instead of `folly::dynamic → NSDictionary → JSON → Codable`, expose individual property accessors from C++ directly to Swift. Eliminates 2 intermediate copies.
+- **Single-property sync** - Currently `pushStateToCxx()` serializes entire state. Could track dirty properties and only sync changed values.
+- **Lazy Swift state rebuild** - Defer `Codable` struct reconstruction until property actually accessed.
+- **Direct C++ ↔ Swift interop** - Swift 5.9+ has experimental C++ interop that could bypass ObjC++ bridge entirely.
 
-- [ ] JS: Implement `useBrownieStoreSelector` hook
-- [ ] JS: Add `isEqual` option for custom comparison (objects/arrays)
-- [ ] Swift: Implement `@UseStoreSelector` property wrapper
-- [ ] Swift: Consider `@Observable` macro for iOS 17+ (automatic property tracking)
+## Auto-generation Hooks
 
-### Distribution
+### iOS (Podfile)
 
-- [ ] Support xcframework packaging (iOS)
-- [ ] Support AAR packaging (Android)
-- [ ] Figure out autolinking of generated code
+```ruby
+pre_install do |installer|
+  system("npx", "brownie", "codegen", "-p", "swift")
+end
+```
 
-### Documentation
+### Android (build.gradle.kts)
 
-- [ ] Documentation
+```kotlin
+tasks.register("generateBrownfieldStore") {
+  exec { commandLine("npx", "brownie", "codegen", "-p", "kotlin") }
+}
+preBuild.dependsOn("generateBrownfieldStore")
+```