add guardian documentation section

docs/cgr-engine.rst

@@ -82,6 +82,7 @@ The components from the diagram can be found documented in the links bellow:
    apiers
    loaders
    caches
+   guardian
    datadb
    stordb
    rpcconns

docs/guardian.rst

@@ -0,0 +1,39 @@
+.. _guardian:
+
+Guardian
+========
+
+Guardian is CGRateS' internal locking mechanism that ensures data consistency during concurrent operations.
+
+What Guardian Does
+------------------
+
+Guardian prevents race conditions when multiple processes try to access or modify the same data. It uses string-based locks, typically created using some variation of the tenant and ID of the resource being protected, often with a type prefix. Guardian can use either explicit IDs or generate UUIDs internally for reference-based locking when no specific ID is provided.
+
+When CGRateS Uses Guardian
+--------------------------
+
+Guardian protects:
+
+* Account balance operations (debits/topups) - the most critical use case
+* ResourceProfiles, Resources, StatQueueProfiles, StatQueues, ThresholdProfiles, and Thresholds while they're being used or loaded into cache
+* Filter index updates
+* There are other cases, but the ones listed above are the most frequent applications
+
+Performance Implications
+------------------------
+
+Guardian affects system performance in these ways:
+
+* Operations on the same resource are processed one after another, not simultaneously
+* Under heavy load on the same resources, operations may queue up and wait
+* System throughput is better when operations are distributed across different resources
+
+Configuration
+-------------
+
+Guardian has a single configuration option:
+
+The `locking_timeout` setting in the general configuration determines how long Guardian will hold a lock before forcing it to release. Zero timeout (no timeout) is the default and recommended setting. However, setting a reasonable timeout can help prevent system hangs if a process fails to release a lock.
+
+When a timeout occurs, Guardian logs a warning and forces the lock to release. This keeps the system running, but the operation that timed out may fail.