From 900e1534b6b41c5a3f8b071e8636bff248c5ea2e Mon Sep 17 00:00:00 2001
From: Dan Milne <d@nmilne.com>
Date: Sat, 8 Nov 2025 10:35:37 +1100
Subject: [PATCH] add a readme

---
 README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d497206
--- /dev/null
+++ b/README.md
@@ -0,0 +1,83 @@
+# Baffle WAF
+
+## Product Positioning
+Tagline options:
+
+"Baffle bots. Calm traffic." (playing on both meanings: confuse + quiet)
+"Confuse bots. Calm infrastructure."
+"Bewilder bots, silence the chaos"
+
+## Target market:
+
+Solo devs/bootstrapped startups (can't afford $249/mo Wafris/Cloudflare)
+Privacy-conscious/regulated orgs (data sovereignty requirements)
+Self-hosters (infrastructure control enthusiasts)
+Cost-sensitive scale-ups (outgrowing free tiers)
+
+## Business Model (Sidekiq-style)
+Free (fully functional):
+
+Ruby/Rack edge agent (2-5ms response time)
+Local SQLite rules
+IP blocking, rate limiting, geoblocking
+Manual rule management
+Community support
+
+Pro ($99-149/mo):
+
+Go edge agent (performance upgrade)
+SSO / multi-team
+Centralized hub with traffic analytics
+Automated rule generation
+Adaptive sampling (manual 0-100% toggle for hub load management)
+IP reputation feeds
+Priority support
+
+## Key Technical Decisions
+Traffic categories:
+
+Blocked - Matched deny rule
+Allowed - Matched allow rule (fast-path for whitelisted IPs/APIs)
+Unmatched - No rules, passed through
+
+## OWASP approach:
+
+Don't try to compete with ModSecurity's full CRS
+Focus on network-layer threats (bots, rate limiting, IP reputation)
+Map to OWASP Top 10 where applicable (A05, A07, partial A01/A03)
+Position as complementary to app-layer security
+
+### Killer Feature: Performance Visibility
+Always-on category timing:
+
+Track latency by rule type (IP checks, rate limits, regex, etc.)
+Show real-time impact in dashboard
+Let users add rules and immediately see performance cost
+"The only WAF that shows you exactly what your rules cost"
+
+Why this matters:
+
+No other WAF does this well
+Solves "why is my site slow?" blame game
+Empowers users to make informed tradeoffs
+Natural deterrent against kitchen-sink rule sets
+
+## Implementation:
+
+Start with category-level timing (always on, minimal overhead)
+Users can experiment: add rule → watch latency → remove if too expensive
+Can add detailed per-rule profiling later if needed
+
+## Terminology Settled
+
+Rule pruning - removing inactive rules for performance
+Violation/pattern match - when traffic triggers a rule
+Adaptive sampling - hub telling edges to reduce telemetry load
+
+## Architecture Clarity
+Self-hosted only (no SaaS hosting from you):
+
+Edge agents do forward auth with local SQLite
+Push telemetry to hub every 10 seconds
+Hub analyzes and pushes rules back
+Max 20-second gap between violation and rule deployment