add event broker page to docs

Author: walshmm

docs/source/design/event_broker.rst

@@ -0,0 +1,122 @@
+EventBroker
+===========
+
+The ``EventBroker`` provides a lightweight publish/subscribe (pub-sub) mechanism for
+decoupled event-driven communication between components. It acts as a central
+dispatcher that routes events to registered subscribers based on event type.
+
+Overview
+--------
+
+The broker is implemented as a singleton, so all parts of the application interact
+with the same event registry. Components can:
+
+- **Register** handlers for specific event types
+- **Publish** events to notify all interested subscribers
+- Rely on a simple recursion guard to prevent runaway event loops
+
+This pattern is useful for cross-cutting concerns such as logging, state updates,
+UI notifications, or domain events.
+
+Basic Usage
+-----------
+
+Registering Subscribers
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Subscribers are callables that accept a single event instance.
+
+.. code-block:: python
+
+   from tavi.meta.event.event_interface import Event
+   from myapp.events import UserCreatedEvent
+   from myapp.event_broker import EventBroker
+
+   def on_user_created(event: UserCreatedEvent) -> None:
+       print(f"User created: {event.user_id}")
+
+   broker = EventBroker()
+   broker.register(UserCreatedEvent, on_user_created)
+
+Publishing Events
+~~~~~~~~~~~~~~~~~
+
+When an event is published, all subscribers registered for that event type are invoked.
+
+.. code-block:: python
+
+   event = UserCreatedEvent(user_id="123")
+   broker.publish(event)
+
+Each subscriber receives a **deep copy** of the event instance. This prevents
+subscribers from mutating shared state and affecting other listeners.
+
+Event Dispatch Semantics
+------------------------
+
+- **Dispatch is synchronous**: subscribers are called in the order they were registered.
+- **Dispatch is type-based**: only subscribers registered for the exact event class
+  (``type(event)``) are invoked.
+- **Event instances are copied**: each subscriber receives an isolated event object.
+
+Recursion Guard
+---------------
+
+The broker enforces a maximum call depth to prevent infinite or runaway recursion
+when events trigger other events during handling.
+
+If the maximum depth is exceeded, a ``RuntimeError`` is raised:
+
+.. code-block:: python
+
+   RuntimeError: Event recursive depth of 1 has been exceeded.
+
+This protects against patterns like:
+
+- A handler publishing the same event type it is subscribed to
+- Circular event chains between handlers
+
+If deeper event chaining is required, the maximum depth can be increased:
+
+.. code-block:: python
+
+   broker = EventBroker()
+   broker.call_depth_max = 3
+
+Recommended Practices
+---------------------
+
+- **Keep handlers small and side-effect focused**
+  Event handlers should perform limited, well-defined actions and avoid complex control flow.
+
+- **Avoid cyclic event dependencies**
+  Design event flows to be acyclic where possible. The recursion guard is a safety net,
+  not a control mechanism.
+
+- **Prefer domain-specific events**
+  Use narrowly scoped event types (e.g., ``UserCreatedEvent`` instead of a generic
+  ``UserEvent``) to keep subscriptions explicit and predictable.
+
+- **Do not mutate incoming events**
+  Although handlers receive copies, treat events as immutable to preserve intent
+  and make behavior easier to reason about.
+
+Typical Use Cases
+-----------------
+
+- Emitting domain events from application services
+- Triggering side effects such as logging, metrics, or notifications
+- Decoupling UI updates from core business logic
+- Broadcasting lifecycle events (startup, shutdown, state changes)
+
+Limitations
+-----------
+
+- No built-in support for asynchronous handlers
+- No wildcard or base-class subscriptions (exact type matching only)
+- No unregistration mechanism for subscribers
+- No event classification system.  It does not validate that a subscriber *should* receive a specific event class. (Model vs Presenter)
+- Global singleton scope may be undesirable in some testing or multi-tenant contexts
+
+For more complex workflows (async dispatch, filtering, prioritization, or scoped
+brokers), consider layering a more advanced event bus on top of this interface.