01 — Naming Conventions

A consistent name is the cheapest documentation we have. When a Worker is paging someone at 2 a.m., the name alone should tell them what it does, who it belongs to, and whether it’s production.

The pattern

{scope}-{category}-{project}[-{service}]-{env}

Worker names in Cloudflare are lowercase, 1–63 characters, and may only contain a–z, 0–9, and -. This pattern complies with that constraint and still leaves headroom for meaningful names.

Segment definitions

Segment	Required	Rules	Purpose
scope	Yes	2–6 lowercase letters. adv for Adventive-owned. Client short-codes for client builds (e.g. acme, nova, rho). Subsidiary brands get their own code.	Answers “who owns this?” at a glance.
category	Yes	One of int, site, svc, cli.	Answers “what kind of thing is this?”
project	Yes	3–24 chars, kebab-case, lowercase letters, digits, and hyphens only. No leading/trailing hyphen.	The product, site, or client engagement this Worker is part of.
service	Optional	Same rules as project, typically 3–10 chars. Use only when a project has more than one Worker.	Distinguishes Workers within the same project (e.g. api, cron, webhook, edge, img).
env	Yes	Exactly one of dev, stg, prd.	The deployment environment. Always last so the eye finds it.

Category codes

Code	Meaning	Typical examples
int	Internal tool — built for Adventive staff or internal workflows.	ops dashboards, billing helpers, internal webhooks
site	Full website — a web property or its edge logic.	marketing site, docs site, landing page, SSR shell
svc	Microservice / API — a shared or standalone service consumed by other systems.	turnstile proxy, image resizer, form relay, auth helper
cli	Client-specific build — scoped to a single client engagement, not a reusable platform.	ACME campaign page, client X’s form handler

Environment codes

We use exactly three environments. No more (inventing qa, uat, pilot creates drift); no fewer (skipping staging is how outages happen).

Code	Name	Purpose
dev	Development	Per-engineer or shared dev. Allowed to break. Never routed to customer traffic.
stg	Staging	Mirror of production config and bindings, but using non-production data stores. Every change lands here first.
prd	Production	Customer-facing. Change only via the promote-from-staging flow in 04 — QA & Deployment.

Worked examples

Worker name	What it is
adv-int-ops-dashboard-prd	Internal ops dashboard, production
adv-int-billing-sync-cron-stg	Internal billing-sync scheduled Worker, staging
adv-site-marketing-edge-prd	Edge Worker fronting the Adventive marketing site, production
adv-site-docs-stg	Adventive docs site, staging (single-Worker project — no service segment)
adv-svc-turnstile-proxy-prd	Turnstile verification proxy microservice, production
adv-svc-image-resize-dev	Image-resizing service, developer sandbox
adv-svc-form-relay-webhook-prd	Webhook-handler variant of the form-relay service, production
acme-cli-landing-edge-prd	Client ACME’s landing-page edge Worker, production
nova-cli-intake-api-stg	Client Nova’s lead-intake API, staging

Naming everything else

Workers don’t live alone. KV namespaces, D1 databases, R2 buckets, Queues, Durable Object namespaces, secrets, and DNS routes all get named by the same segment logic, with a type prefix. This makes searching the dashboard trivial — one search for acme-cli-landing surfaces the Worker, its KV, its R2, and its routes together.

Resource	Pattern	Example
Worker	{scope}-{category}-{project}[-{service}]-{env}	adv-svc-form-relay-prd
KV namespace	kv-{scope}-{category}-{project}[-{purpose}]-{env}	kv-adv-svc-form-relay-sessions-prd
D1 database	d1-{scope}-{category}-{project}-{env}	d1-adv-int-billing-sync-prd
R2 bucket	r2-{scope}-{category}-{project}[-{purpose}]-{env}	r2-adv-svc-image-resize-cache-prd
Queue	q-{scope}-{category}-{project}-{purpose}-{env}	q-adv-svc-form-relay-inbound-prd
Durable Object namespace	do-{scope}-{category}-{project}-{purpose}-{env}	do-adv-site-marketing-ratelimit-prd
Secret	SCREAMING_SNAKE_CASE inside the Worker; no env suffix (each env has its own secret store).	STRIPE_SECRET_KEY
DNS route (zones)	Human-friendly hostname; map to Worker via route, not name.	forms.adventive.com/* → adv-svc-form-relay-prd
Wrangler env name (inside wrangler.toml)	Match the env suffix: dev, staging, production.	—

Note on Wrangler env names vs. Worker names. Cloudflare’s own conventions use the full words staging and production inside wrangler.toml’s [env.*] tables. We follow that inside the config file, but the deployed Worker name still ends in stg / prd via the name override in each env block. Section 02 shows exactly how.

Tags — the sidecar metadata

Cloudflare lets you tag Workers. Every Adventive Worker carries these tags, set via Wrangler or the dashboard, because they power cost reports and ownership lookups that the name alone can’t:

• owner:<team-or-person> — e.g. owner:platform, owner:client-services
• criticality:<tier> — one of tier-1, tier-2, tier-3 (see 05 — Resiliency & DR)
• cost-center:<code> — for chargeback on client work
• repo:<github-slug> — so anyone in the dashboard can find the source in one click

Rules of thumb

1. When in doubt, include the service segment. A name with one too many segments is easy to read. A name where two Workers collide is painful.
2. Don’t encode version numbers in names. Use git tags, Worker versions, and Wrangler’s gradual deploys. A Worker named adv-svc-form-relay-v2-prd is a sign we botched a migration.
3. Rename by creating, not editing. Cloudflare doesn’t support Worker rename. If a name is wrong, deploy the correctly named Worker, move the route, verify, then delete the old one.
4. Client scopes must be pre-registered. Before deploying the first {clientcode}-cli-* Worker, add the client code to the table in this document via PR. This keeps the short-code registry auditable.

Registered scopes

Code	Owner	Notes
adv	Adventive	Default for everything Adventive-owned.
(add rows via PR as clients onboard)

---

See also: 02 — Wrangler Configuration for how these names are wired into config.