From 0219f923e92f1e3413b3711b5a96574a931268d3 Mon Sep 17 00:00:00 2001
From: xfy <i@rua.plus>
Date: Fri, 12 Jun 2026 10:36:12 +0800
Subject: [PATCH] docs: add DEVELOPMENT.md with performance testing guide

---
 DEVELOPMENT.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 DEVELOPMENT.md

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..551f167
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,66 @@
+# Development Guide
+
+## Performance Testing
+
+### Prerequisites
+
+Install hey (HTTP load generator) and samply (profiler):
+
+```bash
+brew install hey
+cargo install samply
+```
+
+### Benchmark
+
+```bash
+# 1. Build release binary
+make build
+
+# 2. Start server
+./target/dx/yggdrasil/release/web/server
+
+# 3. Run load test (in another terminal)
+hey -c 100 -n 100000 http://localhost:8080/
+```
+
+### Flame Graph
+
+```bash
+# 1. Build with debug symbols (required for readable flame graphs)
+CARGO_PROFILE_RELEASE_DEBUG=1 make build
+
+# Terminal 1: Start profiling
+samply record -- ./target/dx/yggdrasil/release/web/server
+
+# Terminal 2: Wait for server to start, then send load
+hey -c 100 -n 100000 http://localhost:8080/
+
+# Terminal 1: Ctrl+C after hey finishes — samply opens flame graph in browser
+```
+
+### Key Metrics to Watch
+
+| Metric | Description |
+|--------|-------------|
+| Requests/sec | Throughput |
+| Average latency | Mean response time |
+| P99 latency | Tail latency |
+| Status codes | Error rate (should be 0) |
+| Latency distribution | Consistency (tight = stable) |
+
+### Flame Graph Hotspots
+
+| Expected Hotspot | Code Location | Cause |
+|------------------|---------------|-------|
+| SSR rendering | Dioxus framework | Virtual DOM diff + render per request |
+| `deadpool` connection acquisition | `src/db/mod.rs` | Connection pool contention under concurrency |
+| `moka` cache lookup | `src/cache.rs` | Cache hit/miss overhead |
+| `tokio` scheduling | tokio runtime | Async task dispatch |
+| `serde` serialization | Models | Post/User serialization |
+
+### Tuning
+
+- `DB_POOL_SIZE` — increase if `deadpool` / `Semaphore` shows high in flame graph
+- `SSR_CACHE_SECS` — increase to cache SSR output longer
+- `TOKIO_WORKER_THREADS` — explicitly set worker thread count