An event companion and onboarding experience for the ATmosphere (alpha)
atmo.quest
docs: design spec for optional event links
Up to 5 {label,url} links per event, edited in admin forms, synced to
the PDS record on create AND edit, shown above the progress bar on the
event detail page.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
authored by
Brittany Ellich
Claude Opus 4.8
and committed by
Tangled
(May 31, 2026, 11:15 PM UTC)
5ab46ff9
3744b3bf
+125
+125
docs/superpowers/specs/2026-05-31-event-links-design.md
+125
docs/superpowers/specs/2026-05-31-event-links-design.md
···
1
+
# Design: Optional Links on Events
2
+
3
+
**Date:** 2026-05-31
4
+
**Status:** Approved, pending implementation plan
5
+
6
+
## Summary
7
+
8
+
Let event organizers attach up to 5 optional links (label + URL) to an event,
9
+
mirroring profile links. Links are edited in the admin event create/edit forms,
10
+
stored both in the canonical `quest.atmo.event` PDS record and the local cache,
11
+
and displayed on the event detail page (`/events/{token}`) directly above the
12
+
"collective progress" bar.
13
+
14
+
## Motivation
15
+
16
+
Events often have associated resources (schedule, venue map, Discord, sponsor
17
+
page). Profiles already support a `{label, url}` link list capped at 5; this
18
+
brings the same affordance to events.
19
+
20
+
## Data model
21
+
22
+
- New type `event.Link{ Label, URL string }`.
23
+
- New constant `event.MaxEventLinks = 5` (mirrors `profile.MaxLinks`).
24
+
- `Links []Link` added to `event.Record`, `event.CreateInput`, and
25
+
`event.UpdateInput`.
26
+
27
+
## Storage (local cache)
28
+
29
+
- New migration `internal/db/migrations/022_event_links.sql` adds a
30
+
`links TEXT NOT NULL DEFAULT ''` column to the `events` table, holding a JSON
31
+
array: `[{"label":"…","url":"…"}]`. Inline JSON mirrors how the profile
32
+
record stores links and avoids a join table.
33
+
- `scanRow` decodes the JSON column into `Record.Links` (tolerant of empty
34
+
string → nil slice).
35
+
- `event.Put`, `event.Cache`, and the new `event.Update` encode `Links` to JSON
36
+
when writing the row.
37
+
38
+
## PDS record (synced on create AND edit)
39
+
40
+
Event edits must keep the canonical PDS record in lockstep with the app — not
41
+
just for links, but for all fields.
42
+
43
+
- **Create** (`event.Put`): the `quest.atmo.event` record value written to the
44
+
organizer's PDS includes a `links` array.
45
+
- **Edit** (new `event.Update(ctx, sess, db, uri, in)`):
46
+
1. Builds the full record value (`name`, `startTime`, `endTime`, `location`,
47
+
`expectedAttendees`, `geofence`, `links`) and calls
48
+
`com.atproto.repo.putRecord` with the existing rkey (via the existing
49
+
`rkeyFromURI` helper) to overwrite the record in the organizer's PDS.
50
+
2. Updates the local cache (the current `UpdateLocal` logic).
51
+
52
+
This replaces the current cache-only `UpdateLocal` edit path. As a direct
53
+
consequence, **name / location / time / attendee edits now also sync to the
54
+
PDS**, which they previously did not. This is intended (the user explicitly
55
+
wants the PDS kept in line with the app).
56
+
57
+
**Shared helper:** `event.Put` and `event.Update` build an identical record-
58
+
value map, so that construction is factored into one `recordValue(...)` helper
59
+
used by both — a single source of truth for the record shape.
60
+
61
+
## Admin editing UI
62
+
63
+
- Add a `links (up to 5)` fieldset to both `AdminEventNew` and `AdminEventEdit`
64
+
forms, mirroring profile's `profileLinkRow` (a label input + URL input per
65
+
row).
66
+
- `AdminEventFormView` gains a `Links []EventLink` field; the edit page
67
+
pre-fills it from the cached event's links.
68
+
- `parseEventForm` parses up to 5 link rows, trims empty rows, and accepts
69
+
`http(s)` URLs only (mirroring profile validation). The cap is enforced
70
+
defensively at parse time.
71
+
- `AdminEventEditSave` acquires the admin's session via
72
+
`h.Auth.RequireSession(w, r)` (as `AdminEventCreate` already does) and passes
73
+
it to `event.Update`. If the PDS write fails, the edit fails loudly with an
74
+
error rendered on the form, rather than letting the cache diverge from the
75
+
PDS.
76
+
77
+
## Display
78
+
79
+
- On the event detail page (`features/events/pages/detail.templ`), a new links
80
+
section is rendered directly above `@eventDetailProgress` (currently
81
+
detail.templ:146).
82
+
- Links render as `.pill-link` pills, matching the profile look.
83
+
- The section is shown only when at least one link exists (links are optional).
84
+
- Display text is the link label; if the label is blank, fall back to the URL's
85
+
host (mirroring profile behavior).
86
+
- `EventDetailView` gains a `Links []EventLink` field, populated by the detail
87
+
handler from the cached event.
88
+
89
+
## Validation and edge cases
90
+
91
+
- Empty rows (both label and URL blank) are dropped at parse time.
92
+
- A row with a URL but no label is kept; the label falls back to the URL host
93
+
at render.
94
+
- Non-`http(s)` URLs are rejected with a form error.
95
+
- More than 5 rows are truncated to 5.
96
+
- Events with no links render no links section and write `links: []` (or omit)
97
+
to the record.
98
+
99
+
## Testing
100
+
101
+
- `internal/event`: JSON round-trip of `Links` through `scanRow` / cache write;
102
+
`event.Update` builds and `putRecord`s the full record value including links
103
+
(using a stub/fake oauth session); `recordValue` produces the expected map.
104
+
- `features/admin`: `parseEventForm` caps at 5, trims empties, rejects non-http
105
+
URLs.
106
+
- View render: detail page omits the links section when there are no links and
107
+
renders pills when present.
108
+
109
+
## Files touched
110
+
111
+
- `internal/event/put.go` — `Link` type, `MaxEventLinks`, `Links` on inputs,
112
+
`recordValue` helper, `event.Update` (replacing cache-only edit path),
113
+
links in `Put`/`Cache`.
114
+
- `internal/event/event.go` — `Links` on `Record`, decode in `scanRow`.
115
+
- `internal/db/migrations/022_event_links.sql` — new `links` column.
116
+
- `features/admin/pages/events.templ` — links fieldset on new + edit forms;
117
+
`Links` on `AdminEventFormView`.
118
+
- `features/admin/handlers.go` — parse links in `parseEventForm`; pre-fill on
119
+
edit page; session + `event.Update` in `AdminEventEditSave`.
120
+
- `features/events/pages/detail.templ` — links section above progress bar;
121
+
`Links` on `EventDetailView`.
122
+
- `features/events/handlers.go` — populate `Links` in the detail view.
123
+
- Regenerated `*_templ.go` files.
124
+
125
+
No new dependencies.