Flow Architecture
================

vein's configuration management is built on a powerful state management engine called **Flow**.

The Flow Engine
--------------

Flow provides the foundation for real-time state management across your application:

.. code-block:: python

    from vein import config  # Built on Flow
    
    # Flow handles the complexity
    config.api_key = "secret"  # Real-time updates
    config.database.host = "localhost"  # Nested state
    config.on_change("api_key", handle_key_change)  # Event system

How Flow Works
-------------

Flow manages state through several key components:

* **Real-time Updates**: Changes propagate instantly across your app
* **Event System**: React to state changes with callbacks
* **Validation**: Built-in validation with custom policies
* **Caching**: Intelligent caching for performance
* **Sources**: Multiple data sources (env vars, files, AWS, etc.)

.. code-block:: python

    # Flow handles all this complexity
    config.update(from_env("APP_"))
    config.update(from_yaml("config.yml"))
    config.update(from_appconfig("myapp", "prod"))

Using Flow Directly
------------------

Flow is available as a base class for custom state management:

.. code-block:: python

    from vein import Flow
    
    # Create custom state management
    class UserSession(Flow):
        def __init__(self):
            super().__init__()
            self.user_id = None
            self.permissions = []
    
    # Use it like any Flow-based system
    session = UserSession()
    session.user_id = "123"
    session.on_change("user_id", handle_user_change)

Why Flow?
---------

The Flow abstraction provides several key benefits:

* **Separation of Concerns**: State logic is separate from business logic
* **Reusability**: Same patterns work for config, sessions, preferences, etc.
* **Consistency**: All state management uses the same validation, caching, and event systems
* **Testability**: State management can be tested independently
* **Extensibility**: Easy to add new state types without changing the core engine

The Config Interface
-------------------

For now, vein exposes Flow through the familiar Config interface:

.. code-block:: python

    from vein import config
    
    # Simple configuration API
    config.api_key = "secret"
    config.timeout = 30
    
    # But powered by Flow underneath
    print(type(config))  # <class 'vein.flow.config.Config'>

Long-term Vision
---------------

We're introducing vein as a configuration management library because:

* **Immediate Value**: Configuration is a universal need that developers understand
* **Familiar Patterns**: Config interfaces are well-established and intuitive
* **Natural Progression**: Introduces Flow concepts through familiar configuration patterns

However, Flow is designed for general state management. In the long run, vein will expand to handle all sorts of state management while maintaining full backwards compatibility with all configuration management from v1.0 onwards.

The goal is to provide a unified state management experience where the same patterns, performance, and reliability you get with configuration apply to any type of state your application needs to manage.