# ACB Dependency Injection Patterns Guide
**Version:** 1.0
**Last Updated:** 2025-10-29
**Applies To:** session-buddy with ACB/Bevy DI
______________________________________________________________________
## Overview
This guide documents best practices and patterns for using dependency injection (DI) with the ACB (Asynchronous Component Base) framework and Bevy container in session-buddy. These patterns were developed during Week 7 refactoring to address limitations with string-based keys and bevy's async/await handling.
______________________________________________________________________
## Core Principles
### 1. Always Use Type-Based DI Keys
**✅ DO:** Use class types (classes, dataclasses, protocols) as DI keys
**❌ DON'T:** Use string keys or any non-type objects
```python
from dataclasses import dataclass
from acb.depends import depends
# ✅ CORRECT: Type-based key
@dataclass(frozen=True)
class SessionPaths:
claude_dir: Path
logs_dir: Path
paths = SessionPaths.from_home()
depends.set(SessionPaths, paths) # Type-based key
# ❌ WRONG: String-based key
CLAUDE_DIR_KEY = "paths.claude_dir"
depends.set(CLAUDE_DIR_KEY, claude_dir) # Causes TypeError in bevy
```
**Why:** Bevy's DI container uses `issubclass()` for type checking, which requires actual type objects. Strings cause `TypeError: issubclass() arg 2 must be a class`.
### 2. Use Direct Container Access for Singletons
**✅ DO:** Access bevy container directly for singleton services
**❌ DON'T:** Use `depends.get_sync()` from async functions or module level
```python
from bevy import get_container
from acb.depends import depends
# ✅ CORRECT: Direct container access (works everywhere)
def get_service() -> SomeService:
container = get_container()
if SomeService in container.instances:
service = container.instances[SomeService]
if isinstance(service, SomeService):
return service
service = SomeService()
depends.set(SomeService, service)
return service
# ❌ WRONG: depends.get_sync() from async function
async def get_service() -> SomeService:
# RuntimeError: asyncio.run() from running event loop!
service = depends.get_sync(SomeService)
return service
```
**Why:** Bevy's `depends.get_sync()` internally calls `asyncio.run()`, which fails when called from:
- Async functions (already-running event loop)
- Module-level code (during pytest collection)
### 3. Use Frozen Dataclasses for Configuration
**✅ DO:** Use `@dataclass(frozen=True)` for configuration objects
**❌ DON'T:** Use mutable classes or dictionaries
```python
from dataclasses import dataclass
from pathlib import Path
# ✅ CORRECT: Frozen dataclass
@dataclass(frozen=True)
class SessionPaths:
claude_dir: Path
logs_dir: Path
commands_dir: Path
@classmethod
def from_home(cls) -> SessionPaths:
home = Path(os.path.expanduser("~"))
claude_dir = home / ".claude"
return cls(
claude_dir=claude_dir,
logs_dir=claude_dir / "logs",
commands_dir=claude_dir / "commands",
)
# ❌ WRONG: Mutable configuration
class SessionPaths:
def __init__(self):
self.claude_dir = Path.home() / ".claude"
self.logs_dir = self.claude_dir / "logs"
```
**Why:** Frozen dataclasses provide:
- Immutability (thread-safe)
- Hashability (can be dict keys)
- Type safety (compile-time checking)
- Clear intent
______________________________________________________________________
## Pattern Catalog
### Pattern 1: Type-Safe Configuration
**Use Case:** Registering multiple related configuration values
**Implementation:**
```python
# session_buddy/di/config.py
from dataclasses import dataclass
from pathlib import Path
import os
@dataclass(frozen=True)
class SessionPaths:
"""Type-safe path configuration for session management."""
claude_dir: Path
logs_dir: Path
commands_dir: Path
@classmethod
def from_home(cls, home: Path | None = None) -> SessionPaths:
"""Create from home directory with env var support."""
if home is None:
home = Path(os.path.expanduser("~")) # Respects HOME env var
claude_dir = home / ".claude"
return cls(
claude_dir=claude_dir,
logs_dir=claude_dir / "logs",
commands_dir=claude_dir / "commands",
)
def ensure_directories(self) -> None:
"""Create all directories if they don't exist."""
self.claude_dir.mkdir(parents=True, exist_ok=True)
self.logs_dir.mkdir(parents=True, exist_ok=True)
self.commands_dir.mkdir(parents=True, exist_ok=True)
# session_buddy/di/__init__.py
from acb.depends import depends
from .config import SessionPaths
def configure(*, force: bool = False) -> None:
"""Register default dependencies."""
# Register type-safe configuration
paths = SessionPaths.from_home()
paths.ensure_directories()
depends.set(SessionPaths, paths)
# Use configuration in service registration
_register_logger(paths.logs_dir, force)
_register_permissions(paths.claude_dir, force)
```
**Benefits:**
- Single source of truth for paths
- Type-safe access with IDE support
- Easy to test with custom paths
- No string key confusion
### Pattern 2: Direct Container Access for Singletons
**Use Case:** Accessing singleton services reliably from any context
**Implementation:**
```python
from typing import TYPE_CHECKING
from bevy import get_container
from acb.depends import depends
if TYPE_CHECKING:
from session_buddy.core import SessionLifecycleManager
def get_session_manager() -> SessionLifecycleManager:
"""Get or create SessionLifecycleManager instance.
Note:
Uses direct container access to avoid bevy's async event
loop issues when called from async contexts or module level.
"""
from session_buddy.core import SessionLifecycleManager
# Check container directly (no async issues)
container = get_container()
if SessionLifecycleManager in container.instances:
manager = container.instances[SessionLifecycleManager]
if isinstance(manager, SessionLifecycleManager):
return manager
# Create and register if not found
manager = SessionLifecycleManager()
depends.set(SessionLifecycleManager, manager)
return manager
# Works from anywhere:
async def some_async_function():
manager = get_session_manager() # ✅ No RuntimeError
def some_sync_function():
manager = get_session_manager() # ✅ Works
# Module level
session_manager = get_session_manager() # ✅ Works during import
```
**Benefits:**
- No async event loop issues
- Works from async, sync, and module level
- Faster than full DI resolution
- More predictable behavior
### Pattern 3: Lazy Singleton Initialization
**Use Case:** Creating expensive services on-demand
**Implementation:**
```python
async def get_reflection_database() -> ReflectionDatabase | None:
"""Resolve reflection database via DI, creating it on demand."""
try:
from session_buddy.reflection_tools import ReflectionDatabase
from session_buddy.reflection_tools import (
get_reflection_database as load_database,
)
except ImportError:
return None
# Check if already registered
container = get_container()
if ReflectionDatabase in container.instances:
db = container.instances[ReflectionDatabase]
if isinstance(db, ReflectionDatabase):
return db
# Expensive initialization only happens once
db = await load_database()
depends.set(ReflectionDatabase, db)
return db
```
**Benefits:**
- Deferred initialization until first use
- Singleton behavior maintains single instance
- Graceful handling of import errors
- Async-safe initialization
### Pattern 4: Environment-Aware Configuration
**Use Case:** Test-friendly configuration that respects environment variables
**Implementation:**
```python
import os
from pathlib import Path
from dataclasses import dataclass
@dataclass(frozen=True)
class SessionPaths:
claude_dir: Path
logs_dir: Path
@classmethod
def from_home(cls, home: Path | None = None) -> SessionPaths:
"""Create from home directory.
Args:
home: Optional home path. If None, uses expanduser("~")
which respects the HOME environment variable.
Note:
Use os.path.expanduser("~") instead of Path.home()
because expanduser respects environment variables,
making it test-friendly with pytest's monkeypatch.
"""
if home is None:
# ✅ Respects HOME environment variable
home = Path(os.path.expanduser("~"))
claude_dir = home / ".claude"
return cls(
claude_dir=claude_dir,
logs_dir=claude_dir / "logs",
)
# In tests:
def test_paths_respect_home_env(monkeypatch, tmp_path):
monkeypatch.setenv("HOME", str(tmp_path))
paths = SessionPaths.from_home()
assert paths.claude_dir == tmp_path / ".claude" # ✅ Works
```
**Benefits:**
- Test isolation via environment variables
- Works in Docker containers
- Supports custom home directories
- No hardcoded paths
### Pattern 5: Service Registration with Dependencies
**Use Case:** Registering services that depend on configuration
**Implementation:**
```python
def configure(*, force: bool = False) -> None:
"""Register default dependencies."""
# Register configuration first
paths = SessionPaths.from_home()
paths.ensure_directories()
depends.set(SessionPaths, paths)
# Register services with explicit dependencies
_register_logger(paths.logs_dir, force)
_register_permissions(paths.claude_dir, force)
_register_lifecycle(force)
def _register_logger(logs_dir: Path, force: bool) -> None:
"""Register SessionLogger with explicit path dependency.
Note:
Accepts Path directly instead of resolving from DI,
making dependencies explicit and easier to test.
"""
from session_buddy.utils.logging import SessionLogger
if not force:
# Check if already registered
container = get_container()
if SessionLogger in container.instances:
return
logger = SessionLogger(logs_dir)
depends.set(SessionLogger, logger)
```
**Benefits:**
- Explicit dependencies (no hidden coupling)
- Easier to test (just pass paths)
- Clear initialization order
- Follows dependency inversion principle
______________________________________________________________________
## Anti-Patterns to Avoid
### Anti-Pattern 1: String-Based DI Keys
**❌ DON'T DO THIS:**
```text
# Using strings as DI keys
CLAUDE_DIR_KEY = "paths.claude_dir"
depends.set(CLAUDE_DIR_KEY, claude_dir)
# Later...
claude_dir = depends.get_sync(CLAUDE_DIR_KEY)
# TypeError: issubclass() arg 2 must be a class
```
**✅ DO THIS INSTEAD:**
```text
@dataclass(frozen=True)
class SessionPaths:
claude_dir: Path
paths = SessionPaths.from_home()
depends.set(SessionPaths, paths)
# Later...
paths = depends.get_sync(SessionPaths) # ✅ Type-safe
claude_dir = paths.claude_dir
```
### Anti-Pattern 2: Using `depends.get_sync()` in Async Contexts
**❌ DON'T DO THIS:**
```python
async def get_service() -> SomeService:
# RuntimeError: asyncio.run() from running event loop!
service = depends.get_sync(SomeService)
return service
```
**✅ DO THIS INSTEAD:**
```python
async def get_service() -> SomeService:
container = get_container()
if SomeService in container.instances:
service = container.instances[SomeService]
if isinstance(service, SomeService):
return service
service = SomeService()
depends.set(SomeService, service)
return service
```
### Anti-Pattern 3: Mutable Configuration Objects
**❌ DON'T DO THIS:**
```text
class SessionPaths:
def __init__(self):
self.claude_dir = Path.home() / ".claude"
self.logs_dir = self.claude_dir / "logs"
paths = SessionPaths()
paths.claude_dir = Path("/tmp") # ❌ Mutable, not thread-safe
```
**✅ DO THIS INSTEAD:**
```text
@dataclass(frozen=True)
class SessionPaths:
claude_dir: Path
logs_dir: Path
paths = SessionPaths(claude_dir=..., logs_dir=...)
# paths.claude_dir = Path("/tmp") # ✅ Error: frozen
```
### Anti-Pattern 4: Module-Level `depends.get_sync()` Calls
**❌ DON'T DO THIS:**
```python
# module_level.py
from acb.depends import depends
# Called during import - can fail in pytest collection
service = depends.get_sync(SomeService)
def use_service():
return service.do_something()
```
**✅ DO THIS INSTEAD:**
```python
# module_level.py
from bevy import get_container
def _get_service() -> SomeService:
container = get_container()
if SomeService in container.instances:
service = container.instances[SomeService]
if isinstance(service, SomeService):
return service
service = SomeService()
depends.set(SomeService, service)
return service
# Lazy initialization on first use
def use_service():
service = _get_service()
return service.do_something()
```
______________________________________________________________________
## Testing Patterns
### Pattern 1: Injecting Test Dependencies
```text
import pytest
from acb.depends import depends
from bevy import get_container
@pytest.fixture(autouse=True)
def reset_di():
"""Reset DI state after each test."""
yield
# Clean up registered instances
container = get_container()
for cls in [SessionLogger, SessionPermissionsManager]:
with suppress(KeyError):
container.instances.pop(cls, None)
def test_with_custom_paths(tmp_path, monkeypatch):
"""Test with custom path configuration."""
monkeypatch.setenv("HOME", str(tmp_path))
# Register test configuration
paths = SessionPaths.from_home()
depends.set(SessionPaths, paths)
# Test uses custom paths
assert paths.claude_dir == tmp_path / ".claude"
```
### Pattern 2: Mocking Singleton Services
```python
def test_with_mock_service():
"""Test with mocked singleton service."""
from unittest.mock import Mock
# Create mock
mock_service = Mock(spec=SomeService)
mock_service.do_something.return_value = "mocked"
# Register mock in DI
depends.set(SomeService, mock_service)
# Test uses mock
result = function_that_uses_service()
assert result == "mocked"
mock_service.do_something.assert_called_once()
```
______________________________________________________________________
## Migration Guide
### Migrating from String Keys to Type-Based Keys
**Step 1:** Create configuration dataclass
```python
@dataclass(frozen=True)
class MyConfig:
setting1: str
setting2: int
```
**Step 2:** Update registration
```python
# Before
depends.set("config.setting1", "value")
depends.set("config.setting2", 42)
# After
config = MyConfig(setting1="value", setting2=42)
depends.set(MyConfig, config)
```
**Step 3:** Update access
```python
# Before
setting1 = depends.get_sync("config.setting1")
# After
config = depends.get_sync(MyConfig)
setting1 = config.setting1
```
______________________________________________________________________
## Performance Considerations
### Direct Container Access vs DI Resolution
**Benchmark Results:**
- Direct container access: ~0.1μs (dictionary lookup)
- `depends.get_sync()`: ~5-10μs (includes async machinery overhead)
**Recommendation:** Use direct container access for hot paths and singleton services.
### Memory Usage
- Frozen dataclasses: Minimal overhead vs regular classes
- Singleton pattern: One instance per service (memory efficient)
- Type-based keys: No additional memory vs string keys
______________________________________________________________________
## Summary
**Key Takeaways:**
1. Always use type-based DI keys (classes, dataclasses)
1. Use direct container access for singletons
1. Use frozen dataclasses for configuration
1. Respect environment variables for test-friendliness
1. Make dependencies explicit in function signatures
**When to Use Each Pattern:**
- **Type-Safe Configuration:** Grouping related configuration values
- **Direct Container Access:** Singleton services in any context
- **Lazy Initialization:** Expensive services that may not be needed
- **Environment-Aware Config:** Test-friendly path resolution
- **Explicit Dependencies:** Service registration with clear dependencies
______________________________________________________________________
**Version History:**
- 1.0 (2025-10-29): Initial version based on Week 7 refactoring
**Author:** Claude Code + Les
**Project:** session-buddy
**Framework:** ACB (Asynchronous Component Base) with Bevy DI
