mdadul Facade
Purpose
Help the user decide whether Facade is appropriate, then design and implement clear subsystem entry points that isolate client code from complexity and churn.
When To Use
- User asks to explain Facade pattern.
- Client code is tightly coupled to many subsystem classes and orchestration details.
- Integration requires repeated setup/order/lifecycle code across call sites.
- Team needs stable API boundaries while underlying framework/library evolves.
- Subsystem should be exposed through layer-specific entry points.
Inputs
- Subsystem classes and current client touchpoints.
- Most common client use cases to prioritize in facade API.
- Lifecycle responsibilities (init, configuration, cleanup, retries, resource handling).
- Error and observability requirements (exceptions, logging, metrics, tracing).
- Constraints: performance, backward compatibility, deployment/migration strategy.
Workflow
- Clarify the goal. Confirm whether the user needs concept explanation, architecture review, or implementation/refactor.
- Check applicability. Use Facade when the problem is subsystem complexity and coupling, not interface incompatibility.
- Identify high-value use cases. Select the smallest set of client scenarios the facade must support well.
- Define facade contract. Design a concise task-oriented API with clear inputs/outputs and error model.
- Implement orchestration. Move object creation, dependency ordering, and subsystem coordination into facade methods.
- Isolate subsystem details. Keep concrete subsystem types behind facade boundaries; expose domain-oriented results.
- Migrate clients. Redirect client calls from subsystem internals to facade API incrementally.
- Split when needed. If facade grows broad, extract focused facades per bounded context/layer.
- Validate maintainability. Verify client simplification, reduced coupling, and stable behavior under subsystem changes.
Decision Branches
- If the core issue is incompatible interfaces between two specific classes: Prefer Adapter.
- If the goal is access control, lazy loading, or remote indirection with same interface: Prefer Proxy.
- If communication between many peer components needs central coordination rules: Prefer Mediator.
- If facade starts accumulating unrelated responsibilities: Split into additional facades aligned to use-case or layer boundaries.
- If only object creation should be hidden while behavior remains elsewhere: Consider Abstract Factory for construction plus optional thin Facade for orchestration.
Output Contract
When responding, provide:
- A suitability verdict (Facade or better alternative).
- Coupling hotspot summary (what client complexity is being removed).
- Role mapping (Client, Facade, Additional Facade(s), Subsystem components).
- Incremental migration plan from direct subsystem usage to facade API.
- Minimal code sketch in the user's language showing one facade method orchestrating multiple subsystem calls.
- Validation checklist proving reduced client coupling and preserved behavior.
Quality Checks
- Facade API is minimal, use-case oriented, and free of low-level subsystem jargon.
- Client code depends on facade abstraction, not subsystem internals.
- Facade centralizes lifecycle and ordering concerns consistently.
- Error mapping provides actionable, stable outcomes for clients.
- Subsystem can evolve with limited or no client-side changes.
- Facade size remains bounded; unrelated concerns are split out.
Common Mistakes To Prevent
- Turning facade into a god object with unrelated features.
- Leaking subsystem types or configuration details through facade API.
- Hiding domain errors without preserving useful context.
- Introducing facade without migrating clients, leaving duplicated integration paths.
- Confusing Facade with Adapter (translation) or Proxy (same-interface control).
References
- Detailed guide: REFERENCE.md
- Worked examples: EXAMPLES.md