xiaojilele-glitch/WhyBuddy

🎯 What is SlideRule (WhyBuddy)

SlideRule is an open‑source product‑rehearsal engine. You give it a single sentence describing a product idea, and the system walks you through a deterministic, step‑by‑step creation of a full product spec, UI mock‑ups, data model and even a runnable web app – all inside the browser. Every intermediate artifact must pass an explicit “gate” (evidence check) before the next step is allowed, so the final app is guaranteed to be backed by concrete, auditable work rather than a single “LLM says it’s done”.

---

🛠️ Core Concepts & Workflow

Phase	What Happens	Who/Component
Intent	You type one sentence (e.g., “book a pet‑clinic appointment”).	Client UI
Control Plane	The sentence is turned into a scope card and assumption cards that drive the rehearsal.	rehearsal_control (Node/TS)
Spec → Pages → Structure → Bind	A spec‑first pipeline generates a requirements spec, then UI pages, then a data‑structure graph, and finally binds everything together.	spec-first pipeline (Python)
Assumptions Review	Any hidden model forks are surfaced as cards; the user must confirm before proceeding.	spec.assumptions
Publish Closure	All six required “skills” (evidence, RBAC, workflow, data, AIGC, etc.) are checked. If any gate fails the rehearsal is parked for refinement.	publish closure
Run / Refine	A fully‑functional web app is launched in the browser; you can iterate, repair, or export it.	Browser runtime + control plane

The whole loop is visualised in the repo’s Live path diagram and can be tried instantly at the hosted demo (no backend, no API key required). When a key is supplied, the LLM runs in‑browser via an OpenAI‑compatible endpoint.

---

🚀 How It Works Under the Hood

Layer	Technology	Role
Frontend	Vite + React (TypeScript)	UI for composing intents, viewing the rehearsal steps, and running the generated app.
Thin‑proxy server	Express (Node)	Exposes /api/sliderule and /api/agent-loop endpoints that forward to the Python engine.
Authority engine	FastAPI (Python) – slide-rule-python	Implements the deterministic pipelines, gate checks, and architecture graph validation.
Shared contracts	shared/ (JSON schemas)	Guarantees the same data model between TS and Python.
Skill package	skills/sliderule.zip	A self‑contained “skill” that can be dropped into any TRAE/Claude‑style agent host; it turns a sentence into a full spec package.
Docker	docker‑compose.yml	One‑command dev/prod stack (Node + Python, optional MySQL, Redis, Lobster executor).

All architecture diagrams are generated from the code (arch_graph.py / arch-graph-ts.mjs), ensuring the visual representation never drifts from the actual implementation.

---

📦 Quick Start (Docker)

# Clone & configure
git clone https://github.com/2686521696/WhyBuddy.git && cd WhyBuddy
cp .env.example .env   # add your OpenAI‑compatible LLM_API_KEY

# Build & run the stack
docker compose up -d --build

# Open the UI
open http://localhost:3000/agent-loop/sliderule

If you omit the LLM key the engine falls back to deterministic templates, so the UI still works for exploration.

---

🧪 Running from Source (no Docker)

pnpm install                     # install TS deps
pnpm run dev:all                 # Vite (3000) + Node proxy (3001) + Python FastAPI (9700)

Open the same URL as above. The repo also provides a lean dev:sliderule mode (frontend + Python only) and a UI‑only dev:frontend mode for offline demos.

---

🎓 Example Use Cases (from the README)

• Pet‑clinic booking & triage – generates a full booking flow with triage UI.
• Second‑hand instrument consignment – creates a ledger, appraisal workbench and calendar view.
• Script‑murder venue scheduling – builds a session board, sign‑up forms and car‑pool coordination.
• Procurement approval with field‑level permissions – produces a five‑system model with RBAC‑locked approval state machine.

Each example demonstrates the end‑to‑end path: intent → spec → UI → runnable app, all gated by evidence checks.

---

📊 Project Scale (as of the repo)

• 9,313 tracked files
• 3,336 TS/TSX files (~945 k lines of TypeScript)
• 817 Python files (~226 k lines of Python)
• 2,018 test files
• 2,205 live modules (modules that are part of the running system)

---

🤝 Contributing

The project uses a gated merge workflow:

bash scripts/merge-gated.sh <branch> "msg"   # → pre_main
bash scripts/merge-gated.sh pre_main "msg" main   # → main

Run pnpm run check && pnpm run test locally, and Python tests with:

slide-rule-python/.venv/bin/python -m pytest slide-rule-python/tests/ -q

See CONTRIBUTING.md for full guidelines.

---

📄 License & Links

• License: MIT
• Live demo: https://2686521696.github.io/WhyBuddy/agent-loop/sliderule
• Main repo: https://github.com/2686521696/WhyBuddy
• Product site: https://sliderule.ai
• Award: TRAE Pioneer Skill Award 2026‑07

---

SlideRule is not a “one‑click app generator”. Its value lies in making every design decision visible, auditable, and reversible before any code is shipped.