From 276e57b2baa395bbcdb4adc33b9f484688ad4c92 Mon Sep 17 00:00:00 2001 From: katR Date: Sun, 11 Oct 2026 10:17:07 +0530 Subject: [PATCH] docs: add architecture flow diagram and failure design invariants --- README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/README.md b/README.md index 8a91a36..c970432 100644 --- a/README.md +++ b/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>`). 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: