diff --git a/docs/explainer/images/01-architecture-overview.svg b/docs/explainer/images/01-architecture-overview.svg
new file mode 100644
index 0000000..a8bb34f
--- /dev/null
+++ b/docs/explainer/images/01-architecture-overview.svg
@@ -0,0 +1,106 @@
+
diff --git a/docs/explainer/images/02-grpc-streaming.svg b/docs/explainer/images/02-grpc-streaming.svg
new file mode 100644
index 0000000..5361755
--- /dev/null
+++ b/docs/explainer/images/02-grpc-streaming.svg
@@ -0,0 +1,83 @@
+
diff --git a/docs/explainer/images/03-storage-tiers.svg b/docs/explainer/images/03-storage-tiers.svg
new file mode 100644
index 0000000..8863c59
--- /dev/null
+++ b/docs/explainer/images/03-storage-tiers.svg
@@ -0,0 +1,83 @@
+
diff --git a/docs/explainer/images/04-event-driven.svg b/docs/explainer/images/04-event-driven.svg
new file mode 100644
index 0000000..ea1a4ef
--- /dev/null
+++ b/docs/explainer/images/04-event-driven.svg
@@ -0,0 +1,84 @@
+
diff --git a/docs/explainer/images/05-domain-mapping.svg b/docs/explainer/images/05-domain-mapping.svg
new file mode 100644
index 0000000..b0c5759
--- /dev/null
+++ b/docs/explainer/images/05-domain-mapping.svg
@@ -0,0 +1,80 @@
+
diff --git a/docs/explainer/images/06-deskmeter-enhancement.svg b/docs/explainer/images/06-deskmeter-enhancement.svg
new file mode 100644
index 0000000..40bc3d7
--- /dev/null
+++ b/docs/explainer/images/06-deskmeter-enhancement.svg
@@ -0,0 +1,125 @@
+
diff --git a/docs/explainer/other-applications.md b/docs/explainer/other-applications.md
index 9c8ad38..c2f778d 100644
--- a/docs/explainer/other-applications.md
+++ b/docs/explainer/other-applications.md
@@ -2,6 +2,8 @@
The architecture behind sysmonstm isn't specific to system monitoring. The patterns - streaming data collection, event-driven processing, tiered storage, real-time dashboards - apply to many domains. This article explores two: payment processing systems and desktop productivity tracking.
+
+
## Payment Processing Systems
The sysmonstm architecture was intentionally designed to map to payment processing. Here's how each component translates.
@@ -117,6 +119,8 @@ Current architecture:
This works, but sysmonstm patterns could enhance it significantly.
+
+
### Current Deskmeter Implementation
The core daemon (`dmapp/dmcore/main.py`) polls in a loop:
diff --git a/docs/explainer/sysmonstm-from-start-to-finish.md b/docs/explainer/sysmonstm-from-start-to-finish.md
index 340a138..9f08b9c 100644
--- a/docs/explainer/sysmonstm-from-start-to-finish.md
+++ b/docs/explainer/sysmonstm-from-start-to-finish.md
@@ -2,6 +2,8 @@
This is the story of building a distributed system monitoring platform. Not a tutorial with sanitized examples, but an explanation of the actual decisions made, the trade-offs considered, and the code that resulted.
+
+
## The Problem
I have multiple development machines. A workstation, a laptop, sometimes a remote VM. Each one occasionally runs out of disk space, hits memory limits, or has a runaway process eating CPU. The pattern was always the same: something breaks, I SSH in, run `htop`, realize the problem, fix it.
@@ -29,6 +31,8 @@ service MetricsService {
The collector is the client. It streams metrics. The aggregator is the server. It receives them. When the stream ends (collector shuts down, network drops), the aggregator gets a `StreamAck` response.
+
+
### Why This Storage Tier Approach
Metrics have different access patterns at different ages:
@@ -45,6 +49,8 @@ Storing everything in one place forces a choice between fast reads (keep it all
The aggregator writes to both on every batch. Redis for live dashboard. TimescaleDB for history.
+
+
### Why Event-Driven for Alerts
The alerts service needs to evaluate every metric against threshold rules. Two options:
@@ -70,6 +76,8 @@ class EventSubscriber(ABC):
Currently backed by Redis Pub/Sub (`shared/events/redis_pubsub.py`). The abstraction means switching to Kafka or RabbitMQ later requires implementing a new backend, not changing any service code.
+
+
## Phase 1: MVP - Getting Streaming to Work
The goal was simple: run a collector, see metrics appear in the aggregator's logs.
diff --git a/docs/explainer/viewer.html b/docs/explainer/viewer.html
new file mode 100644
index 0000000..89d0f52
--- /dev/null
+++ b/docs/explainer/viewer.html
@@ -0,0 +1,425 @@
+
+
+