From 9106251d3dbbd3c25c6473f9eb98aab6121d0925 Mon Sep 17 00:00:00 2001
From: Leo Galambos <galambos@noreply.localhost>
Date: Thu, 3 Jul 2025 22:51:54 +0200
Subject: [PATCH] Add Design and Architecture

---
 Design-and-Architecture.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 Design-and-Architecture.md

diff --git a/Design-and-Architecture.md b/Design-and-Architecture.md
new file mode 100644
index 0000000..35e8f10
--- /dev/null
+++ b/Design-and-Architecture.md
@@ -0,0 +1,32 @@
+# Design and Architecture
+
+## Motivation
+
+- Provide an application-wide, strongly typed key-value store
+- Avoid tight coupling of modules
+- Allow subscribing to value changes without risking memory leaks
+
+## Why Enum Singleton
+
+- Simple
+- Thread-safe by Java specification
+- Cannot be duplicated through serialization
+
+## Why Weak References for Listeners
+
+- Listeners should not prevent GC
+- Weak references automatically clean up when listener objects are unreachable
+
+## Thread Safety
+
+- Uses `ConcurrentHashMap`
+- Listeners stored in `CopyOnWriteArrayList`
+
+## Trade-offs
+
+- Slightly higher cost for weak-reference listener lookups
+- Enum cannot be extended (intentional for safe singleton)
+
+---
+
+[[Home]] | [[API Reference]] | [[FAQ]]
\ No newline at end of file