docs: add architecture flow diagram and failure design invariants

README.md

@@ -23,6 +23,36 @@ BrokeCrew makes free-tier models first-class citizens while eliminating their in
 
 ---
 
+## Architecture & Failure Design
+
+```text
+Prompt Ingest
+  │
+  ├── Stage A : Zero-latency Keyword & Regex classifier (0ms)
+  └── Stage B : Single-token LLM meta-router fallback
+  │
+  ▼
+[ Persona Selection ] ──> Ranked Candidate Cascade
+  │                         ├── Candidate 1 (e.g. qwen:free)
+  │                         ├── Candidate 2 (e.g. deepseek:free)
+  │                         └── Candidate 3 (e.g. gemini-flash paid fallback)
+  │
+  ▼
+[ Budget Engine ] ───────> Atomic Token/Request Tracker
+  │                         ├── Rolling 1-min sliding window (20 req/min)
+  │                         └── Daily quota tracker (50 vs 1,000 req/day by tier)
+  │
+  ▼
+[ Transport & Stream ] ──> Async SSE Parser ──> TUI / CLI stdout
+```
+
+### Technical Invariants
+- **Fail-Fast Cascade Walk**: Free endpoints on OpenRouter frequently return transient `429`, `503`, or drop out of `/v1/models` without warning. Candidate resolution treats failures as cascade triggers rather than fatal aborts, stepping to the next viable candidate model within `<250ms`.
+- **Sliding-Window Budgeting**: Token usage and request counts are stored in atomic sliding windows (`VecDeque<DateTime<Utc>>`). Router and classifier calls deduct from the shared account budget to prevent downstream API lockouts.
+- **Async Non-Blocking SSE**: Streaming tokens are decoupled from the Ratatui TUI render loop via crossbeam/tokio MPSC channels, ensuring UI frame rates remain at 60 FPS even during erratic remote network jitter.
+
+---
+
 ## OpenCode / Pi-Style Interactive TUI
 
 Simply run `brokecrew` to enter the rich, full-screen interactive TUI: