Last life cycle refactor updates + add comprehensive documentation (#57)

Co-authored-by: Michal Pikulski <michal.a.pikulski@gmail.com>
Reviewed-on: #57

docs/managed_behavior/architecture_overview.md

@@ -0,0 +1,93 @@
+# ManagedBehaviour System - Architecture Overview
+
+**Version:** 2.0 <br>
+**Updated:** 11.11.2025
+
+
+---
+
+## What is the ManagedBehaviour System?
+
+Lifecycle orchestration framework that provides guaranteed execution order and deterministic lifecycle management for Unity components.
+
+### Problems Solved
+
+We've had quite a few things shoe-stringed together in various ways and dependant on references to each other.
+Due to undefined initialization order - null references during access to yet uninitialized resources was becoming a problem.
+
+### What You Get
+
+- **Guaranteed Initialization Order** - Managers ready before components that depend on them
+- **Deterministic Lifecycle Hooks** - Predictable callbacks at key moments
+- **Automatic Registration** - No boilerplate for wiring up systems
+- **Scene Lifecycle Events** - Built-in hooks for scene load/unload
+- **Save/Load Coordination** - Centralized collection of save data
+- **Bootstrap Integration** - Components know when bootstrap completes  
+
+---
+
+## Architecture Principles
+
+### 1. Centralized Orchestration
+
+Single `LifecycleManager` singleton coordinates all lifecycle events. Components auto-register and receive callbacks at appropriate times.
+
+### 2. Sealed Framework Methods
+
+`Awake()` and `OnDestroy()` are sealed. Use `OnManagedAwake()` and `OnManagedDestroy()` instead. Prevents forgetting to call `base.Awake()`.
+
+### 3. Two-Phase Initialization
+
+- **Early (`OnManagedAwake()`)**: During Unity's Awake, before bootstrap. Use for singleton setup.
+- **Late (`OnManagedStart()`)**: After bootstrap completes. All managers guaranteed ready.
+
+### 4. Registration Order Execution
+
+Execution follows Unity's natural Awake order. No priority numbers to manage.
+
+### 5. Automatic Cleanup
+
+Framework handles unregistration automatically. Override `OnManagedDestroy()` only if you need custom cleanup.
+
+---
+
+## Lifecycle Flow Diagrams
+
+### Boot Sequence
+
+![Boot Sequence](../media/boot_sequence.png)
+
+### Scene Transition Flow
+
+![Scene Transition Flow](../media/Scene_transition_flow.png)
+
+### Component Lifecycle (Individual Component)
+
+![Component Lifecycle](../media/component_lifecycle.png)
+
+---
+
+## Class Diagram
+
+![Class Diagram](../media/class_diagram.png)
+
+---
+## Key Guarantees
+
+### Guaranteed
+
+1. **Bootstrap Completion** - `OnManagedStart()` always fires after bootstrap completes
+2. **Manager Availability** - All manager singletons exist when `OnManagedStart()` is called
+3. **Scene Lifecycle** - `OnSceneReady()` fires after scene load, `OnSceneUnloading()` before unload
+4. **Automatic Registration** - Can't forget to register (Awake is sealed)
+5. **Automatic Cleanup** - Can't forget to unregister (OnDestroy is sealed)
+6. **Save/Load Coordination** - All save participants called in one pass
+
+### Not Guaranteed
+
+1. **Initialization Order Between Components** - `OnManagedAwake()` follows Unity's unpredictable Awake order
+2. **Thread Safety** - All methods must run on main thread
+3. **Performance** - Broadcasting to 1000+ components may have overhead
+4. **SaveId Uniqueness** - Developer responsible for unique SaveIds
+
+