ADR-004: Controller Architecture and Dependency Graph

Status

Accepted

Context

Initially, Tasteful implemented routes directly within flavor classes. This approach seemed logical - a flavor would contain its configuration, services, repositories, and routes all in one place:

# Original approach - routes directly in flavor
class UserFlavor(BaseFlavor):
    def __init__(self):
        super().__init__()

    @Get("/users/{user_id}")
    async def get_user(self, user_id: int):
        return await self.user_service.get_user(user_id)

However, this approach created several problems:

Dependency Injection Limitations: Routes couldn’t be properly integrated into the dependency injection lifecycle
Service Instance Naming: Variable names for services were auto-generated by regex minimization, making it hard for developers to identify and use them correctly.
Service Coupling: Routes were tightly coupled to the flavor’s specific service instances
Testing Complexity: Difficult to mock dependencies for individual route testing
Flexibility Issues: Routes couldn’t easily use different services or configurations without interfering with the flavor’s core components

We needed an architecture that would:

Decouple routes from flavor lifecycle management
Enable proper dependency injection for routes
Allow routes to use different services or configurations independently
Maintain clear separation between flavor composition and route logic

Decision

We adopted decoupled controller architecture where routes are separated from flavor classes and managed through dedicated controller classes with proper dependency injection.

The New Architecture

Controllers: Handle routes and HTTP logic with injected dependencies

from tasteful.base_flavor import BaseController

class UserController(BaseController):
    def __init__(self, user_service: UserService, auth_service: AuthService):
        super().__init__(prefix="/users", tags=["users"])
        self.user_service = user_service
        self.auth_service = auth_service
    
    @Get("/{user_id}")
    async def get_user(self, user_id: int, request: Request):
        # Route logic with injected services
        user = request.state.user
        return await self.user_service.get_user(user_id, requesting_user=user)
    
    @Post("/")
    async def create_user(self, user_data: UserCreate, request: Request):
        user = request.state.user
        return await self.user_service.create_user(user_data, created_by=user)

Flavors: Compose and configure the complete dependency graph

class UserFlavor(BaseFlavor):
    def __init__(self):
        super().__init__(
            controller=UserController,
            services=[UserService, EmailService],
            repositories=[UserRepository],
            config=UserConfig
        )

Rationale

Why Decouple Controllers from Flavors?

The original approach of embedding routes directly in flavors created several architectural problems: Problem 1: Dependency Injection Lifecycle Issues

# Original problematic approach
class UserFlavor(BaseFlavor):
    def __init__(self):
        self.user_service = UserService()
    
    @Get("/users/{user_id}")
    async def get_user(self, user_id: int):
        # Route tied to flavor's specific service instance
        return await self.user_service.get_user(user_id)

Problem 2: Inflexible Service Usage Routes couldn’t use different configurations or alternative service implementations without modifying the entire flavor. Solution: Controller Decoupling

# New approach - controllers with dependency injection
class UserController(BaseController):
    def __init__(self, user_service: UserService, auth_service: AuthService):
        super().__init__(prefix="/users", tags=["users"])
        self.user_service = user_service  # Explicitly declared variable name with injected dependency
        self.auth_service = auth_service  # Explicitly declared variable name that can use different implementation
    
    @Get("/{user_id}")
    async def get_user(self, user_id: int, request: Request):
        # Route uses injected services, not flavor's fixed instances
        return await self.user_service.get_user(user_id)

Why Flavor as Pure Composition?

Flavors now serve a single, clear purpose: composing the complete dependency graph

class UserFlavor(BaseFlavor):
    """
    A flavor is purely a composition of:
    - Controller (handles routes)
    - Services (business logic)
    - Repositories (data access)
    - Config (configuration)
    """
    def __init__(self):
        super().__init__(
            controller=UserController,
            services=[UserService, EmailService, NotificationService],
            repositories=[UserRepository, AuditRepository],
            config=UserConfig
        )

Why Personal Container per Flavor?

Each flavor gets its own dependency injection scope:

Isolation: Dependencies don’t interfere between flavors
Flexibility: Each flavor can configure its dependencies independently
Testing: Easy to override dependencies for specific flavors
Modularity: Flavors are truly self-contained modules

# Each flavor manages its own dependency graph
class OrderFlavor(BaseFlavor):
    def __init__(self):
        super().__init__(
            controller=OrderController,
            services=[OrderService, PaymentService, InventoryService],
            repositories=[OrderRepository, PaymentRepository],
            config=OrderConfig
        )

# Container automatically wires dependencies within flavor scope
def _register_flavor_dependencies(self, flavor: BaseFlavor) -> None:
    # Controller gets its dependencies injected from flavor's services
    controller_deps = self._resolve_controller_dependencies(
        flavor.controller, 
        available_services=flavor.services,
        available_configs=flavor.config
    )

Consequences

Positive

Proper Separation of Concerns: Controllers handle HTTP logic, flavors handle composition
Dependency Injection Integration: Routes can participate fully in the DI lifecycle
Flexibility: Controllers can use different service implementations without affecting flavor composition
Testability: Easy to mock dependencies and test controllers in isolation
Modularity: Flavors are truly self-contained with their own dependency scopes
Maintainability: Changes to routes don’t interfere with flavor’s core components

Negative

Additional Abstraction Layer: More classes to understand (Controller + Flavor)
Learning Curve: Developers need to understand the controller/flavor separation
Container Complexity: Each flavor manages its own dependency graph

Trade-offs

Flexibility vs. Simplicity: More flexible dependency management but requires understanding two concepts (controllers and flavors)
Decoupling vs. Directness: Better separation of concerns but less direct than having routes in flavors
Testability vs. Setup: Much better testability but requires more initial setup

Migration Benefits

Backward Compatibility: Existing flavors can be gradually migrated
Incremental Adoption: Teams can adopt controller pattern flavor by flavor
Clear Upgrade Path: Simple transformation from flavor routes to controller classes

Design Decisions

ADR-004: Controller Architecture and Dependency Graph

ADR-004: Controller Architecture and Dependency Graph

Status

Context

Decision

The New Architecture

Rationale

Why Decouple Controllers from Flavors?

Why Flavor as Pure Composition?

Why Personal Container per Flavor?

Consequences

Positive

Negative

Trade-offs

Migration Benefits

References

​ADR-004: Controller Architecture and Dependency Graph

​Status

​Context

​Decision

​The New Architecture

​Rationale

​Why Decouple Controllers from Flavors?

​Why Flavor as Pure Composition?

​Why Personal Container per Flavor?

​Consequences

​Positive

​Negative

​Trade-offs

​Migration Benefits

​References

ADR-004: Controller Architecture and Dependency Graph

Status

Context

Decision

The New Architecture

Rationale

Why Decouple Controllers from Flavors?

Why Flavor as Pure Composition?

Why Personal Container per Flavor?

Consequences

Positive

Negative

Trade-offs

Migration Benefits

References