design-pattern-facade

Skill: Facade

Intent

Provide a simplified high-level interface to a complex subsystem so most clients can execute common workflows without understanding internal coordination details.

Applicability Signals

• Signal 1: Client code repeatedly orchestrates multiple subsystem components in the same sequence.
• Signal 2: Subsystem APIs are noisy/volatile and leak implementation complexity.
• Signal 3: Onboarding and maintenance cost is high due to broad subsystem surface area exposure.

Contraindications

• Case 1: Clients need fine-grained control over subsystem internals for most use cases.
• Case 2: A facade would become a massive god-object that mirrors every underlying method.
• Case 3: Subsystem is already cohesive and simple enough for direct use.

Decision Heuristics

• If recurring use cases can be expressed as a smaller stable API over complex internals, prefer Facade.
• If the main issue is incompatible interfaces rather than complexity, Adapter is a better fit.
• Decision anti-bias note: do not treat facade as a permanent substitute for fixing poor subsystem boundaries.

Implementation Checklist

• Identify top user workflows and collapse them into concise facade operations.
• Keep direct subsystem access available for advanced callers when necessary.
• Delegate orchestration logic to facade while preserving subsystem separation.
• Define clear error translation and transaction/boundary behavior.
• Test facade flows and compatibility with evolving subsystem internals.

Misuse Checks

• Misuse 1: Facade mirrors every subsystem method 1:1 → Remediation: prune to high-value workflow methods.
• Misuse 2: Facade embeds business rules unrelated to orchestration → Remediation: push domain logic back into domain/service layer.
• Misuse 3: All clients forced through facade despite advanced needs → Remediation: expose explicit escape hatch for specialized cases.

Verification Rubric

• Correctness:
  • Common workflow succeeds through facade without direct subsystem calls.
  • Facade handles subsystem error propagation consistently.
• Design quality:
  • Facade API is significantly smaller and clearer than raw subsystem API.
  • Subsystem components remain decoupled and testable independently.
• Regression safety:
  • Tests cover at least one standard workflow and one subsystem change with unchanged facade contract.

Language-Specific Adaptations (Optional)

• TypeScript: model facade as service class with explicit dependency injection of subsystem collaborators.
• Python: module-level facade functions can work for lightweight orchestration cases.
• Go: small facade struct with narrow methods and explicit dependencies is preferred.

Related Patterns (Optional)

• Adapter: converts one interface to another; facade simplifies many interfaces.
• Mediator: centralizes peer interactions; facade centralizes client-to-subsystem entry.

Attribution & Sources

• Source Site: Refactoring.Guru
• Source URLs:
  • https://refactoring.guru/design-patterns/facade
  • https://refactoring.guru/design-patterns
• Derivation Note: Concepts derived from referenced sources; explanatory wording rewritten for this repository.
• Policy Note: This artifact intentionally includes no direct quotes and no Refactoring.Guru images.