From 865d7477b61a91d756810ec60de69cd570e7cc66 Mon Sep 17 00:00:00 2001
From: Joe Particle <joe@particle-os.local>
Date: Wed, 16 Jul 2025 20:47:31 +0000
Subject: [PATCH] docs: add full dbus-next migration plan to eliminate
 architectural impedance mismatch

---
 TODO.md                        | 18 ++++++++++++++++++
 src/apt-ostree.py/CHANGELOG.md |  3 ++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/TODO.md b/TODO.md
index 1d5032c..e282838 100644
--- a/TODO.md
+++ b/TODO.md
@@ -153,6 +153,24 @@
 
 ## Next Phase 🎯
 
+### Full dbus-next Migration & Architecture Decoupling (PLANNED)
+- 🎯 **Phase 1: Foundation & Core Decoupling**
+  - Create centralized `AptOstreeDaemon` class with pure Python logic (no D-Bus dependencies)
+  - Consolidate D-Bus setup in main entry point (`apt_ostree_new.py` or similar)
+  - Refine `interface_simple.py` to pure D-Bus interface definitions using `dbus-next`
+  - Eliminate circular imports and architectural impedance mismatch
+- 🎯 **Phase 2: Implementing dbus-next Correctly & Decoupling Logic**
+  - Implement all D-Bus properties using `@dbus_property` decorators
+  - Correctly define and emit D-Bus signals using `@signal()` and `.emit()`
+  - Integrate progress callbacks into `ShellIntegration` for real-time updates
+  - Refactor methods for proper asynchronous operations with `asyncio`
+  - Remove all legacy `dbus-python` code and hybrid patterns
+- 🎯 **Phase 3: Testing & Cleanup**
+  - Implement comprehensive integration tests using `dbus-next` as client
+  - Service activation, introspection, method call, and signal monitoring tests
+  - Remove obsolete code and legacy D-Bus interfaces
+  - Establish clean, maintainable architecture for future development
+
 ### Production Readiness
 - ✅ **Systemd Integration**: Complete systemd service file and unit configuration
   - Service file with security hardening and OSTree integration
diff --git a/src/apt-ostree.py/CHANGELOG.md b/src/apt-ostree.py/CHANGELOG.md
index 5cc53d8..628eaf1 100644
--- a/src/apt-ostree.py/CHANGELOG.md
+++ b/src/apt-ostree.py/CHANGELOG.md
@@ -1,2 +1,3 @@
 ## [Unreleased]
-- D-Bus signal emission implemented: TransactionProgress, PropertyChanged, and StatusChanged signals are now emitted from interface_simple.py for all relevant methods (InstallPackages, RemovePackages, Deploy, Upgrade, Rollback, GetStatus). 
\ No newline at end of file
+- D-Bus signal emission implemented: TransactionProgress, PropertyChanged, and StatusChanged signals are now emitted from interface_simple.py for all relevant methods (InstallPackages, RemovePackages, Deploy, Upgrade, Rollback, GetStatus).
+- **PLANNED: Full dbus-next Migration & Architecture Decoupling** - Comprehensive plan to eliminate hybrid dbus-python/dbus-next architecture, establish clean separation of concerns, and create maintainable D-Bus interface using modern async patterns. 
\ No newline at end of file