an app to share curated trails
sidetrail.app
1# Sidetrail Lexicons
2
3Three record types stored in users' ATProto repositories.
4
5## `app.sidetrail.trail`
6
7A trail with 2-12 embedded stops.
8
9```json
10{
11 "title": "Getting Started with Bluesky",
12 "description": "A quick tour of the basics",
13 "stops": [
14 {
15 "tid": "3abc...",
16 "title": "Create an account",
17 "content": "Head to bsky.app and sign up...",
18 "buttonText": "Done",
19 "external": {
20 "uri": "https://bsky.app",
21 "title": "Bluesky",
22 "thumb": { "$type": "blob", ... }
23 }
24 }
25 ],
26 "accentColor": "#e8a87c",
27 "backgroundColor": "#fdf8f3",
28 "createdAt": "2024-01-01T00:00:00Z"
29}
30```
31
32Stops have stable TIDs so they survive reordering. The `external` field can hold http(s) URLs or at:// URIs (for embedding Bluesky posts).
33
34## `app.sidetrail.walk`
35
36Tracks a user's progress through a trail. Deleted on completion or abandon.
37
38```json
39{
40 "trail": {
41 "uri": "at://did:plc:xyz/app.sidetrail.trail/abc",
42 "cid": "bafyrei..."
43 },
44 "visitedStops": ["3abc...", "3def..."],
45 "createdAt": "2024-01-01T00:00:00Z",
46 "updatedAt": "2024-01-01T00:01:00Z"
47}
48```
49
50The app only respects the most recent walk per trail (by TID). `visitedStops` grows as the user progresses - current position is the last item.
51
52## `app.sidetrail.completion`
53
54Permanent record that a user finished a trail.
55
56```json
57{
58 "trail": {
59 "uri": "at://did:plc:xyz/app.sidetrail.trail/abc",
60 "cid": "bafyrei..."
61 },
62 "createdAt": "2024-01-01T00:05:00Z"
63}
64```
65
66Uses a strong ref (uri + cid) so we know exactly which version was completed. Users can complete the same trail multiple times.
67
68## Lifecycle
69
701. **Start walking**: Create a walk record with `visitedStops = [firstStopTid]`
712. **Advance**: Append the next stop TID to `visitedStops`
723. **Complete**: Delete the walk, create a completion
734. **Abandon**: Just delete the walk
74
75## Editing
76
77Trails can be edited in place (same URI, new CID). Stop TIDs survive reordering. If a stop is deleted mid-walk, the client handles it gracefully.