Interaction Patterns

Components in PSP don't import each other. Instead, they interact through four patterns—each suited for different scenarios. Choosing the wrong pattern leads to tight coupling, inconsistency, or poor performance.

Decision Table

Hooks: Synchronous Interception

Use hooks when you need to block, modify, or observe an operation as it happens:

• Veto — Block an operation (e.g., "can't complete task, you're over budget")
• Patch — Modify input before it's processed (e.g., auto-add a tag)
• Observe — Run side effects after success (e.g., log to audit)

class BudgetCheckHook:
    def before_complete_task(self, task, context):
        if self.is_over_budget(task.owner_id):
            return Veto("Over budget this week")
        return Allow()

Events: Asynchronous Reactions

Use events when the caller doesn't need to wait for the reaction:

• Side effects — Send notification, update search index
• Fan-out — Multiple components react to one event
• Audit trail — Record what happened for compliance

@event_bus.subscribe(TaskCompleted)
def on_task_completed(event: TaskCompleted):
    if task_has_recurrence(event.task_id):
        create_next_occurrence(event.task_id)

Policies: Centralized Authorization

Use policies when you need consistent permission checks across use cases:

class DeleteTask:
    def execute(self, task_id, actor):
        task = self.repo.get(task_id)
        self.policy.require(actor, "delete", task)  # raises if denied
        self.repo.delete(task_id)

Policies keep permission logic out of use cases. An OwnerOnlyPolicy checks if the actor's ID matches the resource's owner_id.

Queries: Cross-Component Discovery

Use owner_id queries when you need to aggregate data across components:

def export_user_data(owner_id: UUID):
    return {
        "tasks": task_repo.query_by_owner(owner_id),
        "budget": budget_repo.query_by_owner(owner_id),
        "facets": facet_store.list_by_owner(owner_id),
    }

This is the only way to "join" data across components—query each independently with the same owner_id.

Anti-Patterns

Quick Decision Flowchart