Architecture

class Application:
    """
    Central entry point for all interactions with the application,
    whether via web or CLI.
    """

    _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._instance._initialized = False
        return cls._instance

    def __init__(self):
        if hasattr(self, "_initialized") and self._initialized:
            return

        self._container = ServiceContainer()
        self._bundle_manager = BundleManager()
        self._container.set_instance(BundleManager, self._bundle_manager)

        self._initialized = True

    def boot_web(self):
        from framefox.core.kernel import Kernel

        kernel = Kernel(self._container, self._bundle_manager)
        return kernel

    def boot_cli(self):
        registry = CommandRegistry()
        if not hasattr(self, "_cli_loaded"):
            self._bundle_manager.register_bundle_commands(registry)
            self._cli_loaded = True

        return registry

class Kernel:
    """
    The Kernel class is the core of the Framefox framework. It initializes and configures
    the FastAPI application, manages dependency injection, bundles, security services,
    middleware, routing, and static files.
    """

    def __init__(self, container=None, bundle_manager=None) -> None:
        if hasattr(self, "_initialized") and self._initialized:
            return
        self._container = container
        self._bundle_manager = bundle_manager

        try:
            self._settings = Settings()
            self._logger = logging.getLogger("KERNEL")
            self._app = self._create_fastapi_app()
            self._configure_app()
            self._initialized = True

        except SettingsException as e:
            StartupErrorHandler.handle_configuration_error(e)
        except Exception as e:
            self._logger.error(f"Failed to initialize Kernel: {e}")
            raise RuntimeError(f"Kernel initialization failed: {e}") from e

def _configure_app(self) -> None:
    """Configure the FastAPI application"""
    MiddlewareManager(self._app).setup_middlewares()
    self._setup_routing()
    self._setup_static_files()
    self._bundle_manager.boot_bundles(self._container)
    dispatcher.load_listeners()
    self._container.freeze_registry()

    self._logger.debug("Framefox application initialized successfully")
    self._logger.debug("Application configuration complete - registry frozen")

class AbstractBundle(ABC):
    """
    Abstract class that all bundles must implement.
    """

    @property
    @abstractmethod
    def name(self) -> str:
        """Unique name of the bundle"""
        pass

    @property
    def dependencies(self) -> List[str]:
        """List of bundles this bundle depends on"""
        return []

    def register_services(self, container: ServiceContainer) -> None:
        """Registers the bundle's services in the container"""
        pass

    def register_commands(self, registry: CommandRegistry) -> None:
        """Registers the bundle's commands in the registry"""
        pass

    def boot(self, container: ServiceContainer) -> None:
        """Executed after all bundles have been registered"""
        pass

def _setup_routing(self) -> None:
    """Setup routing system and register controllers"""
    router = Router(self._app)
    self._container.set_instance(Router, router)
    router.register_controllers()

    self._logger.debug("Routing system configured")

def resolve_controller(self, controller_name: str) -> Any:
    # Check in mapped name cache
    if controller_name in self._controller_name_to_class:
        controller_class = self._controller_name_to_class[controller_name]
        if controller_class not in self._controller_cache.values():
            self._controller_cache[controller_name] = controller_class
        return self._create_controller_instance(controller_class)

    if controller_name in self._controller_cache:
        controller_class = self._controller_cache[controller_name]
        return self._create_controller_instance(controller_class)

    controller_class = self._load_controller_class(controller_name)
    if controller_class:
        self._controller_cache[controller_name] = controller_class
        return self._create_controller_instance(controller_class)

    searched_paths = [path for path in self._controller_paths.values()]
    raise ControllerNotFoundError(controller_name, searched_paths)

@wraps(func)
async def wrapper(*args, **kwargs):
    controller_instance = args[0] if args else None

    if controller_instance and hasattr(controller_instance, "_container"):
        for param_name, param in original_sig.parameters.items():
            if param_name == "self" or param_name in kwargs:
                continue

            param_type = type_hints.get(param_name)

            if param_type and param_type != type(None):
                if (
                    self._is_fastapi_native_type(param_type)
                    or self._is_pydantic_model(param_type)
                    or self._is_primitive_type(param_type)
                    or self._is_path_parameter(param_name)
                ):
                    continue

                try:
                    service = controller_instance._container.get(param_type)
                    kwargs[param_name] = service
                except Exception as e:
                    # Handle injection failure
                    ...

    return await func(*args, **kwargs)