From 0cbd462e7cc6dbac6309fad0b5b359bc50f867e8 Mon Sep 17 00:00:00 2001
From: Dan Milne <d@nmilne.com>
Date: Mon, 3 Nov 2025 17:42:57 +1100
Subject: [PATCH] Update README

---
 README.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 90 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 7db80e4..352e203 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,101 @@
-# README
+# Baffle Hub
 
-This README would normally document whatever steps are necessary to get the
-application up and running.
+**Rails 8 WAF analytics and automated rule management system**
 
-Things you may want to cover:
+Baffle Hub provides intelligent Web Application Firewall (WAF) analytics with automated rule generation. It combines real-time threat detection with SQLite-based local storage for ultra-fast request filtering.
 
-* Ruby version
+## Features
 
-* System dependencies
+- **Real-time Analytics** - Process WAF events and detect attack patterns
+- **Automated Rule Generation** - Create rules automatically from threat intelligence
+- **Fast Local Storage** - SQLite for sub-millisecond request evaluation
+- **Forward Auth Integration** - Compatible with Caddy, Traefik, and NGINX
+- **Docker Ready** - Containerized deployment with Kamal
 
-* Configuration
+## Quick Start
 
-* Database creation
+### Prerequisites
 
-* Database initialization
+- Ruby 3.x
+- PostgreSQL 14+
+- Docker (optional)
 
-* How to run the test suite
+### Installation
 
-* Services (job queues, cache servers, search engines, etc.)
+```bash
+# Clone the repository
+git clone <repository-url>
+cd baffle-hub
 
-* Deployment instructions
+# Install dependencies
+bundle install
 
-* ...
+# Copy environment files
+cp .env.example .env
+
+# Setup database
+rails db:create db:migrate
+
+# Start the server
+rails server
+```
+
+### With Docker
+
+```bash
+# Build and run
+docker-compose up -d
+```
+
+## Architecture
+
+```
+Request → Reverse Proxy → Baffle (SQLite check) → Decision
+                            ↓
+                    Async analytics processing
+                            ↓
+                    Pattern detection → New rules
+```
+
+## Configuration
+
+Key environment variables:
+
+- `DATABASE_URL` - PostgreSQL connection string
+- `RAILS_ENV` - Environment (development/production)
+- `SECRET_KEY_BASE` - Rails secret key
+
+## API Endpoints
+
+- `POST /api/:project_id/events` - Ingest WAF events
+- `GET /projects/:id` - View project analytics
+- `GET /dashboard` - Analytics dashboard
+
+## Deployment
+
+Deploy with Kamal:
+
+```bash
+# Setup deployment
+kamal setup
+
+# Deploy to production
+kamal deploy
+```
+
+## Development
+
+```bash
+# Run tests
+rails test
+
+# Run background jobs
+rails jobs:work
+
+# View analytics
+rails console
+```
+
+## License
+
+MIT License - see LICENSE file for details.