Add API benchmark suite

.github/workflows/api-benchmark-smoke.yml

@@ -0,0 +1,23 @@
+name: API Benchmark Smoke
+
+on:
+  pull_request:
+    paths:
+      - "apps/api/**"
+      - "benchmarks/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/api-benchmark-smoke.yml"
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run benchmark:smoke

benchmarks/.env.benchmark.example

@@ -0,0 +1,7 @@
+BENCHMARK_TARGET_URL=
+BENCHMARK_AUTH_TOKEN=
+BENCHMARK_ITERATIONS=20
+BENCHMARK_CONCURRENCY=4
+BENCHMARK_P99_THRESHOLD_MS=500
+BENCHMARK_ERROR_RATE_THRESHOLD=0
+JWT_SECRET=development-secret

benchmarks/README.md

@@ -0,0 +1,25 @@
+# API Benchmarks
+
+Run a reproducible benchmark against the local Express API or an external target.
+
+```bash
+npm run benchmark
+npm run benchmark:smoke
+```
+
+Configuration can be supplied with environment variables. Copy `.env.benchmark.example`
+when running outside the default local setup.
+
+- `BENCHMARK_TARGET_URL`: target host. When omitted, the runner starts the local API.
+- `BENCHMARK_AUTH_TOKEN`: bearer token for protected routes. When omitted, a local admin token is generated.
+- `BENCHMARK_ITERATIONS`: requests per endpoint for the full suite.
+- `BENCHMARK_CONCURRENCY`: concurrent workers per endpoint.
+- `BENCHMARK_P99_THRESHOLD_MS`: default p99 latency ceiling.
+- `BENCHMARK_ERROR_RATE_THRESHOLD`: default allowed error rate percentage.
+
+Results are written to:
+
+- `benchmarks/results/latest.json`
+- `benchmarks/results/latest.md`
+
+The smoke mode lowers request volume while still covering every configured endpoint.