Decorators

Decorators (atlas.decorators) is the package containing layer-specific decorators designed to standardize error handling, session management, and response formatting across the architectural layers — Controller, Service, and Repository.

Each decorator encapsulates the cross-cutting concerns relevant to its layer, ensuring consistent behavior, clean separation of responsibilities, and reduced boilerplate code.

Below are the descriptions of each decorator.

controller_method

@controller_method is a decorator designed for functions within the Controller layer, typically used to wrap AWS Lambda handlers or HTTP entry points. It provides a standardized mechanism for request parsing, validation, and exception handling, ensuring that all controller methods return a consistent HttpResponse format.

This decorator automatically

• Wraps the controller method in a structured error-handling layer.
• Converts event payloads into HttpRequest instances when the method signature includes a req parameter.
• Catches and formats all expected application and validation errors into standardized JSON responses.
• Returns a HttpResponse dictionary compatible with AWS Lambda’s API Gateway integration.

The decorator acts as the Controller layer boundary, isolating business logic from infrastructure concerns such as serialization, error formatting, and validation reporting.

Parameters:

Name	Type	Description	Default
func	Callable	The controller function being decorated. This function may optionally accept a req: HttpRequest parameter, which will be automatically constructed from the Lambda event payload.	required

Returns:

Name	Type	Description
Callable		A wrapped function that executes the controller logic with standardized error handling.

The decorator maps exceptions to HTTP responses as follows

• JSONDecodeError (400) → Invalid JSON body in the incoming request.
• ValidationError (422) → Pydantic validation errors, formatted using ValidationErrorFormatter.
• BadRequestError (4xx) → Explicit user-side errors, reported with details if provided.
• DatabaseError (5xx) → Errors originating from the Repository layer.
• HttpError (4xx–5xx) → Service-layer errors encapsulated in HTTP-compatible form.
• Exception (500) → Unhandled or unexpected errors, returned as internal server errors.

service_method

@service_method is a decorator designed for functions within the Service layer, typically applied to methods of classes that extend the base Service. It ensures transactional integrity by managing the lifecycle of the database session for each service call.

Service calls can be made inside another service call as a session stack, but only the first call (which will trigger the first/root database session creation) will trigger the transactions commit - the first/root database session closure.

This decorator automatically

• Ensures a valid database session is available for the duration of the method call.
• Commits the transaction if the method completes successfully.
• Rolls back the transaction if an exception occurs.
• Closes and unbinds the session after execution to prevent connection leaks.
• Propagates service-level errors as structured HttpError or DatabaseError exceptions.

The decorator acts as the Service layer boundary, encapsulating transactional control and database consistency for business logic operations executed through repositories.

Parameters:

Name	Type	Description	Default
func	Callable	The service method being decorated. This function is typically defined inside a subclass of Service and may perform one or more repository operations within a transactional context.	required

Returns:

Name	Type	Description
Callable		A wrapped function that executes the service logic with automatic
		session management and error propagation.

Raises:

Type	Description
HttpError	If an unexpected error occurs during service execution, wrapping the original exception.
DatabaseError	If a commit or rollback operation fails.
RuntimeError	If the database session factory is not properly configured.

The decorator handles exceptions as follows

• HttpError → Propagates known service-level HTTP errors as-is.
• DatabaseError → Raised if session commit or rollback fails.
• RuntimeError → Raised if no session factory is available in SessionManager.
• Exception → Any other unexpected error is wrapped as HttpError (500).

repository_method

@repository_method is a decorator designed for functions within the Repository layer, typically applied to data access methods of classes that extend the base Repository. It provides a standardized mechanism for capturing and converting low-level database exceptions into a consistent error format.

This decorator automatically

• Wraps repository methods in a structured error-handling layer.
• Catches all unhandled exceptions raised during database access or query execution.
• Converts those exceptions into DatabaseError instances, ensuring consistent propagation to the Service layer.
• Enforces a clear separation between domain logic and data persistence concerns.

The decorator acts as the Repository layer boundary, ensuring that only standardized DatabaseError exceptions cross the persistence boundary and preventing leakage of raw database driver or ORM exceptions into upper layers.

Parameters:

Name	Type	Description	Default
func	Callable	The repository function being decorated. This function typically performs direct SQLAlchemy operations such as queries, inserts, updates, or deletes.	required

Returns:

Name	Type	Description
Callable		A wrapped function that executes the repository logic with consistent
		error conversion and propagation.

Raises:

Type	Description
DatabaseError	When an unexpected error occurs during database access, wrapping the

The decorator maps exceptions as follows

• Exception → DatabaseError (5xx) → Raised for any unhandled database or ORM error. The exception message includes the original error type and description.