migrazione verso gitea

docs/flows/gestione_aree_frame_async_flow.md

@@ -0,0 +1,45 @@
+# `gestione_aree_frame_async.py`
+
+## Scopo
+
+Questo modulo fornisce l'infrastruttura async usata dalle finestre GUI:
+
+- loop asincrono globale;
+- overlay di attesa;
+- runner che collega coroutine e callback Tk.
+
+## Flusso infrastrutturale
+
+```{mermaid}
+flowchart TD
+    A["Metodo finestra GUI"] --> B["AsyncRunner.run(awaitable)"]
+    B --> C{"busy overlay richiesto?"}
+    C -- Si --> D["BusyOverlay.show()"]
+    C -- No --> E["Salta overlay"]
+    D --> F["run_coroutine_threadsafe(awaitable, loop globale)"]
+    E --> F
+    F --> G["Polling del Future"]
+    G --> H{"Future completato?"}
+    H -- No --> G
+    H -- Si --> I{"Successo o errore?"}
+    I -- Successo --> J["widget.after(..., on_success)"]
+    I -- Errore --> K["widget.after(..., on_error)"]
+    J --> L["BusyOverlay.hide()"]
+    K --> L
+```
+
+## Schema di componenti
+
+```{mermaid}
+flowchart LR
+    Holder["_LoopHolder"] --> Loop["get_global_loop"]
+    Loop --> Runner["AsyncRunner"]
+    Overlay["BusyOverlay"] --> Runner
+    Runner --> GUI["Moduli GUI"]
+```
+
+## Note
+
+- Il modulo fa da ponte tra thread Tk e thread del loop asincrono.
+- `BusyOverlay` e riusato da piu finestre, quindi e un componente condiviso.
+- `AsyncRunner` evita che i moduli GUI gestiscano direttamente i `Future`.