The Origin: The Twenty-Handler Trap

In one of my earliest distributed bot projects—a Telegram automation service featuring dozens of distinct commands—I found myself facing a classic anti-pattern: authorization checks were being manually copy-pasted across virtually every single command handler.

# play.py
if not (await check_perms(user_id, "play")):
    return await c.reply("Unauthorized access")

# download.py
if not (await check_perms(user_id, "download")):
    return await c.reply("Unauthorized access")

At first glance, this felt harmless. But whenever business requirements shifted—such as introducing tenant-level subscriptions, changing error responses, logging security violations, or altering how roles were resolved from Redis—I had to execute widespread find-and-replace edits across twenty different modules.

Inevitably, human error kicked in: I would fix the logic in eighteen handlers and inadvertently forget two. Users running the forgotten commands continued to experience subtle security bugs, stale permissions, or broken responses.

---

Defining the Single Authority

Instead of relying on search-and-replace, I asked a fundamental architectural question: Who actually owns the truth of command execution?

The handler shouldn’t be responsible for enforcing the operational protocol. The protocol should govern the handler. Authorization, request tracing, and input normalization belong to a single, unified abstraction layer:

from functools import wraps

def require_permission(required_role: str):
    def decorator(handler):
        @wraps(handler)
        async def wrapper(event, context, *args, **kwargs):
            if not await check_permissions(event.sender_id, required_role):
                return await context.reply("Access denied: insufficient privileges")
            return await handler(event, context, *args, **kwargs)
        return wrapper
    return decorator

This simple refactoring established a Single Source of Truth (SSOT): The rule is declared exactly once, and consumers simply reference it declaratively via @require_permission("play").

---

Tangible Engineering Wins

1. Bug fixes happen in one place: A flaw in permission validation or Redis token parsing is resolved in one single function and instantly propagates across all endpoints without manual sweeps.
2. Features become cheap to implement: When we added rate limiting and audit logging to privileged actions, adding that logic to the centralized wrapper took five minutes and protected every endpoint simultaneously.
3. Handlers become lean and declarative: Developers reading the codebase immediately understand the requirements of each command at a glance, without deciphering boilerplate checks.

---

When the Principle Breaks Down: Beware the “God Abstraction”

The Single Source of Truth principle is immensely powerful, but it carries a significant pitfall: Premature Unification.

When two parts of a system look similar by coincidence rather than by intrinsic shared domain logic, forcing them into a single centralized handler introduces dangerous coupling.

For example, unifying user authentication for internal admins and external API consumers into a single function often leads to a spiderweb of conditional statements (if is_admin: ... elif is_api_key: ...). When an abstraction requires a dozen flags to satisfy disparate callers, it is no longer a source of truth—it has become a God Object.

Keep truth unified where the underlying rule is identical, but allow separate concepts to evolve independently.