Add comprehensive swift-docc documentation and architecture guide

- Update README.md with detailed architecture explanation covering Attribute, Graph, and Runtime components
- Create swift-docc documentation catalog with main module documentation
- Add in-depth Architecture.md article explaining the three-layer system
- Document key public APIs including:
  * Attribute<Value> struct with property wrapper documentation
  * Rule protocol for computed attributes
  * Metadata extensions for runtime type introspection
- Reference wickwirew/Runtime repo for Swift runtime techniques
- Include code examples and usage patterns throughout documentation

Author: Kyle-Ye

README.md

@@ -12,6 +12,35 @@ AttributeGraph is a high performance computing engine written in C++ and Swift.
 
 And it powers the underlying computing and diffing of SwiftUI.
 
+## Architecture
+
+OpenAttributeGraph consists of three main components:
+
+### Attribute Part
+The **Attribute** system provides a reactive property wrapper that automatically tracks dependencies and manages value updates. Key features include:
+- `Attribute<Value>` - A property wrapper for reactive values with automatic dependency tracking
+- `AnyAttribute` - Type-erased attribute for runtime flexibility  
+- **Rules** - Transform attributes through `Rule` and `StatefulRule` protocols
+- **Weak/Optional** - Support for optional and weak attribute references
+- **Body system** - Efficient value computation and caching mechanisms
+
+### Graph Part
+The **Graph** manages the dependency network and orchestrates updates across attributes. Core functionality includes:
+- `Graph` - Central coordinator for attribute relationships and update cycles
+- `Subgraph` - Scoped computation contexts for isolated attribute groups
+- **Invalidation tracking** - Efficient change propagation through the dependency graph
+- **Update scheduling** - Optimized batch processing of attribute changes
+- **Profiling support** - Performance monitoring and debugging capabilities
+
+### Runtime Part
+The **Runtime** provides low-level type introspection and memory management utilities. This includes:
+- `Metadata` - Swift runtime type information and reflection capabilities
+- **Type comparison** - Efficient value equality checking across different types  
+- **Memory layout** - Safe pointer manipulation and offset calculations
+- **Tuple handling** - Runtime support for tuple types and field access
+
+> **Note**: The Runtime part leverages techniques similar to those found in [wickwirew/Runtime](https://github.com/wickwirew/Runtime) for Swift runtime introspection.
+
 | **CI Status** |
 |---|
 |[![Compatibility tests](https://github.com/OpenSwiftUIProject/OpenAttributeGraph/actions/workflows/compatibility_tests.yml/badge.svg)](https://github.com/OpenSwiftUIProject/OpenAttributeGraph/actions/workflows/compatibility_tests.yml)|

Sources/OpenAttributeGraph/Attribute/Attribute/Attribute.swift

@@ -1,5 +1,67 @@
 public import OpenAttributeGraphCxx
 
+/// A reactive property wrapper that automatically tracks dependencies and manages value updates.
+///
+/// `Attribute` is the core building block of the OpenAttributeGraph reactive system. When you wrap a property 
+/// with `@Attribute`, it becomes reactive and can automatically track dependencies and propagate changes.
+///
+/// ```swift
+/// @Attribute var count: Int = 0
+/// @Attribute var doubledCount: Int = count * 2
+/// 
+/// count = 5 // doubledCount automatically becomes 10
+/// ```
+///
+/// ## Key Features
+///
+/// - **Automatic dependency tracking**: Attributes automatically discover their dependencies
+/// - **Efficient updates**: Only affected attributes are recomputed when changes occur
+/// - **Type safety**: Full Swift type safety with compile-time checking
+/// - **Dynamic member lookup**: Access nested properties as reactive attributes
+/// - **Property wrapper syntax**: Clean, declarative syntax using `@Attribute`
+///
+/// ## Property Wrapper Usage
+///
+/// Use `@Attribute` to make any Swift value reactive:
+///
+/// ```swift
+/// struct CounterView {
+///     @Attribute var count: Int = 0
+///     
+///     var body: some View {
+///         Button("Count: \(count)") {
+///             count += 1
+///         }
+///     }
+/// }
+/// ```
+///
+/// ## Dynamic Member Lookup
+///
+/// Access nested properties as separate attributes:
+///
+/// ```swift
+/// @Attribute var person: Person = Person(name: "Alice", age: 30)
+/// let nameAttribute: Attribute<String> = person.name
+/// let ageAttribute: Attribute<Int> = person.age
+/// ```
+///
+/// ## Integration with Rules
+///
+/// Create computed attributes using ``Rule`` or ``StatefulRule``:
+///
+/// ```swift
+/// struct DoubledRule: Rule {
+///     typealias Value = Int
+///     let source: Attribute<Int>
+///     
+///     func value() -> Int {
+///         source.wrappedValue * 2
+///     }
+/// }
+///
+/// let doubled = Attribute(DoubledRule(source: count))
+/// ```
 @frozen
 @propertyWrapper
 @dynamicMemberLookup
@@ -8,14 +70,30 @@ public struct Attribute<Value> {
 
     // MARK: - Initializer
 
+    /// Creates an attribute from a type-erased identifier.
+    ///
+    /// - Parameter identifier: The type-erased attribute identifier
     public init(identifier: AnyAttribute) {
         self.identifier = identifier
     }
 
+    /// Creates an attribute by copying another attribute.
+    ///
+    /// - Parameter attribute: The attribute to copy
     public init(_ attribute: Attribute<Value>) {
         self = attribute
     }
 
+    /// Creates an attribute with an initial value.
+    ///
+    /// This initializer creates an external attribute that holds the provided value.
+    /// External attributes are typically used for storing user input or initial state.
+    ///
+    /// ```swift
+    /// let count = Attribute(value: 42)
+    /// ```
+    ///
+    /// - Parameter value: The initial value for the attribute
     public init(value: Value) {
         self = withUnsafePointer(to: value) { valuePointer in
             withUnsafePointer(to: External<Value>()) { bodyPointer in
@@ -61,6 +139,18 @@ public struct Attribute<Value> {
 
     // MARK: - propertyWrapper
 
+    /// The current value of the attribute.
+    ///
+    /// When used as a property wrapper with `@Attribute`, this provides the underlying value.
+    /// Getting this value may trigger dependency tracking in the current evaluation context.
+    /// Setting this value will update the attribute and invalidate any dependents.
+    ///
+    /// ```swift
+    /// @Attribute var count: Int = 0
+    /// 
+    /// print(count) // Gets wrappedValue, returns 0
+    /// count = 5    // Sets wrappedValue, triggers updates
+    /// ```
     public var wrappedValue: Value {
         unsafeAddress {
             OAGGraphGetValue(identifier, type: Value.self)
@@ -70,6 +160,18 @@ public struct Attribute<Value> {
         nonmutating set { _ = setValue(newValue) }
     }
 
+    /// The attribute itself when accessed with the `$` prefix.
+    ///
+    /// This provides access to the attribute object itself rather than its value,
+    /// allowing you to pass the reactive attribute to other functions or create
+    /// derived attributes.
+    ///
+    /// ```swift
+    /// @Attribute var count: Int = 0
+    /// 
+    /// let countAttribute = $count  // Gets the Attribute<Int> object
+    /// let doubled = countAttribute.map { $0 * 2 }
+    /// ```
     public var projectedValue: Attribute<Value> {
         get { self }
         set { self = newValue }

Sources/OpenAttributeGraph/Attribute/Rule/Rule.swift

@@ -7,9 +7,70 @@
 
 public import OpenAttributeGraphCxx
 
+/// A protocol for defining computed attributes that automatically update when dependencies change.
+///
+/// Rules provide a way to create derived attributes that compute their values based on other attributes.
+/// When any dependency changes, the rule will automatically recompute its value.
+///
+/// ```swift
+/// struct DoubledRule: Rule {
+///     typealias Value = Int
+///     let source: Attribute<Int>
+///     
+///     var value: Int {
+///         source.wrappedValue * 2
+///     }
+/// }
+///
+/// @Attribute var count: Int = 5
+/// let doubled = Attribute(DoubledRule(source: $count))
+/// // doubled.wrappedValue == 10
+///
+/// count = 10
+/// // doubled.wrappedValue automatically becomes 20
+/// ```
+///
+/// ## Key Features
+///
+/// - **Automatic dependency tracking**: Dependencies are discovered automatically when accessed
+/// - **Lazy evaluation**: Values are only computed when needed
+/// - **Caching**: Results are cached until dependencies change
+/// - **Efficient updates**: Only recomputes when dependencies actually change
+///
+/// ## Implementation Requirements
+///
+/// Types conforming to `Rule` must provide:
+/// - `Value`: The type of value produced by the rule
+/// - `value`: A computed property that returns the current value
+/// - `initialValue`: An optional initial value (defaults to `nil`)
+///
+/// ## Advanced Usage
+///
+/// For rules that need to maintain state between evaluations, see ``StatefulRule``.
+/// For rules that can be cached based on their content, make your rule type conform to `Hashable`.
 public protocol Rule: _AttributeBody {
+    /// The type of value produced by this rule.
     associatedtype Value
+    
+    /// An optional initial value to use before the rule is first evaluated.
+    ///
+    /// If `nil`, the rule will be evaluated immediately when the attribute is created.
+    /// If non-`nil`, this value will be used initially, and the rule will be evaluated
+    /// on the next update cycle.
     static var initialValue: Value? { get }
+    
+    /// Computes and returns the current value of the rule.
+    ///
+    /// This property should access any attributes or other dependencies needed to compute
+    /// the result. The attribute graph will automatically track these dependencies and
+    /// invalidate this rule when any dependency changes.
+    ///
+    /// ```swift
+    /// var value: Int {
+    ///     // Dependencies are automatically tracked
+    ///     return source1.wrappedValue + source2.wrappedValue
+    /// }
+    /// ```
     var value: Value { get }
 }