knowledge base · gf.cx portfolio patterns

Patterns that travel

Operating patterns surfaced session-by-session from building the gf.cx portfolio — recipes, traps, design choices, disciplines. Each entry is a pattern that has earned its keep on one surface and is documented so the next developer (future-Dan, or anyone else building in this style) can recognise + reuse it without rediscovering the friction.

Featured · curated highlights

Read everything

Operating dashboards · seed

Read-me · status of the stack

R/Y/G priority tiers + collapsible category panels make a system's "what's done / what's open / what's silent-failure risk" visible at a glance. Doubles as documentation + running TODO. Dan named the pattern 2026-05-27 after 5 items flipped ✅ in one session on pa.gf.cx/service-records.

Deployment mechanics

BASE_URL one-line swap

Workers + tag-previews + dashboards all reference a single exported BASE_URL constant — when the custom domain binds, one-line edit + redeploy flips everything. Avoids the dozen-find-replace migration that always misses one.

Vendor integration

Sandbox-first discipline

Vendor APIs (Pwinty, Resend, Twilio, Stripe) get a self-contained surface — sandbox.gf.cx/<vendor>/ — for end-to-end proof before promoting to production tag-previews and order paths. Contains the blast-radius of sandbox creds + experimental wiring.

Cloudflare gotchas

Workers-with-Assets · run_worker_first

CF Pages projects with _worker.ts + assets binding intercept asset paths BEFORE the worker for browser-shaped requests. Symptom: works in curl, 404s in browser. Fix: run_worker_first: true. Cost us 90 minutes on dare.co.uk/ip before the cf-cache-status HIT signal broke it open.

Deploy verification

Visual verification · external probe

"Looks good from here" is not deploy verification. WhereGoes / urltoscreenshot.com / RapidAPI-screenshot are the independent witnesses that catch the curl-200-but-browser-404 class of bug before real users do. Bake into deploy hygiene.

Routing design

Tag-router · numeric + slug peers

QR labels encode short numeric IDs (denser scan, re-assignable, opaque). Slug URLs stay as friendly aliases for humans. Both resolve to the same record — first-class peers in the worker. Class-prefixed numbering (1xxx vehicles · 2xxx tools · etc.) gives the IDs structure without leaking semantics.

Portfolio scaffolding

gfcx_subdomain_new · scaffold

Don't hand-roll a new gf.cx subdomain. The generator at ~/bin/gfcx_subdomain_new.py encodes prior friction — fonts, primitives, CF Pages config, deploy command, custom-domain dashboard path. Each new subdomain adds learnings back to the scaffold itself.

Read-me · status of the stack

Source · Dan, 2026-05-27

"Can't tell you how important a pattern like 'Read-me · status of the stack' is to the growth. It's super logical and shows foresight and helps frame the interdependencies between entities and records/bindings and such like."

"This is a GOLD standard set of operating principles."

The problem

A system grows by accretion: new endpoints, new bindings, new vendor accounts, half-done refactors, parked sketches. Without a self-state-tracking surface, two things rot:

The operator's mental model diverges from reality. Did I bind that domain? Is Access on yet? Did I ever fix that typo'd entry? Cost = re-discovery on every return.
The interdependencies become invisible. A 🟢 nice-to-have can quietly turn into a 🔴 blocker the moment a related decision lands. Without a frame for "this depends on that," velocity tax compounds.

The shape

Production-blocking3 items+

Data lifecycle4 items+

Workflow / UX3 items+

Cross-surface integration3 items+

Operational hygiene4 items+

Tag-physical workflow3 items+

People / governance3 items+

An H2 "Read-me · status of the stack" near the bottom of an operator dashboard or category landing. Below it: a stack of collapsible <details> panels — one per priority tier, with:

A colored dot 🔴 🟡 🟢 carrying the priority semantics (production-blocking / lifecycle-rot / silent-failure-risk)
A category name in the operator's language — not P1/P2/P3 abstractions
A count summary in the panel header ("4 items" → "2 of 3 done · 1 open") so scope + velocity are visible without opening
Done items kept in the list with ✅ and a date — they don't disappear; the page becomes session-log + TODO simultaneously
Each open item has a how-to-fix sub-line below its title — actionable, not just descriptive

Why R/Y/G works (and a flat checklist doesn't)

Choice	Why
Color via dot, not text-color	Dot is at-a-glance even at peripheral vision. The dot does the work before any reading happens.
Categories named in operator's language	"Tag-physical workflow" instead of "Hardware" — names the operator already uses internally. Eye finds the right bucket without translation.
Collapsible per-category	23 items in a flat list is intimidating + scroll-heavy. 7 collapsed panels fit one phone screen; the eye picks where to dive in.
Count in summary	Shows scope without opening. After completions: "2 of 3 done · 1 open" makes velocity visible.
✅ stays + dates	Velocity is visible. Future-you knows what was resolved + when + by which session.
How-to-fix sub-line per open item	Re-entering work next session = one-line briefing. The dashboard is actionable, not just descriptive.
Lede summarizes velocity	"5 of 23 resolved this session" primes the reader to see the page as alive + moving, not a static gripe list.

Where it applies

Strong candidates — surfaces where the page is both documentation AND a TODO:

Operator dashboards (pa.gf.cx/service-records/ is the canonical exemplar)
Agent / watcher hubs (agent.gf.cx/ — module lifecycle state)
Marketing / SEO sites with running performance debts (PSI, GSC indexing gaps, broken-link punch lists)
Category landings on pa.gf.cx/ that grow ≥ 5 interdependent records
Vendor decision surfaces (refuse re-quote, HVAC shortlist) with status across candidates

Weak candidates — pages whose audience is external:

Public-facing detail pages (found.gf.cx finder pages, individual svc.gf.cx brand pages)
Sales pages, blog posts, content marketing

The portable shape

<h2 class="section-heading">Read-me · <em>status of the stack</em></h2>
<p class="lede">[snapshot date · N of M resolved · brief tier framing]</p>

<details class="gap">
  <summary>
    <span class="gap__pri">🔴</span>
    Category name
    <span class="gap__count">2 of 3 done · 1 open</span>
  </summary>
  <ul>
    <li><span class="gap__title">✅ item title</span> (done YYYY-MM-DD). Brief.</li>
    <li><span class="gap__title">item title.</span> Why it matters.
      <span class="gap__sub">How to close it · effort · who/what blocks.</span></li>
  </ul>
</details>

When it breaks

Stale fast if not maintained. Two sessions of stale state = the page becomes a source of wrong belief about system state. Worse than no dashboard.
R/Y/G can paper over judgment. A 🟢 with a 6-month-rotting dependency is still rotting. Mitigation: in the 🟢 lede, frame it as "silent-failure risk" not "nice-to-have."
Counts drift from reality. Hand-maintained counts go stale when items get added without count update. Mitigation: render via JS when this matters; skip for personal-tool scale.

Trigger to add it to a page

When the page starts having tracked-but-unresolved decisions, bindings, or dependencies that span ≥ 3 categories. Below that, a single TODO list or a Cross-references block is enough. Above that, R/Y/G + collapsible structure starts paying off because the eye needs help finding what matters.

Reference implementation

Canonical exemplar as of 2026-05-27: pa.gf.cx/service-records/ → Read-me · status of the stack. The dashboard tracks the cross-Worker service-records stack (svc.gf.cx + found.gf.cx). After 5 items flipped ✅ in one session, Dan named the underlying pattern — this kb.gf.cx entry codifies it.