Add Design and Architecture

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]]