campaign-sender · submission home

Start here

This page is the front door. Everything the brief asks for lives in this folder: the working code (src/), the complete AI conversations rendered as clickable transcripts (transcript/), the docs and benchmarks behind every number. Below: how to run it, what to test step by step, and what my usual workflow adds that this task didn't need. Dry-run only — no real recipient ever receives anything.

↓ run it · what to test · what's in the folder · how I work with AI

0.0% of 1,000,000

The run, in shape: batches of 1,000 stream through the two gates into the ESP's fan-out — each dot is one batch, orange dots are 429s re-crossing after Retry-After. ~135k emails/s until every recipient is accounted for, then it starts over.

Run it

Needs Node ≥ 20 and pnpm (corepack enable gets you pnpm). Zero runtime dependencies — install pulls only the dev toolchain.

/guide-me — using Claude Code? The repo ships this command (.claude/commands/guide-me.md): open Claude Code in the folder and run it for an interactive tour that walks every step below, runs the demos, and interprets your machine's actual numbers instead of reciting the README's. Everything that follows is the manual version of the same route.

Install.
```
pnpm install
```
Tests first — they're what make every number below trustworthy.
```
pnpm test
```
✓ 15/15 in ~2s: checkpoint durability, retry classification, semaphore bound, and two end-to-end exactly-once runs.
Generate the list. 1,000,000 synthetic recipients, ~40MB CSV.
```
pnpm generate
```
Send the campaign — and open http://localhost:3210 while it runs for the live dashboard.
```
pnpm send
```
✓ ~7s wall clock, ~140k emails/s, and the accounting line sums to exactly 1,000,000 — every recipient, exactly once.

What to test, step by step

Three demos, in order of importance — each one exercises a claim the README makes (all covered by /guide-me too).

Crash mid-campaign, resume without duplicates. The core promise: duplicates are worse than slowness.
```
pnpm send --crash-after 400000
pnpm send
```
The first run dies hard at ~400k sends (a simulated kill -9, no graceful shutdown). The rerun prints "400 of 1000 batches already sent — they will be skipped" and finishes the rest: zero duplicates, at most one batch per in-flight slot re-sent. campaign.checkpoint (~4KB) is the entire mechanism.
Why rate ≠ concurrency. Run against a simulated 50 req/s provider quota, first with no client-side limiter, then with one.
```
pnpm send --sim-quota 50
pnpm send --sim-quota 50 --rate 50
```
Without --rate: a wall of 429s — the retry machinery becomes your flow control. With --rate 50: pinned steady at the quota with a handful of 429s from jitter at the boundary. Same wall clock; very different citizenship.
Find the scaling walls. Two-regime concurrency sweep with p50/p95/p99.
```
pnpm sweep
```
Unlimited regime: scaling bends where the client CPU (CSV parsing + request building) becomes the ceiling — never the network. Quota regime: past saturation, throughput pins and the median latency collapses ~7× — extra concurrency is pure downside.
Optional — real TLS instead of the mock.
```
pnpm exec tsx scripts/bench-tls.ts
```
The real EspTransport through real HTTPS against a local server — the bench that validated the fsync conclusion under genuine crypto load.

What's in the folder

The brief asks for two things: the code, and all of the prompts. The starred lines are the prompts — start there.

★transcript/01-session-scoping-and-build.html the full conversation: scoping → build → review → packaging
★transcript/02-session-guide-tour.html second session: re-verifying the delivered repo on my machine
README.md the ninety-second map of the whole project
docs/visual/architecture.html system flow, crash-resume timeline, failure tree
docs/visual/benchmarks.html stat tiles, throughput ramp, the sweep
docs/01–06 · *.md the depth: approaches, architecture, reliability, performance, sweep, security
src/ · tests/ · scripts/ ~500 lines of pipeline, 15 tests, the sweep + TLS bench harnesses

How I usually work with AI — and what I skipped here

This take-home is a compressed version of the loop I run on real projects. The full loop, what ran here, and what a real project would get in addition:

✓ applied here ↻ adapted to the task ✕ deliberately skipped

The one accented box is the habit I keep even under time pressure: nothing ships on my own read alone.

✓ Goals, objectives, trade-offs before code. Turn 1 of session 1 is exactly this: five approaches, each with its real bottleneck named, and decision points asked — not assumed — before a line existed.

✓ Everything visualized, twice. Markdown (docs/01–06) as the AI-readable context layer; HTML (docs/visual/, the transcript pages, this page) as the layer I actually read. Same facts, two audiences.

↻ Plan mode + OpenSpec explore/propose. Planning happened and the build waited for sign-off — but in-conversation rather than as OpenSpec artifacts. A single-task assignment doesn't need cross-task context storage; on a real project every task gets an OpenSpec explore/propose so progress and context survive beyond one conversation.

↻ Prototype, diagrams, big picture, double-check. The architecture was agreed in prose before code; the diagrams that on a real project would precede implementation were produced immediately after, as the visual docs.

✓ Agent-generated tests, e2e included. 15 tests, two of them end-to-end exactly-once accounting — and they caught two real bugs before delivery (the torn checkpoint tail, the unflushed reject log).

✓ Stress tests and a metrics report. Full-1M runs, a 5×5 re-baseline with spreads, a TLS transfer-validity bench, and the two-regime concurrency sweep with p50/p95/p99 — written up in docs/04 and docs/05.

↻ PR summary with mermaid flows and browser screenshots. On a real project the change lands as a PR with full mermaid flow diagrams and agent-browser screenshots. An email submission has no PR to open — the README serves as that map, the diagrams live in the visual docs, and every page was render-checked through headless-browser screenshots before delivery.

↻ Stronger-model review with per-domain skills. My normal last gate on real projects: senior-BE skill on the backend, senior-FE on the front, architecture on the whole, security last for vulnerabilities. Here the security pass ran in-session (docs/06: three fixes, named audit gaps) and design skills built the visual layer; the full four-skill pass is what I'd run before any real deploy.

✕ Deploy, then archive the spec. Out of scope by the brief itself: dry-run only, no real recipients, nothing to deploy. On a real project the loop ends with the deploy and openspec archive closing the task.