Refactor Function for Readability and Testability

Goal: Refactor the selected function for readability and testability without changing its behavior.

Context: This is a production function. Identify the language and framework from the code itself.

Constraints:
- Do not change the function signature
- Do not change returned values
- Do not add new dependencies
- Preserve all existing behavior and edge cases

Steps:
1. Identify code smells (long methods, deep nesting, unclear names)
2. Extract helper functions where appropriate
3. Improve variable and function names
4. Add type annotations if missing
5. Simplify conditional logic

Output format: Return the refactored code with inline comments explaining each change, followed by a summary of what was improved and why.