feat: Introduce capability-driven architecture by removing placeholder broker services and simplifying registration. (#296)

This allows that when running only with brokers like 'Bitvavo', the features that are not supported, like 'Dividends' are hidden.

Author: ctasada

CHANGELOG.md

@@ -19,6 +19,8 @@ _This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) a
 ### Changed
 
 - **Configuration:** Different UI/UX improvements
+- **Brokers:** Hidden not supported broker capabilities
+  - When a broker does not support a certain feature, it will not be shown in the UI
 
 ### Fixed
 

docs/ARCHITECTURE.md

@@ -89,6 +89,16 @@ class BrokerRegistry:
 - Dynamic broker registration
 - Configuration validation on startup
 
+### Capability-Driven Architecture
+
+The system uses a capability-based discovery mechanism. Brokers are not required to implement all service interfaces; they only implement those that they actually support.
+
+**Key Features**:
+- **Dynamic Discovery**: The `BrokerRegistry` tracks which services each broker provides.
+- **Graceful Adaptation**: Aggregator services automatically skip brokers that don't support a requested feature.
+- **Adaptive UI**: The frontend dynamically hides navigation links (e.g., "Dividends", "Fees") if the currently selected portfolio doesn't support them.
+- **Lean Implementation**: Reduces boilerplate by eliminating "hollow" services that only return empty data.
+
 ### Exception Management
 
 Professional exception hierarchy with structured error handling:

docs/ARCHITECTURE_BROKERS.md

@@ -346,12 +346,22 @@ BROKER_CONFIGS = {
             # ServiceType.DIVIDEND: NewBrokerDividendService,
             # ServiceType.FEE: NewBrokerFeeService,
         },
-        "supports_complete_registration": True,  # Set to False if missing required services
     },
 }
 ```
 
-### 5. Add Credential Support (Optional)
+### 5. Dynamic Capabilities Support
+
+Stonks Overwatch uses a capability-based architecture. You only need to register the services that your broker actually supports.
+
+- **Required**: `ServiceType.PORTFOLIO` is the only strictly required service.
+- **Optional**: `TRANSACTION`, `ACCOUNT`, `DEPOSIT`, `DIVIDEND`, `FEE`, and `AUTHENTICATION` are optional.
+
+The application automatically handles missing services:
+1. **Backend**: Aggregator services skip brokers that don't provide the requested service.
+2. **Frontend**: The sidebar navigation dynamically hides links (e.g., "Dividends", "Fees") if the currently selected portfolio doesn't support them.
+
+### 6. Add Credential Support (Optional)
 
 If your broker needs credential update functionality, add it to the BrokerFactory mapping:
 

src/stonks_overwatch/config/config.py

@@ -5,6 +5,7 @@
 from stonks_overwatch.config.base_config import BaseConfig
 from stonks_overwatch.constants import BrokerName
 from stonks_overwatch.core.factories.broker_factory import BrokerFactory
+from stonks_overwatch.core.service_types import ServiceType
 from stonks_overwatch.services.models import PortfolioId
 from stonks_overwatch.utils.core.logger import StonksLogger
 from stonks_overwatch.utils.core.logger_constants import LOGGER_CONFIG, TAG_CONFIG
@@ -81,6 +82,28 @@ def _is_broker_enabled(self, broker_name: BrokerName) -> bool:
         config = self.get_broker_config(broker_name)
         return config.is_enabled() if config else False
 
+    def get_capabilities(self, portfolio_id: PortfolioId) -> list[ServiceType]:
+        """
+        Get the capabilities (service types) for a portfolio.
+
+        Args:
+            portfolio_id: The portfolio to get capabilities for
+
+        Returns:
+            List of supported ServiceType enums
+        """
+        if portfolio_id == PortfolioId.ALL:
+            capabilities = set()
+            for broker_name in self._factory.get_available_brokers():
+                if self._is_broker_enabled(broker_name):
+                    capabilities.update(self._factory.get_broker_capabilities(broker_name))
+            return sorted(capabilities, key=lambda x: x.value)
+
+        if portfolio_id.broker_name:
+            return self._factory.get_broker_capabilities(portfolio_id.broker_name)
+
+        return []
+
     def __eq__(self, value: object) -> bool:
         if isinstance(value, Config):
             if self.base_currency != value.base_currency:

src/stonks_overwatch/core/aggregators/base_aggregator.py

@@ -172,7 +172,10 @@ def _collect_broker_data(self, selected_portfolio: PortfolioId, method_name: str
         """
         enabled_brokers = self._get_enabled_brokers(selected_portfolio)
         if not enabled_brokers:
-            raise DataAggregationException("Failed to find any enabled broker")
+            self._logger.debug(
+                f"No brokers enabled for service {self._service_type.value} with selection {selected_portfolio}"
+            )
+            return {}
 
         broker_data = {}
         broker_errors = {}

src/stonks_overwatch/core/registry_setup.py

@@ -40,9 +40,6 @@
     BitvavoAuthenticationService = None
 
 from stonks_overwatch.services.brokers.bitvavo.services.deposit_service import DepositsService as BitvavoDepositService
-from stonks_overwatch.services.brokers.bitvavo.services.dividends_service import (
-    DividendsService as BitvavoDividendsService,
-)
 from stonks_overwatch.services.brokers.bitvavo.services.fee_service import FeeService as BitvavoFeeService
 from stonks_overwatch.services.brokers.bitvavo.services.portfolio_service import (
     PortfolioService as BitvavoPortfolioService,
@@ -80,11 +77,9 @@
     logger.warning(f"Could not import IbkrAuthenticationService: {e}")
     IbkrAuthenticationService = None
 
-from stonks_overwatch.services.brokers.ibkr.services.deposit_service import DepositsService as IbkrDepositService
 from stonks_overwatch.services.brokers.ibkr.services.dividends import (
     DividendsService as IbkrDividendsService,
 )
-from stonks_overwatch.services.brokers.ibkr.services.fee_service import FeeService as IbkrFeeService
 from stonks_overwatch.services.brokers.ibkr.services.portfolio import (
     PortfolioService as IbkrPortfolioService,
 )
@@ -105,33 +100,27 @@
             ServiceType.ACCOUNT: DeGiroAccountService,
             ServiceType.AUTHENTICATION: DegiroAuthenticationService,
         },
-        "supports_complete_registration": True,
     },
     BrokerName.BITVAVO: {
         "config": BitvavoConfig,
         "services": {
             ServiceType.PORTFOLIO: BitvavoPortfolioService,
             ServiceType.TRANSACTION: BitvavoTransactionService,
             ServiceType.DEPOSIT: BitvavoDepositService,
-            ServiceType.DIVIDEND: BitvavoDividendsService,
             ServiceType.FEE: BitvavoFeeService,
             ServiceType.ACCOUNT: BitvavoAccountService,
             ServiceType.AUTHENTICATION: BitvavoAuthenticationService,
         },
-        "supports_complete_registration": True,
     },
     BrokerName.IBKR: {
         "config": IbkrConfig,
         "services": {
             ServiceType.PORTFOLIO: IbkrPortfolioService,
             ServiceType.TRANSACTION: IbkrTransactionService,
-            ServiceType.DEPOSIT: IbkrDepositService,
             ServiceType.DIVIDEND: IbkrDividendsService,
-            ServiceType.FEE: IbkrFeeService,
             ServiceType.ACCOUNT: IbkrAccountOverviewService,
             ServiceType.AUTHENTICATION: IbkrAuthenticationService,
         },
-        "supports_complete_registration": True,  # Now supports all required services
     },
 }
 
@@ -177,24 +166,15 @@ def register_all_brokers() -> None:
         try:
             config_class = broker_config["config"]
             services = broker_config["services"]
-            supports_complete = broker_config.get("supports_complete_registration", False)
-
-            if supports_complete:
-                # Use complete registration for brokers with all required services
-                registry.register_complete_broker(
-                    broker_name,
-                    config_class,
-                    **{service_type.value: service_class for service_type, service_class in services.items()},
-                )
-                logger.debug(f"Registered {broker_name} broker using complete registration")
-            else:
-                # Use separate registration for brokers missing required services
-                registry.register_broker_config(broker_name, config_class)
-                registry.register_broker_services(
-                    broker_name,
-                    **{service_type.value: service_class for service_type, service_class in services.items()},
-                )
-                logger.debug(f"Registered {broker_name} broker using separate registration")
+
+            # Register configuration and services together
+            # This is cleaner and includes automatic rollback on failure
+            registry.register_complete_broker(
+                broker_name,
+                config_class,
+                **{service_type.value: service_class for service_type, service_class in services.items()},
+            )
+            logger.debug(f"Registered {broker_name} broker successfully")
 
             successfully_registered.append(broker_name)
 
@@ -256,22 +236,13 @@ def ensure_registry_initialized() -> None:
         try:
             config_class = broker_config["config"]
             services = broker_config["services"]
-            supports_complete = broker_config.get("supports_complete_registration", False)
-
-            if supports_complete:
-                registry.register_complete_broker(
-                    broker_name,
-                    config_class,
-                    **{service_type.value: service_class for service_type, service_class in services.items()},
-                )
-                logger.debug(f"Registered {broker_name} broker successfully")
-            else:
-                registry.register_broker_config(broker_name, config_class)
-                registry.register_broker_services(
-                    broker_name,
-                    **{service_type.value: service_class for service_type, service_class in services.items()},
-                )
-                logger.debug(f"Registered {broker_name} broker successfully (separate registration)")
+
+            registry.register_complete_broker(
+                broker_name,
+                config_class,
+                **{service_type.value: service_class for service_type, service_class in services.items()},
+            )
+            logger.debug(f"Registered {broker_name} broker successfully")
 
         except Exception as e:
             logger.warning(f"Failed to register {broker_name}: {e}")