Phase plan — api-rate-limiting.com

The schedule to grow this site phase-by-phase, generated from the Django Site model. No OpenRouter / no API — you (Claude Code) do the work, grounded in the real markdown under content/.

• Niche: API Rate Limiting & Throttling Architecture
• Audience: API developers, backend engineers, frontend leads, platform teams
• Live now: 52 pages, 106,594 words
• Current phase: expansion
• Next phase to build: maturity

How to upgrade a phase

Work through every step in order. Do not skip the uplift, the term cleanup, the SVG render check, or the finish/deploy steps — those were the gaps in earlier runs.

1. Read & orient. Read this whole file, then skim content/ to learn what exists and the writing tone.

2. Uplift EVERY existing page (not just new ones). Bring all current pages — from earlier phases — up to the Page blueprint below: its page anatomy, frontmatter, JSON-LD schema, the custom SVG visuals, and the mandatory wiki-style interlinking. Old pages must reach the current standard, not be left as they were.

3. Build the next phase. Add this phase’s page mix (see schedule), slotting pages into the existing hierarchy, each built to the same blueprint standard.

4. Keep it niche-specific. Section topics must be drawn from this niche, not generic placeholders.

5. Remove internal IA/SEO terms from visible copy. The words pillar, cluster, long-tail (and “hub and spoke”, “supporting page”, etc.) are internal labels — they must not appear in reader-facing prose. Scan and fix:

   python3 /home/martin/WebstormProjects/_qa/term_lint.py api-rate-limiting.com

   (Legit domain uses of “cluster” — e.g. a Kafka/DB cluster — are fine; rewrite only the information-architecture sense.)

6. Author custom SVG visuals per the “Custom visuals” section, then build the site and verify the SVGs render correctly ON THE PAGE — the page’s CSS/typography must not leak in and break them. Fix and rebuild until clean:

   cd /home/martin/WebstormProjects/api-rate-limiting.com && npm run build
   python3 /home/martin/WebstormProjects/_qa/svg_check.py api-rate-limiting.com

   It statically validates each SVG (XML, id refs), then renders the BUILT pages in headless chromium with the real stylesheet applied — flagging page typography overflowing labels, distorted/zero-size, and empty SVGs. Must pass with no FAILs.

7. Record completion (updates page/word count, advances current→next phase, and rewrites this plan ready for the next phase). From the Django project (/home/martin/PycharmProjects/Django-Pillar-Cluster-Long-Tail):

   .venv/bin/python manage.py finish_phase api-rate-limiting.com --completed maturity \
       --blueprint "/home/martin/WebstormProjects/api-rate-limiting.com/_plan/blueprint.json"

8. Commit & deploy. Build, deploy to Cloudflare, and push to GitHub:

   cd /home/martin/WebstormProjects/api-rate-limiting.com
   npm run deploy          # build + wrangler deploy (auth from the site .env)
   git add -A && git commit -m "Upgrade to maturity phase" && git push

Phase schedule

Priorities for the next phase (maturity)

• Frontend resilience pillar is the thinnest — add cluster pages for retry-after parsing, exponential backoff UX patterns, and client-side rate-limit state management
• Add comparison long-tail pages for every cluster that currently has only one long-tail (e.g. Redis vs in-memory for token bucket, Django vs FastAPI middleware tradeoffs)
• Add a compliance/tiered-access cluster under backend-middleware covering per-tier quota enforcement, API key scoping, and billing-critical sliding-log usage — mentioned in site description but absent from content
• Add HowTo-schema long-tail pages for observability instrumentation: emitting X-RateLimit headers, Prometheus metrics, and alerting on 429 rates — high search intent for backend engineers

Page blueprint

(tailored to this site)

• Frontmatter (every page): title, description, slug, type, breadcrumb, datePublished, dateModified
• Schema (JSON-LD): Article, BreadcrumbList, HowTo, FAQPage
• Interlinking: Wiki-style inline cross-links are mandatory. Rule 1 — first mention of any named algorithm (token bucket, leaky bucket, sliding window, fixed window, sliding log) that has its own page becomes an inline link, e.g. ‘the token bucket algorithm deducts tokens atomically’. Rule 2 — first mention of any named middleware/framework page (Redis counter architecture, Express.js rate-limit middleware, FastAPI throttling, Django rate-limit) becomes an inline link woven into the sentence, e.g. ‘configure the Redis counter architecture to store bucket state’. Rule 3 — first mention of distributed concepts (CRDT, gossip protocol, clock skew) links to the distributed-algorithm-sync cluster page. Rule 4 — every page ends with a ‘Related’ block (3-5 bullets) listing sibling and parent pages. Rule 5 — every cluster and long-tail page includes an up-link to its parent in the opening paragraph, e.g. ‘as covered in the Core Rate Limiting Algorithms & Theory pillar’.

pillar pages (~4500 words)

• Frontmatter (title, description, slug, type=pillar, breadcrumb, datePublished, dateModified)
• Lead paragraph: define the pillar’s scope, audience, and why this topic is foundational to production API design (2-3 sentences, inline cross-link to a sibling pillar)
• Conceptual overview: explain the core mechanism or domain boundary (no code yet); establish vocabulary used throughout the site
• Algorithm/technique comparison table: columns = mechanism, memory footprint, burst tolerance, precision, distributed complexity — rows = each major variant covered by cluster pages
• Section per major sub-topic (one per cluster child): 2-3 paragraphs each, inline cross-link to the cluster page in the first sentence
• Architecture & deployment context: edge vs origin enforcement, failure modes (fail-open vs fail-closed), when to layer algorithms
• Operational considerations: observability signals (X-RateLimit headers, metrics, alerting thresholds), SLA implications
• Decision guide / selection criteria: bulleted rules mapping workload characteristics to algorithm or framework choice
• Related block: 4-5 inline links to cluster children and sibling pillars

cluster pages (~3500 words)

• Frontmatter (title, description, slug, type=cluster, breadcrumb, datePublished, dateModified)
• Lead paragraph: state the specific problem this cluster solves, up-link to parent pillar in the first sentence
• Mechanism / spec section: precise algorithmic or API description — state variables, invariants, complexity (O-notation), data structures required
• Configuration reference table: parameter name, type, default, valid range, effect — every tunable knob for this mechanism
• Implementation walkthrough: step-by-step with runnable, production-ready code block(s); at minimum one Redis/Lua or language-native example with inline comments
• Distributed / scaling considerations: how the mechanism behaves under horizontal scale, clock skew, partial failures
• Failure modes & mitigations: enumerate each failure mode (race condition, stale state, queue overflow) with concrete mitigation code or config
• Response contract: HTTP headers emitted (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After), status codes, client retry guidance
• Long-tail pages index: brief description of each child long-tail page with inline links
• Related block: 3-5 links to sibling clusters, parent pillar, and relevant long-tail pages

long_tail pages (~2000 words)

• Frontmatter (title, description, slug, type=long_tail, breadcrumb, datePublished, dateModified)
• Lead paragraph: one sharp sentence naming the exact decision or task, up-link to parent cluster in the second sentence
• Problem framing: describe the concrete scenario or use-case that makes this choice/task necessary (avoid abstract; use realistic traffic numbers)
• Decision matrix or comparison table: side-by-side of the two or more options being compared, rows = evaluation criteria specific to this niche
• Step-by-step implementation or configuration: numbered checklist with runnable code snippets for each step; checkboxes [ ] for operator tasks
• Gotchas & edge cases: bullet list of non-obvious failure modes, boundary conditions, or misconfiguration patterns specific to this topic
• Verification & testing: how to confirm the implementation is correct — load test snippet, curl command, or metric to watch
• FAQ accordion: 3-5 questions engineers actually ask about this specific decision, answered concisely
• Related block: 3-4 links to sibling long-tail pages and parent cluster

All code blocks must use fenced markdown with explicit language tags (typescript, lua, python, javascript) for syntax highlighting. Decision/comparison tables are required in every cluster and long-tail page — the audience is engineers scanning for a quick answer. Avoid marketing language; tone is direct, technical, production-focused. The site already has strong pillar content; new pages should match that register. Checkboxes [ ] in long-tail operator checklists will render as interactive UI per site requirements. FAQ sections must use the accordion pattern per site spec — mark them with a comment or class hint so the 11ty template can render them correctly.

Custom visuals (SVG)

When upgrading or building any page, add a custom, hand-authored inline SVG wherever a visual would genuinely raise quality (architecture/data-flow diagrams, sequence or state diagrams, comparison matrices, timelines, annotated illustrations). Do NOT add decorative or generic stock-style images. Each SVG must: be original and specific to the page’s content; match the site’s existing design system (colours, fonts, stroke weight); be responsive (viewBox, no fixed pixel width) and accessible (