Facade Pattern

# ===== BEFORE: Client coordinates multiple subsystems =====
# Every caller must know about all three services and their order

from analytics_service import AnalyticsService
from email_service import EmailService
from database import UserRepository

def signup_user_without_facade(email: str, password: str):
    # Client must know all dependencies and coordinate them
    user_repo = UserRepository()
    analytics = AnalyticsService()
    email_svc = EmailService()

    user = user_repo.create(email, password)
    analytics.track("user_signup", {"user_id": user.id})
    email_svc.send_welcome(user.email)
    return user

# ===== AFTER: Facade handles coordination =====

class UserService:
    """Facade for user operations. Coordinates subsystems internally."""

    def __init__(
        self,
        user_repo: UserRepository,
        analytics: AnalyticsService,
        email_svc: EmailService,
    ):
        # Dependency injection for testability
        self._users = user_repo
        self._analytics = analytics
        self._email = email_svc

    def signup(self, email: str, password: str) -> User:
        """Create user, track event, send welcome email."""
        user = self._users.create(email, password)
        self._analytics.track("user_signup", {"user_id": user.id})
        self._email.send_welcome(user.email)
        return user

    def deactivate(self, user_id: int) -> None:
        """Deactivate user and clean up related data."""
        self._users.deactivate(user_id)
        self._analytics.track("user_deactivated", {"user_id": user_id})

    # Escape hatch: expose subsystems for advanced use cases
    @property
    def users(self) -> UserRepository:
        return self._users

# Usage - client only knows about the simple interface
user_service = UserService(UserRepository(), AnalyticsService(), EmailService())
new_user = user_service.signup("alice@example.com", "secret123")

# Advanced: direct access when needed
all_users = user_service.users.find_all(active=True)

// ===== Analytics Facade: Fire-and-forget tracking =====
// Problem: Every button click needs to call multiple analytics providers
// with different event formats. UI components shouldn't know the details.

class GoogleAnalytics {
  track(eventName, properties) {
    console.log(`[GA] ${eventName}`, properties);
    // gtag('event', eventName, properties);
  }
}

class Mixpanel {
  track(eventName, properties) {
    console.log(`[Mixpanel] ${eventName}`, properties);
    // mixpanel.track(eventName, properties);
  }
}

class InternalLogger {
  log(level, message, data) {
    console.log(`[${level}] ${message}`, data);
    // fetch('/api/logs', { method: 'POST', body: JSON.stringify({ level, message, data }) });
  }
}

// ===== Facade: Single "track" call dispatches to all providers =====

class AnalyticsFacade {
  constructor(config = {}) {
    this.ga = config.ga ?? new GoogleAnalytics();
    this.mixpanel = config.mixpanel ?? new Mixpanel();
    this.logger = config.logger ?? new InternalLogger();
    this.userId = null;
  }

  identify(userId, traits = {}) {
    this.userId = userId;
    this.mixpanel.track("identify", { userId, ...traits });
    this.logger.log("info", "User identified", { userId });
  }

  track(eventName, properties = {}) {
    const enriched = {
      ...properties,
      userId: this.userId,
      timestamp: Date.now(),
    };

    // Dispatch to all providers - caller doesn't care about details
    this.ga.track(eventName, enriched);
    this.mixpanel.track(eventName, enriched);
    this.logger.log("event", eventName, enriched);
  }

  // Convenience methods for common events
  trackPageView(pageName) {
    this.track("page_view", { page: pageName });
  }

  trackPurchase(productId, amount) {
    this.track("purchase", { productId, amount, currency: "USD" });
  }
}

// ===== Usage: UI components use simple interface =====

const analytics = new AnalyticsFacade();

// Login handler - one line instead of three provider calls
analytics.identify("user_123", { plan: "pro" });

// Button click - fire and forget
document.querySelector("#buy-btn").addEventListener("click", () => {
  analytics.trackPurchase("prod_abc", 29.99);
});

// Page navigation
analytics.trackPageView("/dashboard");

# ===== BEFORE: Main menu coordinates all systems directly =====
# Every scene that needs these operations duplicates this logic

extends Control

func _on_new_game_pressed() -> void:
    # Menu must know about all subsystems and their order
    AudioManager.stop_bgm()
    SaveSystem.clear_current()
    SceneManager.load_scene("res://scenes/level_1.tscn")
    AudioManager.play_bgm("adventure_theme")
    PlayerStats.reset()
    QuestSystem.reset()

# ===== AFTER: GameFacade handles coordination =====

# game_facade.gd - Dependency injection for testability
class_name GameFacade
extends RefCounted

var _audio: AudioSystem
var _save: SaveSystem
var _scene: SceneManager

# Dependency injection: pass subsystems in (or use defaults)
func _init(
    audio: AudioSystem = null,
    save: SaveSystem = null,
    scene: SceneManager = null
) -> void:
    _audio = audio if audio else AudioSystem.new()
    _save = save if save else SaveSystem.new()
    _scene = scene if scene else SceneManager.new()

func start_new_game() -> void:
    _audio.stop_bgm()
    _scene.load_scene("res://scenes/level_1.tscn")
    _audio.play_bgm("adventure_theme")
    _audio.play_sfx("game_start")

func load_game(slot: int) -> void:
    var data: Dictionary = _save.load_game(slot)
    # Dictionary access uses bracket notation
    var level_num: int = data["level"]
    var scene_path := "res://scenes/level_%d.tscn" % level_num
    _scene.load_scene(scene_path)
    _audio.play_bgm(data.get("last_bgm", "adventure_theme"))

func save_game(slot: int) -> void:
    var data := {
        "level": _scene.current_level,
        "last_bgm": _audio.current_bgm,
    }
    _save.save_game(slot, data)
    _audio.play_sfx("save_complete")

func quit_to_menu() -> void:
    _audio.stop_bgm()
    _scene.unload_current()
    _scene.load_scene("res://scenes/main_menu.tscn")
    _audio.play_bgm("menu_theme")

# Escape hatch: expose subsystems for advanced use cases
func get_audio() -> AudioSystem:
    return _audio

# ===== Usage: main_menu.gd =====
extends Control

var game: GameFacade

func _ready() -> void:
    game = GameFacade.new()

func _on_new_game_pressed() -> void:
    game.start_new_game()

func _on_load_pressed() -> void:
    game.load_game(1)

func _on_quit_pressed() -> void:
    game.quit_to_menu()

# Advanced: direct access when needed (e.g., volume settings)
func _on_volume_changed(value: float) -> void:
    game.get_audio().set_volume(value)