learn and share notes on atproto (wip) 馃
malfestio.stormlightlabs.org/
desertthunder.dev
readability
solid
axum
atproto
srs
1# Product + Technical Roadmap
2
3## Roadmap Milestones
4
5### Milestone M - Reliability, Observability, Launch (v0.1.0)
6
7#### Deliverables
8
9**Observability:**
10
11- [ ] Structured logging with correlation IDs
12- [ ] Metrics collection (Tracing spans)
13- [ ] Error tracking
14
15**Reliability:**
16
17- [ ] Database backups + restore drills
18- [ ] Health check endpoints (`/health`, `/ready`)
19- [ ] Graceful shutdown handling
20- [ ] Circuit breakers for external dependencies
21
22**Load Testing:**
23
24- [ ] Study session throughput targets
25- [ ] Feed generation latency benchmarks
26- [ ] Search query performance under load
27
28**Launch Prep:**
29
30- [ ] Beta program signup flow
31- [ ] Feedback collection mechanism
32- [ ] Feature flags for gradual rollout
33
34#### Acceptance
35
36- System handles 10x expected load without degradation.
37- Mean time to recovery < 5 minutes for common failures.
38
39### Milestone N - Deep Linking (v0.2.0)
40
41#### Deliverables
42
43- [ ] AT-URI deep linking from external clients
44- [ ] Handle `at://` URL scheme in app
45- [ ] Link preview generation for shared content (backend OG middleware)
46
47#### Acceptance
48
49- Users can share AT-URIs that open directly to content
50- Shared links show rich previews on Slack, Twitter, Discord, etc.
51
52### Milestone O - Custom Feed Generator (v0.3.0)
53
54#### Deliverables
55
56**Infrastructure:**
57
58- [ ] Feed Generator service with `did:web` identity
59- [ ] Publish `app.bsky.feed.generator` declaration record to creator's repo
60- [ ] DID document with service endpoint for feed requests
61
62**Endpoints:**
63
64- [ ] `app.bsky.feed.getFeedSkeleton` - Return post URIs + cursor for pagination
65- [ ] `app.bsky.feed.describeFeedGenerator` - Feed metadata (DID, name, description)
66- [ ] JWT authentication for user-personalized feeds
67
68**Algorithms:**
69
70- [ ] "Trending Decks" - Top decks by fork/like count in last 7 days
71- [ ] "New from Following" - Latest decks from followed creators
72- [ ] "Study Streak Leaders" - Decks with highest completion rates (anonymized)
73
74**Indexing:**
75
76- [ ] Subscribe to `com.atproto.sync.subscribeRepos` (or Jetstream) for `org.stormlightlabs.malfestio.*` records
77- [ ] Index posts with compound cursor (timestamp::CID) for deterministic pagination
78- [ ] Garbage collect indexed data older than 48 hours (except pinned content)
79
80#### Acceptance
81
82- Custom feed appears in Bluesky and other AT Protocol clients.
83- Feed surfaces relevant learning content based on engagement signals.
84- Pagination works correctly across feed refreshes.
85
86#### Implementation Details
87
88**Core Flow:** see [AT Notes](./at-notes.md#feeds)
89
90**Skeleton Response Format:**
91
92```json
93{
94 "feed": [
95 {"post": "at://did:example/app.bsky.feed.post/1"},
96 {"post": "at://did:example/app.bsky.feed.post/2"}
97 ],
98 "cursor": "1683654690921::bafyrei..."
99}
100```
101
102**Skeleton Metadata Types:**
103
104```typescript
105type SkeletonItem = {
106 post: string // post URI
107 reason?: Reason // optional context (e.g., repost)
108}
109type ReasonRepost = {
110 $type: 'app.bsky.feed.defs#skeletonReasonRepost'
111 repost: string // repost URI
112}
113```
114
115**Considerations:**
116
117- Validate user JWTs if feed depends on user state (follows, likes)
118- Use compound cursor (timestamp::CID) for deterministic pagination
119- Most feeds can garbage collect data older than 48 hours
120- Reference: [Feed Generator Starter Kit](https://github.com/bluesky-social/feed-generator)
121
122### Milestone P - Moderation + Abuse Resistance (v0.4.0)
123
124#### Deliverables
125
126**Labeler Infrastructure:**
127
128- [ ] Dedicated Bluesky account for labeler service
129- [ ] Publish `app.bsky.labeler.service` record to make discoverable
130- [ ] Self-host Ozone backend + UI (Docker setup in `HOSTING.md`)
131- [ ] Configure report types via `goat` CLI
132
133**Endpoints:**
134
135- [ ] `com.atproto.label.subscribeLabels` - real-time label stream
136- [ ] `com.atproto.label.queryLabels` - query published labels
137- [ ] `com.atproto.report.createReport` - accept user reports
138
139**Moderation Features:**
140
141- [ ] Reporting pipeline + review queue UI
142- [ ] Rate limits + spam heuristics
143- [ ] Takedown/visibility states (shadowed, removed, quarantined)
144- [ ] Audit logging for moderation actions
145
146#### Acceptance
147
148- You can safely operate an open publishing surface.
149- Users can subscribe to your labeler and see moderation applied.
150
151**Reference:** [Ozone Moderation Service](https://github.com/bluesky-social/ozone)
152
153### Milestone Q - Readability Updates (v0.5.0)
154
155#### Deliverables
156
157**Multi-page Support:**
158
159- [ ] `single_page_link` directive - find "view full article" link
160- [ ] `next_page_link` directive - paginate through article pages
161- [ ] Concatenate content from multiple pages
162- [ ] Avoid circular pagination
163
164**Advanced Directives:**
165
166- [ ] `http_header(name)` directive - custom headers for fetching
167- [ ] `replace_string(find): replace` directive - text replacement
168- [ ] `find_string` directive - text pattern matching
169
170**Quality:**
171
172- [ ] Better table handling in markdown
173- [ ] Image caption extraction
174- [ ] JSON-LD support
175
176**Performance:**
177
178- [ ] LRU cache for parsed configs
179- [ ] Parallel candidate scoring
180- [ ] Lazy XPath evaluation
181
182**Markdown Conversion:**
183
184- [ ] Custom markdown converter (more control than html2md)
185- [ ] Code block language detection
186
187#### Acceptance
188
189- [ ] Can correctly extract multi-page articles (e.g., long news reports).
190- [ ] Advanced string manipulation allows for cleaner output on tricky sites.
191- [ ] Performance remains stable under high load.
192
193## Open Question/Parked Decisions
194
195- Full offline authoring + later publish
196- Federation depth: publish-to-PDS in the first public beta
197- Content extraction: store extracted article snapshots locally (browser)
198 - Persist only metadata + highlights