Phase plan — distributed-schema-management.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: GraphQL Federation & Distributed Schema Management
Audience: Backend/full-stack engineers, API architects, platform teams
Live now: 49 pages, 114,741 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.

Read & orient. Read this whole file, then skim content/ to learn what exists and the writing tone.
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. Two presentation fixes that apply site-wide:
- Convert any Mermaid diagrams to hand-authored inline SVGs (in the “Custom visuals” style). No mermaid code fences, .mermaid containers, or mermaid runtime may remain — the mermaid_check gate enforces this.
- Restyle inline <code> to blend with the prose — no background box or border, body-text colour, and not coloured like a link (this is a CSS change in the site’s stylesheet; block code in <pre> keeps its box). The inline_code_check gate enforces this.
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.
Upgrade the homepage AND site navigation to reflect the new content. This is mandatory every phase — new pages must not be left orphaned or unreachable:
- Navigation: update the primary/header nav, footer, and any nav data/menu files (e.g. _data/nav.*, _data/menu.*, layout includes). Every section/topic area must be reachable from the nav; remove links to pages that no longer exist.
- Homepage: refresh the hero, the section/topic cards, any “featured”, “start here”, “popular” or “latest” lists, and any counts/overview copy — surface the newly added sections and the strongest new pages.
- Site-wide: ensure breadcrumbs and sitemap.xml include the new URLs, and wire the new pages in with the same wiki-style interlinking standard.
Keep it niche-specific. Section topics must be drawn from this niche, not generic placeholders.
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 distributed-schema-management.com
```
(Legit domain uses of “cluster” — e.g. a Kafka/DB cluster — are fine; rewrite only the information-architecture sense.)
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/distributed-schema-management.com && npm run build
python3 /home/martin/WebstormProjects/_qa/qa_gates.py distributed-schema-management.com
```
qa_gates.py runs every shared deterministic gate against the BUILT site and must report ALL PASS: term_lint (IA/SEO term leaks), svg_check (inline-SVG validity + hidden/overlapping/clipped/low-contrast labels), mermaid_check (no Mermaid left un-converted to SVG), inline_code_check (inline blends with prose — no box/border, body colour, not link-like), a11y_check (FULL-PAGE WCAG 2 A/AA via axe-core — contrast, alt text, link names, lang, duplicate ids, heading order, keyboard-scrollable regions), links_check (internal links + anchors resolve), jsonld_check (structured-data validity), seo_meta_check (title/description/canonical/og/one-h1 + cross-page duplicates), render_check (no uncaught JS errors / broken same-origin assets), markup_lint (no unrendered markdown or template leakage), sitemap_check (sitemap ↔ built pages), dup_content_check (no near-duplicate article prose), and perf_check (Lighthouse mobile performance budget over a sampled set). Fix the site until every gate passes.



Record completion (re-runs qa_gates and will NOT advance the phase unless they all pass; then 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 distributed-schema-management.com --completed maturity \
    --blueprint "/home/martin/WebstormProjects/distributed-schema-management.com/_plan/blueprint.json"


Commit & deploy. Build, deploy to Cloudflare, and push to GitHub:
cd /home/martin/WebstormProjects/distributed-schema-management.com
npm run deploy          # build + wrangler deploy (auth from the site .env)
git add -A && git commit -m "Upgrade to maturity phase" && git push


QA refresh (uplift to standard — NO new phase) #
Use this when you want to bring the site fully up to the current standard and pass every gate, without building the next phase — the site stays on its current phase (expansion).
Automated (recommended) #
Run /qa-refresh (or just say “do a QA refresh”) — it runs the qa_refresh workflow for this site, which performs everything below automatically: rewrites every page to standard (incl. hand-authored SVGs and Mermaid→SVG), restyles inline code + homepage + navigation, then builds, fixes until every gate passes, records the uplift and deploys. Direct call:
Workflow({scriptPath: "/home/martin/WebstormProjects/_qa/qa_refresh_workflow.js", args: "distributed-schema-management.com"})

Manual (what the workflow does, step by step) #
refresh_site does NOT do the uplift for you — YOU must do the actual work first. It is only the bookkeeping/verification step: it re-syncs counts, re-detects the phase (no advance), re-exports this plan, and runs qa_gates. It will refuse to record the uplift unless every gate passes, so you cannot mark a site “uplifted” without having genuinely rewritten the pages and fixed the SVGs.
Do the checklist above but SKIP step 3 (Build the next phase) — i.e. actually rewrite EVERY existing page to the blueprint (2: anatomy, frontmatter, schema, wiki interlinking, hand-authored SVGs, no Mermaid, blended inline code), update homepage & navigation (4), keep it niche-specific (5), term cleanup (6), and pass the SVG + qa_gates checks (7). Then record the refresh and deploy:
.venv/bin/python manage.py refresh_site distributed-schema-management.com \
    --blueprint "/home/martin/WebstormProjects/distributed-schema-management.com/_plan/blueprint.json"
cd /home/martin/WebstormProjects/distributed-schema-management.com
npm run deploy
git add -A && git commit -m "QA refresh (expansion)" && git push
Phase schedule #



#
Phase
Status
Adds
Target total
Focus




1
1. Foundation
✅ done
2-3 pillars + 10-14 clusters + 8-12 long-tails
~22
Establish core authority: the main pillars and their primary clusters, with enough long-tails to validate demand. Get a consistent page skeleton in place.


2
2. Expansion
✅ done
1-2 pillars + 7-10 clusters + 18-25 long-tails
~50
Broaden coverage: fill out each pillar’s clusters and add the high-intent long-tails around them. Strengthen interlinking between siblings.


3
3. Maturity
➡️ NEXT
4-6 clusters + 28-40 long-tails
~82
Deepen the long tail: comprehensive how-tos, comparisons and edge-case pages under existing clusters. Ensure FAQ blocks and schema on every page.


4
4. Authority
… future
2-3 clusters + 20-30 long-tails
~105
Complete topical authority: remaining gaps, advanced/expert pages, and a tight internal link graph so every page is 1-2 clicks from its pillar.



Priorities for the next phase (maturity) #

Add long-tail pages to under-populated clusters: ‘directive-patterns-for-cross-service-authorization’ and ‘managing-shared-enums-across-subgraphs’ each have no long-tail children yet
Add a ‘schema-registry-and-managed-federation’ cluster to the architecture pillar covering Apollo Studio schema checks, schema proposals, and the managed federation workflow
Add how-to long-tail pages for REST-to-GraphQL migration and resolver performance optimization, which are called out in the site brief but have no pages yet
Add comparison/decision long-tails: ‘Apollo Federation v1 vs v2 directive migration’ and ‘Apollo Router vs @apollo/gateway production trade-offs’ to serve architects evaluating options

Page blueprint #
(tailored to this site)

Frontmatter (every page): title, description, slug, type, breadcrumb, datePublished, dateModified
Schema (JSON-LD): Article, BreadcrumbList, HowTo, FAQPage
Interlinking: Every first mention of a named concept that has its own page (e.g. ‘@key directive’, ‘entity resolver’, ‘schema composition’, ‘subgraph boundary’, ‘Apollo Router’, ‘@requires’, ‘supergraph SDL’) becomes a contextual inline link woven into the prose — not a bare URL but an anchor phrase that reads naturally, e.g. ‘configuring entity resolvers with @key directives’ or ‘the gateway routing strategy determines query plan execution order’. Each page also ends with a short ‘Related’ block (3-5 links) listing sibling cluster pages and the parent pillar, and a single up-link in the breadcrumb/intro sentence pointing to the immediate parent page. Cross-pillar links are allowed when a concept genuinely spans both pillars (e.g. a subgraph-implementation page may link to a federation-architecture page that defines the boundary contract).

pillar pages  (~4500 words) #

H1 + 2-sentence executive summary: what federation solves and who this pillar is for
Core Concepts Overview: define the 4-6 foundational ideas of this pillar (e.g. supergraph composition, subgraph ownership, entity references) with inline links to cluster pages
Architecture Diagram Description: prose walk-through of the component topology (router, subgraphs, composition pipeline) with annotated code or SDL fragment
Key Directives & Configuration Reference: table of the most important directives/config keys for this pillar, their syntax, and effect
Canonical Implementation Pattern: a minimal but production-representative code block (TypeScript + SDL) showing the pillar concept end-to-end
Cross-Pillar Integration Points: how this pillar’s concerns interact with the other pillar (e.g. architecture decisions that shape entity resolution)
Common Failure Modes & Composition Errors: 3-5 named failure scenarios with root cause and remediation, each as a short subsection
CI/CD & Tooling Integration: rover CLI, schema checks, managed federation, and how to wire them into a pipeline
Decision Guide: a comparison table or checklist helping teams choose between approaches (e.g. Federation v1 vs v2, Apollo Router vs gateway)
FAQ accordion: 5-7 practitioner questions specific to this pillar’s scope
Related block: links to all cluster pages in this pillar + 2-3 cross-pillar links

cluster pages  (~3500 words) #

H1 + problem statement: one paragraph naming the specific challenge this cluster addresses and why it matters at scale
Prerequisites checklist: Federation version, packages, and conceptual knowledge required before following this page
Concept Deep-Dive: detailed explanation of the cluster topic with SDL/config snippets illustrating the mechanism (e.g. how @provides works, how boundary events propagate)
Federation Directive or Config Spec Table: precise syntax, valid values, composition-time vs runtime effect for every directive/config relevant to this cluster
Step-by-Step Implementation: numbered workflow with one runnable code block per step; steps must be ordered and atomic
Composition Pipeline Integration: how to validate this pattern with rover, schema checks, or CI; include a YAML or CLI snippet
Performance & Scale Considerations: latency impact, N+1 risks, caching opportunities specific to this cluster topic
Failure Modes & Debugging: 2-4 named error scenarios (composition errors, runtime resolution failures) with exact error messages where known and fix steps
FAQ accordion: 3-5 questions scoped tightly to this cluster topic
Related block: 3-5 links to sibling clusters, the parent pillar, and 1-2 long-tail pages within this cluster

long_tail pages  (~2000 words) #

H1 + one-sentence problem framing: the exact task or question this page answers
When to use this pattern: 2-3 bullet conditions that indicate this long-tail approach is appropriate
Prerequisites: version pins, installed packages, assumed schema state
Implementation walkthrough: prose + a single self-contained code block (SDL + resolver TypeScript) the reader can copy and run; annotate every non-obvious line
Verification steps: how to confirm the pattern works (rover check, query execution, expected response shape)
Common mistakes & gotchas: 2-3 concise pitfalls specific to this exact pattern (e.g. forgetting @external before @requires, mismatched key fields)
Related block: parent cluster link, sibling long-tail links, and one cross-pillar link if relevant


All code blocks must use real Apollo Federation v2 directive syntax (federation spec link @link, not v1 extend type). SDL examples must compile — avoid illustrative pseudo-syntax. FAQ sections must be rendered as HTML details/summary accordions per the site requirements. Checkboxes in prerequisite checklists must use ‘- [ ]’ Markdown syntax so the 11ty build renders them as interactive checkboxes. Tables (directive reference tables, comparison tables) must be standard Markdown pipe tables. Do not include external links; all cross-references must be internal relative URLs. The site uses a light color scheme — code blocks should specify a light-theme highlight class. Breadcrumb trail must appear in both frontmatter and as a rendered nav element near the top of each page.

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 (/<desc>, role=“img”, aria-label); and use currentColor / CSS variables so it adapts to light/dark themes. Prefer one strong diagram that explains the hardest concept on the page over many small ones. Pillar pages should almost always carry a top-level overview diagram. If the site has any Mermaid diagrams (```mermaid blocks, .mermaid containers, or a mermaid runtime), convert each one to a hand-authored inline SVG in this same style — no Mermaid should remain.</p>

#	Phase	Status	Adds	Target total	Focus
1	1. Foundation	✅ done	2-3 pillars + 10-14 clusters + 8-12 long-tails	~22	Establish core authority: the main pillars and their primary clusters, with enough long-tails to validate demand. Get a consistent page skeleton in place.
2	2. Expansion	✅ done	1-2 pillars + 7-10 clusters + 18-25 long-tails	~50	Broaden coverage: fill out each pillar’s clusters and add the high-intent long-tails around them. Strengthen interlinking between siblings.
3	3. Maturity	➡️ NEXT	4-6 clusters + 28-40 long-tails	~82	Deepen the long tail: comprehensive how-tos, comparisons and edge-case pages under existing clusters. Ensure FAQ blocks and schema on every page.
4	4. Authority	… future	2-3 clusters + 20-30 long-tails	~105	Complete topical authority: remaining gaps, advanced/expert pages, and a tight internal link graph so every page is 1-2 clicks from its pillar.

Phase plan — distributed-schema-management.com #

How to upgrade a phase #

QA refresh (uplift to standard — NO new phase) #

Automated (recommended) #

Manual (what the workflow does, step by step) #

Phase schedule #

Priorities for the next phase (maturity) #

Page blueprint #

pillar pages (~4500 words) #

cluster pages (~3500 words) #

long_tail pages (~2000 words) #

Custom visuals (SVG) #

Phase plan — distributed-schema-management.com

How to upgrade a phase

QA refresh (uplift to standard — NO new phase)

Automated (recommended)

Manual (what the workflow does, step by step)

Phase schedule

Priorities for the next phase (maturity)

Page blueprint

pillar pages (~4500 words)

cluster pages (~3500 words)

long_tail pages (~2000 words)

Custom visuals (SVG)