diff --git a/03-behavioral/mediator/README.md b/03-behavioral/mediator/README.md
new file mode 100644
index 0000000..6f4dcd4
--- /dev/null
+++ b/03-behavioral/mediator/README.md
@@ -0,0 +1,31 @@
+# Mediator Design Pattern — Java Example
+
+**Pattern:** Behavioral → Mediator
+**Article:** https://ankurm.com/mediator-design-pattern-java/
+
+## What this example shows
+
+A chat room where users never talk to each other directly. `ChatMediator` declares the hub contract (`sendMessage()`/`addUser()`). `User` is a colleague — it knows only the mediator, never other users. `ChatRoom` is the concrete mediator: it holds the list of users and routes every message to everyone except the sender. `Main` adds three users and has each one broadcast a message, then prints the O(N) vs O(N²) connection-count comparison.
+
+## How to run
+
+```bash
+javac mediator/*.java -d out/mediator
+java -cp out/mediator mediator.Main
+```
+
+Requires Java 25.
+
+## Post Section ↔ File Mapping
+
+| Post Section | File(s) |
+|---|---|
+| Implementation: Chat Room — the Mediator interface | `ChatMediator.java` |
+| Implementation: Chat Room — the Colleague | `User.java` |
+| Implementation: Chat Room — the Concrete Mediator | `ChatRoom.java` |
+| Implementation: Chat Room — wiring it together | `Main.java` |
+
+Note: the "Mediator in Practice: MVC and Spring Events" snippet (`ApplicationEventPublisher`/`@EventListener` example) is illustrative only — it is not part of this repository's runnable example.
+
+Article: https://ankurm.com/mediator-design-pattern-java/
+All patterns: https://ankurm.com/design-patterns-java/
diff --git a/README.md b/README.md
index 86e6e97..fd43860 100644
--- a/README.md
+++ b/README.md
@@ -355,6 +355,23 @@ javac 03-behavioral/iterator/*.java -d out/iterator
 java -cp out/iterator iterator.Main
 ```
 
+### Mediator (`03-behavioral/mediator/`)
+
+| Post Section | File(s) |
+|---|---|
+| Implementation: Chat Room — the Mediator interface | `ChatMediator.java` |
+| Implementation: Chat Room — the Colleague | `User.java` |
+| Implementation: Chat Room — the Concrete Mediator | `ChatRoom.java` |
+| Implementation: Chat Room — wiring it together | `Main.java` |
+
+Note: the "Mediator in Practice: MVC and Spring Events" snippet (`ApplicationEventPublisher`/`@EventListener` example) is illustrative only — it is not part of this repository's runnable example.
+
+Run it:
+```bash
+javac 03-behavioral/mediator/*.java -d out/mediator
+java -cp out/mediator mediator.Main
+```
+
 ## Reference
 
 - *Design Patterns: Elements of Reusable Object-Oriented Software* — Gamma, Helm, Johnson, Vlissides