ADR-029: Domain Service Mediation Architecture

Status

Accepted (September 12, 2025)

Context

During comprehensive DDD refactoring (Issue #168), direct integration access was causing significant architectural violations:

• Layer Boundary Violations: CLI, web, and application layers directly importing integration services
• Tight Coupling: Application logic tightly coupled to external system implementations
• Testing Difficulties: Hard to mock external dependencies due to direct integration access
• Maintenance Complexity: Changes to integration patterns required updates across multiple layers
• DDD Compliance: Violated domain-driven design principles by bypassing domain layer

Specific Violations Identified

• CLI commands directly importing GitHub agents and Slack services
• Main application directly accessing Slack integration components
• Features layer bypassing domain services for external operations
• No centralized mediation for external system concerns

Decision

Implement comprehensive domain service mediation for all external system access:

Domain Services Created

1. GitHubDomainService (services/domain/github_domain_service.py)

   • Mediates all GitHub operations (issues, repositories, commits)
   • Provides clean error handling with domain-appropriate exceptions
   • Abstracts GitHub agent implementation details

2. SlackDomainService (services/domain/slack_domain_service.py)

   • Mediates Slack webhook routing and response handling
   • Manages spatial event processing and intent classification
   • Provides orchestration engine integration

3. NotionDomainService (services/domain/notion_domain_service.py)

   • Mediates Notion MCP operations (workspace, database, page management)
   • Provides comprehensive CRUD operations
   • Handles Notion client lifecycle and error boundaries

Implementation Pattern

# Domain Service Pattern
class GitHubDomainService:
    def __init__(self, github_agent: Optional[GitHubAgent] = None):
        self._github_agent = github_agent or GitHubAgent()

    async def get_open_issues(self, project: str, limit: int = 10):
        # Domain-level validation and orchestration
        # Delegate to integration layer
        # Return domain-appropriate results

Layer Access Pattern

• Application Layer: Uses domain services only
• CLI Layer: Uses domain services and orchestration services
• Web Layer: Uses application services (which use domain services)
• Domain Layer: Uses integration services only
• Integration Layer: Accesses external systems only

Consequences

Positive

• Perfect DDD Compliance: Clean layer separation achieved
• Improved Testability: Domain services can be easily mocked
• Reduced Coupling: Application logic decoupled from integration details
• Better Error Handling: Domain-appropriate error boundaries
• Maintainability: Changes to integrations isolated to domain services
• Scalability: Domain services can be optimized independently

Negative

• Additional Abstraction: One more layer of indirection
• Initial Development Overhead: Required comprehensive refactoring
• Dependency Injection Complexity: Some services require multiple dependencies

Migration Impact

• Zero Functionality Regression: All existing workflows preserved
• Perfect Validation: 5/5 validation steps passed during implementation
• Production Ready: Architecture now deployment-ready with confidence

Implementation Evidence

Validation Results (September 12, 2025)

• ✅ All domain services created and functional
• ✅ CLI commands updated to use GitHubDomainService
• ✅ Main application updated to use SlackDomainService
• ✅ Integration access eliminated from core application paths
• ✅ Perfect DDD compliance achieved across all layers

Performance Impact

• Response Time: Maintained (0s for standup workflow)
• Service Startup: Clean initialization with new architecture
• Resource Usage: Efficient operation with domain service layer

Future Considerations

• Additional Domain Services: Can be added following established patterns
• Service Optimization: Individual domain services can be optimized for specific use cases
• Monitoring Integration: Domain services provide natural boundaries for monitoring
• Microservice Evolution: Domain services provide foundation for potential service extraction

References

• Issue #168: STANDUP-REGRESS DDD Refactoring
• Implementation Session: September 12, 2025 (7+ hours)
• Validation Results: Perfect 5/5 step success rate
• Architecture Documentation: docs/architecture/architectural-excellence-milestone.md