WIP! A BB-style forum, on the ATmosphere!
We're still working... we'll be back soon when we have something to show off!
node
typescript
hono
htmx
atproto
docs: add mobile apps plan (React Native + Expo)
Outlines strategy for iOS/Android apps consuming the existing appview
JSON API. Covers technology choice (React Native + Expo), AT Proto OAuth
on mobile, push notifications architecture, offline support, and a
4-phase implementation roadmap. Also adds mobile apps section to the
main project plan's future roadmap.
https://claude.ai/code/session_013mSCQhwArU9acUKZYweD8L
+306
+5
docs/atproto-forum-plan.md
+5
docs/atproto-forum-plan.md
···
207
207
- **Phase C — Federated moderation:** Moderators on different AppView instances (or using third-party tools) can perform mod actions on the Forum DID via delegation, enabling distributed moderation teams.
208
208
- **Phase D — Extract and propose:** Package the delegation spec as a standalone AT Proto proposal with the forum as the reference use case. Contribute upstream.
209
209
210
+
### Mobile Apps (iOS & Android)
211
+
212
+
React Native + Expo cross-platform apps consuming the same `/api/*` endpoints as the web UI. Phased rollout: read-only browse → write/interact → push notifications → offline support & app store release. Full plan in [`docs/mobile-apps-plan.md`](mobile-apps-plan.md).
213
+
210
214
### Other Future Work
211
215
- Nested/threaded replies
212
216
- Full-text search (maybe Meilisearch)
···
219
223
- Custom themes & branding
220
224
- Plugin/extension system
221
225
- Email notifications
226
+
- Push notifications (mobile + web)
222
227
- RSS feeds per category/topic
+301
docs/mobile-apps-plan.md
+301
docs/mobile-apps-plan.md
···
1
+
# atBB Mobile Apps — Plan
2
+
3
+
This document outlines the strategy for building mobile applications for atBB. The existing architecture — a clean JSON API (appview) separate from the server-rendered web UI — makes this straightforward.
4
+
5
+
---
6
+
7
+
## Why Mobile Apps?
8
+
9
+
The web UI (`@atbb/web`) will be responsive and mobile-friendly, but dedicated apps offer:
10
+
11
+
- **Push notifications** for replies, mentions, and moderation events
12
+
- **Native performance** — smooth scrolling through long threads, instant navigation
13
+
- **Offline reading** — cache threads and categories for subway/airplane use
14
+
- **Deep OS integration** — share sheets, AT Proto URI handling, biometric auth
15
+
- **Better compose experience** — native keyboard handling, image picker, draft persistence
16
+
17
+
The web app remains the primary interface. Mobile apps are a complement, not a replacement.
18
+
19
+
---
20
+
21
+
## Architecture Fit
22
+
23
+
The existing system already separates concerns in a way that supports mobile clients:
24
+
25
+
```
26
+
┌─────────────┐
27
+
│ Forum UI │──────┐
28
+
│ (Web App) │ │
29
+
└─────────────┘ │ ┌──────────────┐ ┌─────────────────┐
30
+
├────▶│ AppView │────▶│ Firehose / │
31
+
┌─────────────┐ │ │ (JSON API) │◀────│ User PDS nodes │
32
+
│ Mobile Apps │──────┘ └──────────────┘ └─────────────────┘
33
+
│ (iOS/Andrd) │
34
+
└─────────────┘
35
+
```
36
+
37
+
Mobile apps consume the **same `/api/*` endpoints** as the web UI. No new backend is needed — just the existing appview.
38
+
39
+
### What the appview already provides
40
+
41
+
| Endpoint | Purpose | Mobile use |
42
+
|---|---|---|
43
+
| `GET /api/forum` | Forum metadata | App title, description, branding |
44
+
| `GET /api/categories` | Category list | Home screen / tab bar |
45
+
| `GET /api/categories/:id/topics` | Topic list (paginated) | Category view with pull-to-refresh |
46
+
| `GET /api/topics/:id` | Thread (OP + replies) | Thread view |
47
+
| `POST /api/topics` | Create topic | Compose screen |
48
+
| `POST /api/posts` | Create reply | Reply sheet |
49
+
50
+
### What needs to be added to the appview for mobile
51
+
52
+
| Endpoint / Feature | Purpose |
53
+
|---|---|
54
+
| `POST /api/auth/oauth/start` | Initiate AT Proto OAuth (return redirect URL for in-app browser) |
55
+
| `POST /api/auth/oauth/callback` | Exchange code for session token |
56
+
| `GET /api/users/:did` | User profile / post history |
57
+
| `GET /api/notifications` | Notification feed (replies to your posts, mentions, mod actions) |
58
+
| `POST /api/devices` | Register push notification token (APNs / FCM) |
59
+
| `DELETE /api/devices/:id` | Unregister push token |
60
+
| Pagination headers / cursors | Consistent cursor-based pagination across all list endpoints |
61
+
| `ETag` / `Last-Modified` headers | Conditional requests for efficient caching |
62
+
63
+
These additions benefit the web UI too — they aren't mobile-only concerns.
64
+
65
+
---
66
+
67
+
## Technology Choice: React Native + Expo
68
+
69
+
**Recommendation:** React Native with Expo for cross-platform iOS and Android from a single codebase.
70
+
71
+
### Why React Native + Expo
72
+
73
+
- **Single codebase** for iOS and Android — critical for a small team / solo developer
74
+
- **TypeScript** — same language as the rest of the monorepo; can share types from `@atbb/lexicon`
75
+
- **Expo** simplifies builds, OTA updates, push notifications, and app store submissions
76
+
- **Mature ecosystem** — navigation (React Navigation / Expo Router), state management, networking
77
+
- **AT Proto libraries work** — `@atproto/api` runs in React Native with minor polyfills
78
+
- **AGPL-3.0 compatible** — React Native's MIT license is compatible with the project license
79
+
80
+
### Why not other options
81
+
82
+
| Option | Reason to skip |
83
+
|---|---|
84
+
| Flutter | Dart — different language from the rest of the stack, can't share types |
85
+
| Native (Swift/Kotlin) | Two codebases to maintain, slower iteration for a small team |
86
+
| PWA only | No push notifications on iOS (limited), no app store presence, weaker offline |
87
+
| Capacitor/Ionic | WebView wrapper — won't feel native, performance ceiling |
88
+
89
+
### Monorepo integration
90
+
91
+
Add a new package to the existing workspace:
92
+
93
+
```
94
+
packages/
95
+
lexicon/ # shared types (already exists)
96
+
appview/ # JSON API (already exists)
97
+
web/ # server-rendered UI (already exists)
98
+
mobile/ # NEW — React Native + Expo app
99
+
```
100
+
101
+
The mobile package imports `@atbb/lexicon` for type safety against AT Protocol records. The Turborepo build pipeline extends naturally — `mobile` depends on `lexicon` types just like `web` and `appview` do.
102
+
103
+
---
104
+
105
+
## Mobile App Structure
106
+
107
+
### Screens
108
+
109
+
| Screen | Description | API |
110
+
|---|---|---|
111
+
| **Login** | AT Proto OAuth flow via in-app browser | `/api/auth/oauth/*` |
112
+
| **Home** | Category list, forum branding | `GET /api/categories` |
113
+
| **Category** | Topic list with pull-to-refresh, infinite scroll | `GET /api/categories/:id/topics` |
114
+
| **Topic/Thread** | OP + flat replies, pagination | `GET /api/topics/:id` |
115
+
| **Compose** | New topic form (select category, write post) | `POST /api/topics` |
116
+
| **Reply** | Reply sheet (bottom sheet or modal) | `POST /api/posts` |
117
+
| **Notifications** | Reply/mention/mod action feed | `GET /api/notifications` |
118
+
| **Profile** | User info, post history | `GET /api/users/:did` |
119
+
| **Settings** | Push notification prefs, theme, logout | Local + `/api/devices` |
120
+
121
+
### Navigation
122
+
123
+
```
124
+
Tab Bar
125
+
├── Home (categories → topics → thread)
126
+
├── Notifications
127
+
└── Profile / Settings
128
+
```
129
+
130
+
Use Expo Router (file-based routing) or React Navigation with a bottom tab + stack pattern.
131
+
132
+
### Key Libraries
133
+
134
+
| Concern | Library |
135
+
|---|---|
136
+
| Navigation | Expo Router or React Navigation |
137
+
| HTTP client | Standard `fetch` or `ky` (lightweight) |
138
+
| State / cache | TanStack Query (React Query) — handles caching, pagination, background refetch |
139
+
| Push notifications | `expo-notifications` + server-side APNs/FCM |
140
+
| Secure storage | `expo-secure-store` (for auth tokens) |
141
+
| Auth browser | `expo-auth-session` or `expo-web-browser` (for OAuth redirect) |
142
+
| Offline storage | SQLite via `expo-sqlite` (cache threads for offline reading) |
143
+
144
+
---
145
+
146
+
## Authentication on Mobile
147
+
148
+
AT Proto OAuth on mobile follows the standard OAuth 2.0 + PKCE flow adapted for native apps:
149
+
150
+
1. User enters their handle or PDS URL
151
+
2. App resolves the user's PDS and authorization server
152
+
3. App opens an in-app browser (ASWebAuthenticationSession on iOS, Custom Tab on Android) to the authorization URL with a PKCE challenge
153
+
4. User authenticates on their PDS
154
+
5. PDS redirects back to the app via a custom URI scheme (`atbb://oauth/callback`) or universal link
155
+
6. App exchanges the authorization code for tokens via the appview's callback endpoint
156
+
7. Tokens stored in `expo-secure-store` (keychain on iOS, keystore on Android)
157
+
8. Subsequent API calls include the bearer token
158
+
159
+
The appview mediates this flow — the mobile app doesn't need to implement AT Proto session management directly.
160
+
161
+
---
162
+
163
+
## Push Notifications
164
+
165
+
### Architecture
166
+
167
+
```
168
+
User posts a reply
169
+
│
170
+
▼
171
+
Firehose event
172
+
│
173
+
▼
174
+
AppView indexes reply
175
+
│
176
+
▼
177
+
Notification service checks:
178
+
"Who should be notified?"
179
+
│
180
+
▼
181
+
Sends push via APNs (iOS)
182
+
and/or FCM (Android)
183
+
│
184
+
▼
185
+
Mobile device shows notification
186
+
```
187
+
188
+
### Implementation
189
+
190
+
- Mobile app registers its push token with `POST /api/devices` on login
191
+
- Appview maintains a `devices` table: `(id, user_did, platform, push_token, created_at)`
192
+
- When the indexer processes a new post that is a reply, it checks if the parent post's author or thread participants have registered devices
193
+
- A lightweight push service (can be part of the appview or a separate worker) sends the notification payload
194
+
- Start simple: notify on direct replies only. Expand to mentions, mod actions, thread subscriptions later
195
+
196
+
### Notification types (phased)
197
+
198
+
| Phase | Notification |
199
+
|---|---|
200
+
| Initial | Direct reply to your post |
201
+
| Later | @mention in a post |
202
+
| Later | Mod action on your post (locked, deleted) |
203
+
| Later | New topic in a subscribed category |
204
+
| Later | Thread subscription (get notified on any reply in a thread) |
205
+
206
+
---
207
+
208
+
## Offline Support
209
+
210
+
Use a layered caching strategy:
211
+
212
+
1. **HTTP cache** — TanStack Query caches API responses in memory with configurable stale times
213
+
2. **Persistent cache** — TanStack Query's `persistQueryClient` with AsyncStorage or SQLite for across-app-restart caching
214
+
3. **Explicit offline mode** — "Save thread for offline" downloads thread data to SQLite; viewable without network
215
+
4. **Optimistic writes** — compose a reply offline, queue it, send when back online
216
+
217
+
MVP mobile app only needs layer 1 (in-memory cache). Layers 2-4 come later.
218
+
219
+
---
220
+
221
+
## Implementation Phases
222
+
223
+
### Mobile Phase 0: Scaffold (after web MVP Phase 4+)
224
+
225
+
Prerequisites: Appview API is stable with read endpoints working, AT Proto OAuth is implemented.
226
+
227
+
- [ ] Add `packages/mobile` with Expo + TypeScript template
228
+
- [ ] Configure workspace — `@atbb/lexicon` as dependency for shared types
229
+
- [ ] Set up Expo Router navigation structure (tabs + stacks)
230
+
- [ ] Implement API client layer using `fetch` + TanStack Query
231
+
- [ ] Create basic UI shell: tab bar, placeholder screens
232
+
233
+
### Mobile Phase 1: Read-Only Browse
234
+
235
+
- [ ] Login screen — AT Proto OAuth via `expo-auth-session`
236
+
- [ ] Home screen — category list from `GET /api/categories`
237
+
- [ ] Category screen — topic list with pull-to-refresh and infinite scroll
238
+
- [ ] Thread screen — OP + flat replies with pagination
239
+
- [ ] Basic theming (light/dark mode following system preference)
240
+
- [ ] Loading states, error states, empty states
241
+
242
+
### Mobile Phase 2: Write & Interact
243
+
244
+
- [ ] Compose screen — create new topic (select category, write text)
245
+
- [ ] Reply sheet — reply to a post (bottom sheet UX)
246
+
- [ ] Reactions — tap to react on posts
247
+
- [ ] Profile screen — view your own posts and membership info
248
+
- [ ] Pull-to-refresh and background data sync
249
+
250
+
### Mobile Phase 3: Notifications & Polish
251
+
252
+
- [ ] Push notification registration (`expo-notifications` + APNs/FCM)
253
+
- [ ] Notification feed screen
254
+
- [ ] Appview: `GET /api/notifications` endpoint + push delivery worker
255
+
- [ ] Appview: `POST /api/devices` and `DELETE /api/devices/:id` endpoints
256
+
- [ ] Deep linking — tap notification to open relevant thread
257
+
- [ ] Universal links / custom URI scheme for `at://` URIs
258
+
259
+
### Mobile Phase 4: Offline & Release
260
+
261
+
- [ ] Persistent query cache (survive app restarts)
262
+
- [ ] Offline thread reading (SQLite cache)
263
+
- [ ] Optimistic reply queueing
264
+
- [ ] App store assets (icon, screenshots, descriptions)
265
+
- [ ] TestFlight (iOS) and internal testing track (Android) release
266
+
- [ ] App Store and Google Play submission
267
+
268
+
---
269
+
270
+
## API Versioning & Compatibility
271
+
272
+
To support mobile clients that can't be force-updated instantly:
273
+
274
+
- **Version the API** with a prefix: `/api/v1/categories`, `/api/v1/topics/:id`, etc. The current unversioned endpoints become v1.
275
+
- **Additive changes only** within a version — new fields are always optional, never remove fields
276
+
- **Minimum version header** — mobile app sends `X-ATBB-Client-Version: 1.2.0`; appview can respond with upgrade-required if the client is too old
277
+
- **Deprecation period** — old API versions stay live for at least 6 months after a new version ships
278
+
279
+
---
280
+
281
+
## Estimated Effort
282
+
283
+
| Phase | Scope | Notes |
284
+
|---|---|---|
285
+
| Phase 0 | Scaffold + navigation shell | Straightforward Expo setup |
286
+
| Phase 1 | Read-only browsing + auth | Bulk of the mobile work — screens, auth flow, caching |
287
+
| Phase 2 | Write path + interactions | Compose UX, reply sheets, reactions |
288
+
| Phase 3 | Push notifications | Requires appview additions (notification service, device registration) |
289
+
| Phase 4 | Offline + app store release | Polish, testing, store submission process |
290
+
291
+
Each phase can be developed and shipped independently. Phase 1 alone is a useful read-only companion app.
292
+
293
+
---
294
+
295
+
## Open Questions
296
+
297
+
1. **Expo vs bare React Native?** Start with Expo managed workflow for speed. Eject to bare only if a native module requires it (unlikely for a forum app).
298
+
2. **Shared component library?** If the web UI eventually moves to React (from Hono JSX + HTMX), a shared component package could serve both. For now, keep them separate — the web and mobile UX patterns are different enough.
299
+
3. **Moderation UI on mobile?** Admins/mods may want to moderate from their phone. This could be a separate "admin" tab that appears based on role, or deferred to web-only initially.
300
+
4. **Multiple forum support?** The app could support connecting to multiple atBB instances (different appview URLs). This aligns with the decentralized nature of AT Protocol but adds complexity. Defer to post-v1.
301
+
5. **AT Proto OAuth on mobile maturity?** The OAuth spec for AT Protocol is still evolving. Verify the state of native app support (PKCE, custom URI schemes, DPoP) before starting implementation.