← Back to the gamebug or idea?Terrapin Trail//Code BibleIIhow the game works, archive to van
Reel 14 · 6 min read

Tags, links and where players came from

Readable hashtags per tour, registration so they resolve, UTM share links and link previews.

Every tour has a hashtag, and the hashtag is its address: a link, a leaderboard, and something people can post.

Making a tag

#TTGD77Apr reads as Terrapin Trail, Grateful Dead, the tour that started April 1977. The band part is the initials of a multi-word name, or the name itself when it's one word:

●tags.py : 21–31trace ↗
21def band_abbrev(band: str) -> str:
22    """'Grateful Dead' -> 'GD', 'String Cheese Incident' -> 'SCI', 'Phish' -> 'Phish'."""
23    words = [w for w in re.split(r"[^A-Za-z0-9]+", band) if w]
24    if words and words[0].lower() == "the" and len(words) > 1:
25        words = words[1:]
26    if not words:
27        return "X"
28    if len(words) == 1:
29        w = words[0]
30        return (w[0].upper() + w[1:])[:10]
31    return "".join(w[0].upper() for w in words)[:6]
band_abbrev: 'Grateful Dead' -> GD, 'String Cheese Incident' -> SCI, 'Phish' -> Phish.
●tags.py : 34–43trace ↗
34def base_tags(band: str, tours: list[dict]) -> list[str]:
35    """One tag per tour (``tours`` sorted by start date, each with a ``start`` ymd)."""
36    abbrev = band_abbrev(band)
37    seen: dict[str, int] = {}
38    out = []
39    for t in tours:
40        stem = f"TT{abbrev}{t['start'][2:4]}{_MONTHS[int(t['start'][5:7]) - 1]}"
41        seen[stem] = seen.get(stem, 0) + 1
42        out.append(stem + (str(seen[stem]) if seen[stem] > 1 else ""))
43    return out
base_tags: a second tour starting the same month gets a digit (#TTGD77Sep2).

A rule set other than the game as built rides on the end (#TTGD77AprHardRoad, #TTGD77AprX3K9); chapter 15 explains the codes. split takes any of these apart again, case-insensitively, because social platforms treat hashtags that way.

Claiming a tag

Initials collide (GD could be any number of bands), so a tag is registered in the shared store the first time a tour is listed. If another band already owns it, a letter goes in after the band part:

●tags.py : 66–79trace ↗
66def register(store, base: str, info: dict) -> str:
67    """Record that ``base`` names this tour. If another band already owns the tag,
68    insert a letter after the band part until it is unique. Returns the tag to use."""
69    m = re.match(r"^TT(.+?)(\d{2}(?:" + "|".join(_MONTHS) + r")\d?)$", base)
70    stem, tail = (m.group(1), m.group(2)) if m else (base[2:], "")
71    for extra in [""] + list("BCDEFGHJKLMNPQRSTUVWYZ"):
72        candidate = f"TT{stem}{extra}{tail}"
73        key = "tag:" + candidate.lower()
74        if store.set_if_absent(key, info):
75            return candidate
76        existing = store.get(key) or {}
77        if existing.get("collection") == info["collection"] and existing.get("start") == info["start"]:
78            return candidate
79    return base
register: set_if_absent claims the tag; a different band's tour gets #TTGDB77Apr, and so on.

The share link and where visitors came from

Share buttons build a link to /t/<tag> with standard UTM parameters: utm_source (x, reddit, instagram, sms, copy...), utm_medium, utm_campaign (the full tag) and utm_content (the sharer's name). The landing route counts the visit by source and serves the browser page with share-preview tags, so the link unfurls nicely where it's posted:

●runner.py : 264–288trace ↗
264    def tag_landing(tag: str) -> BaseResponse:
265        """A shared tour link: count where the visit came from, then open that tour."""
266        parts = tags.split(tag)
267        if not parts:
268            return redirect("/")
269        base, code = parts
270        code = dna.encode(dna.decode(request.args.get("dna") or code))
271        info = tour_info(base)
272        if not info:
273            return redirect("/")
274        base = info.get("tag", base)
275        full = tags.full_tag(base, code)
276        source = (request.args.get("utm_source") or "direct")[:40].lower()
277        store.zincr("src:" + full.lower(), source)
278        og = {
279            "title": f"#{full} - {info['band']} {info['year']} on Terrapin Trail",
280            "description": f"Drive the {info['band']} tour that started {info['start']}, "
281            "tape the shows, and beat the leaderboard. Real recordings from the Internet Archive.",
282            "type": "website",
283            "image": f"/og/{full}.png",
284        }
285        boot = {
286            "tag": base, "dna": code, "luck": request.args.get("luck"), "from": source,
287            "by": (request.args.get("utm_content") or "")[:24], "donate": DONATE_URL,
288        }
tag_landing: count the source, describe the tour for link previews, and open the browser on that tour and rule set.

The counts feed the "where players came from" bars under each board, and the source rides along on any score the visitor later posts.

Key takeaways
  • A tag names one tour (#TTGD77Apr) plus, optionally, a rule set; every full tag has its own board.
  • Tags are registered in the shared store so a pasted tag resolves to exactly one band and tour.
  • Share links are /t/ with UTM parameters; the landing route counts sources and serves link previews.