# Structural Design Patterns

Structural patterns deal with **object composition** — how classes and objects are assembled to form larger structures while keeping those structures flexible and efficient.

## Overview

| Pattern | Intent | Key Mechanism | Complexity |
|---|---|---|---|
| **Adapter** | Make incompatible interfaces work together | Wraps one interface to match another | Low |
| **Bridge** | Decouple abstraction from implementation so both vary independently | Composition over inheritance across two dimensions | Medium |
| **Composite** | Treat individual objects and compositions uniformly | Tree structure with uniform interface | Medium |
| **Decorator** | Add responsibilities dynamically without subclassing | Wrapping with same interface | Medium |
| **Facade** | Provide a simplified interface to a complex subsystem | Single entry point delegating to subsystem | Low |
| **Flyweight** | Share common state among many objects to save memory | Intrinsic vs. extrinsic state separation | High |
| **Proxy** | Control access to an object via a surrogate | Same interface, interposed object | Medium |
| **Module** | Encapsulate related functionality behind a public API | Closure / package-level visibility | Low |

## When to Reach for a Structural Pattern

- **Adapter** — You have existing code with an incompatible interface and cannot change it.
- **Bridge** — You have two independent dimensions of variation (e.g., shape × renderer).
- **Composite** — You need a tree structure where leaves and branches share the same interface.
- **Decorator** — You need to add behavior to objects at runtime without modifying their class.
- **Facade** — You need to simplify interaction with a complex subsystem of many classes.
- **Flyweight** — You have a huge number of similar objects and memory is a concern.
- **Proxy** — You need to control access, add lazy loading, caching, or logging around an object.
- **Module** — You want to group related functions/state and expose only a public API.

## Relationship Between Patterns

```
Adapter vs. Bridge
  Adapter fixes an existing interface mismatch after the fact.
  Bridge is designed up-front to let abstraction and implementation vary independently.

Adapter vs. Facade
  Adapter wraps ONE object to change its interface.
  Facade wraps an ENTIRE SUBSYSTEM to simplify it.

Decorator vs. Proxy
  Decorator adds new behavior (stacking is common).
  Proxy controls access to the original object (usually one layer).

Composite vs. Decorator
  Both use recursive composition.
  Composite focuses on uniform treatment of tree nodes.
  Decorator focuses on adding responsibilities.
```

## Quick Selection Guide

```
Need to…                               → Pattern
──────────────────────────────────────────────────
Reuse a class with a wrong interface    → Adapter
Vary abstraction & impl independently   → Bridge
Build tree structures                   → Composite
Add behavior without subclassing        → Decorator
Simplify a complex subsystem            → Facade
Share state across many objects         → Flyweight
Control access / lazy-load / log        → Proxy
Encapsulate a cohesive module           → Module
```

## Files in This Directory

| File | Pattern |
|---|---|
| [adapter.md](adapter.md) | Adapter |
| [bridge.md](bridge.md) | Bridge |
| [composite.md](composite.md) | Composite |
| [decorator.md](decorator.md) | Decorator |
| [facade.md](facade.md) | Facade |
| [flyweight.md](flyweight.md) | Flyweight |
| [proxy.md](proxy.md) | Proxy |
| [module.md](module.md) | Module |
