🔗 URL strategy: vanity slugs vs opaque IDs (and the rename gap)

[teetangh]

Context

We're deciding whether public URLs should use human-readable vanity slugs (/courses/demo-academy/system-design-interview) or opaque IDs (/courses/clx7k2j9800abc). The concern raised was that collision-free slug generation is real engineering overhead — a tinyurl-style generator, uniqueness handling, rename logic — and that IDs would sidestep all of it.

Auditing the schema first changes the question. The expensive problem largely doesn't exist here, because slugs are already namespaced.

What we actually have today

Every slug constraint in prisma/models/*.prisma:

Model	Constraint	Scope
Course	@@unique([tenantId, slug])	per tenant
Project	@@unique([tenantId, slug])	per tenant
DigitalProduct	@@unique([tenantId, slug])	per tenant
Cohort	@@unique([courseId, slug])	per course
Tenant	slug String @unique	global — namespace root
PortfolioProfile	slug String @unique	global — public handle
Category, Bundle	slug String @unique	global, platform-managed

Because course and project slugs are unique per tenant, two creators can both own system-design-interview:

• /courses/demo-academy/system-design-interview
• /courses/pixelforge/system-design-interview

No global collision space, therefore no collision-free generator is needed. The required logic is slugify(title) plus a -2 suffix on the rare within-tenant clash.

The only globally-unique slugs are the two that should be — the tenant handle and the portfolio handle. For those, "that name is taken, choose another" is ordinary signup UX, the same as picking a username.

We are already running the hybrid pattern

Public, indexable, shareable surfaces use slugs. The authenticated app uses opaque cuids:

/courses/[tenantSlug]/[courseSlug]        ← public
/projects/[tenantSlug]/[projectSlug]      ← public
/c/[tenantSlug]                           ← public storefront
/p/[slug]                                 ← public portfolio
/verify/[code]                            ← public credential

/learn/courses/[courseId]                 ← in-app, cuid
/learn/projects/[instanceId]              ← in-app, cuid
/studio/[tenantSlug]/courses/[courseId]   ← in-app, cuid
/mentor/instances/[instanceId]            ← in-app, cuid

This split is correct and needs no change.

Both sides, stated fairly

For opaque IDs

• No collision logic at all.
• Renames are free — the URL never changes, so there is nothing to redirect.
• No reserved-path conflicts (/courses/new, /courses/admin).
• No unicode, casing, or profanity handling on creator-supplied text.

For vanity slugs

• A URL a human can read before clicking. This matters most on precisely the pages the business depends on: a credential pasted into a hiring conversation, a course link shared in a WhatsApp group.
• Survives being spoken aloud, printed on a slide, or read off a screen.
• Carries organisational context — demo-academy in the path tells a reader who issued the thing.

Recommendation

Keep slugs on public pages, keep IDs in the app, and build nothing new right now.

1. Do not change course/project slugs. Per-tenant scoping already removed the hard problem. Migrating to IDs would trade a solved problem for a worse public surface.
2. The real gap is renames, not collisions. Today, renaming a course changes its slug and the old URL 404s — breaking any link already shared. This is the only part genuinely worth engineering.
3. Optional future hedge — the Stack Overflow pattern. Resolve by ID and treat the slug as decoration (/questions/11227809/why-is-processing-a-sorted-array-faster serves fine with the text portion altered). That makes renames unbreakable and collisions impossible by construction, without giving up readability. Not needed yet.

Proposed implementation — WITHDRAWN

Superseded by the research comment below. This section proposed a slug_history
table and 301 redirects to fix renames. That gap does not exist: updateCourse and
updateProject never write slug, so renaming a course cannot break its URL. The slug is
set once at creation and is independent of the title thereafter — the same decoupling
Thinkific ships deliberately as its documented default.

No migration, no schema-approved label, no work required. Left visible rather than
deleted, so the reasoning trail stays honest.

Not doing

• Migrating public URLs to opaque IDs.
• Building any collision-free slug generator or short-id service.
• Changing the in-app cuid routes.

Open question

Whether creators should be able to edit a slug independently of the title, or whether it should always be derived. Deriving is simpler and keeps title and URL honest; manual editing is better for SEO and for fixing a bad auto-slug. Leaning derived-by-default with an advanced override, but this is a product call.

---

Market research is complete — see the comment below. It confirms the tenant-namespacing recommendation and contradicts the rename section, which has been withdrawn above.

[teetangh]

Market research — and a correction to this issue

Surveyed 25+ platforms via live URLs, help-centre docs and Google's own documentation. It confirms the main recommendation but contradicts the "Proposed implementation" section above, which is corrected below.

What platforms actually do

Indian edtech — pure descriptive slugs, flat namespace. UpGrad (/data-science-course/), Scaler (/courses/full-stack-developer/), Edureka, Great Learning, Testbook, Vedantu, crio.do. These are single-brand catalogues, so they never had a multi-tenant slug problem. Unacademy is the outlier and the interesting one — a hybrid: unacademy.com/lesson/course-structure-unacademy-plus/NCQAUU0R, slug plus 8-char code, almost certainly because of the volume of educator-generated lessons.

Global edtech — same. Udemy (/course/adobe-photoshop-cc-essentials-training-course/), Coursera, DataCamp, Codecademy, Pluralsight, LinkedIn Learning. edX is the structural outlier with a composite key (course-v1:edX+DemoX+2014) — org-namespaced, still readable, not a UUID.

Multi-tenant creator SaaS — this is our category, and it is unanimous: namespace by tenant. Either a subdomain (Teachable yourschool.teachable.com/p/course-name, Thinkific, Kajabi, Podia, Circle) or a path-prefixed handle (Maven maven.com/wes-kao/build-a-cbc, Skool, GitHub). Every one of them collapses collisions from global to per-tenant — exactly what @@unique([tenantId, slug]) already does here.

Bare opaque IDs are essentially absent from consumer-facing content URLs. The only examples found are Stripe (authenticated dashboard objects, no SEO surface) and YouTube (dominant enough that URL legibility is irrelevant). Neither resembles a marketplace that needs organic discovery and shareable links.

On the hybrid pattern

Medium, Notion, Stack Overflow, Amazon, Linear and Unacademy all converged independently on: an opaque ID is the sole resolution key; the slug is decorative text carried for readability. Notion strips everything before the ID, resolves by ID, and redirects to the current canonical slug if stale.

Worth noting the counter-example: Skillshare has an ID in its URLs but its own help centre still warns that renaming a class breaks the URL and hurts SEO — so appending an ID buys nothing unless you also build resolve-by-ID-ignore-slug. The ID alone is not the fix.

SEO — weaker than the folklore, in both directions

Google's own URL structure docs do recommend /wiki/Aviation over /index.php?topic=42, and /product/black-t-shirt-with-a-white-collar over /product/3243. But the framing throughout is crawlability and human comprehension — never ranking. John Mueller has separately said URL structure is "not a big ranking factor" and gives "minimal additional signal" (reported via trade press, not Google's own docs).

So: the common claim that readable URLs rank better is not supported by anything Google has published. The defensible argument for slugs is trust, shareability and click-through — not ranking.

---

Correction: the rename gap described above does not exist

The issue proposed a slug_history table and 301 redirects, calling renames "the one thing genuinely worth building." That was wrong. Checking the code:

• updateCourse (src/actions/course.ts) — its update payload contains title, subtitle and others, but not slug.
• updateProject (src/actions/projects.ts) — same.
• createCourse takes slug as explicit input, checks tenantId_slug for duplicates, and throws "A course with that slug already exists."

Renaming a course cannot break its URL, because renaming does not touch the slug. The slug is set once at creation and is thereafter independent of the title.

That is exactly what Thinkific ships as its documented default — renaming a course does not change its URL — and Thinkific arrived there deliberately, to avoid the breakage problem. We have it already.

Revised recommendation: build nothing

Both problems that motivated this issue are already solved:

Concern	Status
Collision-free generator	Not needed — @@unique([tenantId, slug]) scopes uniqueness per tenant; create-time check throws a friendly error
Renames breaking links	Cannot happen — the update path never writes slug
Readable public URLs	Already have them, in the shape every comparable platform uses
Opaque IDs where they belong	Already — /learn/... and /studio/... use cuids

No migration, no schema-approved label, no work. The slug_history proposal is withdrawn.

Revisit only if one of these becomes true:

1. A creator asks to change a published slug — then decide between a 301 table and the Stack Overflow pattern. Not before.
2. Slug collisions inside a single tenant become a real support burden — auto-suffix -2 at that point, ~15 lines.
3. Public catalogue volume makes per-tenant namespacing insufficient — unlikely; GitHub scales fine on it.

Honest gap in the evidence

No source covers WhatsApp/Telegram sharing behaviour in India, which is plausibly the dominant discovery channel for this market and more decision-relevant than Google ranking. Nobody publishes whether a readable link out-clicks an opaque one in a WhatsApp group. The recommendation rests on the structural argument and near-universal industry convergence, not on measured Indian sharing data — worth stating plainly rather than implying the evidence is stronger than it is.