desertthunder.dev
a love letter to tangled (android, iOS, and a search API)
1---
2title: App Features
3updated: 2026-03-24
4---
5
6## Search & Discovery
7
8**Depends on:** Search API (Twister), Constellation API
9
10### Search
11
12- Create search service pointing at Twister API
13- Debounced search input on Explore tab
14- Segmented results: repos, users, issues/PRs
15- Recent search history (local storage, clearable)
16- Graceful fallback when search API is unavailable
17
18### Discovery Sections
19
20- Explore tab shows search prominently
21- Optional: trending repos or recently active repos (if data supports it)
22- Profile summaries enriched with Constellation data (star counts, follower counts)
23
24### Home Tab
25
26- Handle-based direct browsing (already works)
27- Surface recently viewed repos/profiles from local history
28- Optional: personalized suggestions for signed-in users (later)
29
30### Activity Feed
31
32- Investigate data sources: Jetstream, polling PDS, or Twister-aggregated feed
33- Activity tab shows recent events from followed users and starred repos
34- Filters by event type (commits, issues, PRs, stars)
35- Infinite scroll with pull-to-refresh
36
37## Authentication & Social
38
39**Depends on:** Bluesky OAuth, Constellation API
40
41### OAuth Sign-In
42
43- Install `@atcute/oauth-browser-client`
44- Host client metadata JSON with required scopes
45- Login page: handle input → resolution → OAuth redirect → callback
46- Capacitor deep link handling for native redirect
47- Session restoration on app launch, automatic token refresh
48- Logout, account switcher for multiple accounts
49- Auth state: idle → authenticating → authenticated → error
50
51### Social Actions
52
53All social actions are AT Protocol record writes to the user's PDS. Counts come from Constellation.
54
55- **Star:** Create/delete `sh.tangled.feed.star` record. Show star count via Constellation `getBacklinksCount`.
56- **Follow:** Create/delete `sh.tangled.graph.follow` record. Show follower count via Constellation.
57- **React:** Create `sh.tangled.feed.reaction` record. Show reaction counts via Constellation.
58- Optimistic UI updates via TanStack Query mutation + cache invalidation.
59
60### Authenticated Profile
61
62- Profile tab shows current user's data when signed in
63- Pinned repos, stats (repos, stars, followers via Constellation)
64- Starred repos list
65- Following/followers lists (via Constellation `getBacklinks`)
66- Settings and logout
67
68### Personalized Feed
69
70- Filter activity feed to followed users and starred repos
71- "For You" / "Global" toggle on activity tab
72
73## Write Features
74
75**Depends on:** Authentication
76
77### Issues
78
79- Create issue: title + markdown body, posted as `sh.tangled.repo.issue` record
80- Comment on issue: threaded comments as `sh.tangled.repo.issue.comment` records
81- Close/reopen: create `sh.tangled.repo.issue.state` record
82
83### Pull Requests
84
85- Comment on PR: `sh.tangled.repo.pull.comment` records
86
87### Profile Editing
88
89- Edit bio, links, location, pronouns, pinned repos
90- Avatar upload (max 1MB, png/jpeg)
91- Cross-posting toggle
92- Posted as updated `sh.tangled.actor.profile` record
93
94### OAuth Scope Upgrade
95
96- Detect when an action requires a scope not yet granted
97- Prompt user to re-authorize with expanded scopes
98
99## Offline & Performance
100
101### Local Storage
102
103All local persistence uses **Dexie** over IndexedDB. This works natively in Capacitor's WebView on both iOS and Android, and in the browser during local development — no platform branching or plugins needed.
104
105Three storage layers, each with a distinct purpose:
106
107- **TanStack Query persister (Dexie-backed)** — Automatic cache persistence. Previously-viewed data hydrates on launch and serves from cache when offline. Subject to normal cache eviction (stale times, GC).
108- **Pinned content store (Dexie)** — User-initiated "save for offline" storage for files, READMEs, and other reference content. Exempt from cache eviction — only the user removes pinned items. Stores file content, metadata, repo handle, pinned timestamp.
109- **Capacitor Preferences** — Small key-value settings (theme, recent search history, feed preferences).
110- **Capacitor Secure Storage** — Auth tokens only. Never in Dexie or the query cache.
111
112### Offline Behavior
113
114- TanStack Query serves cached data when offline (stale-while-revalidate)
115- Pinned files always available regardless of connectivity
116- Offline detection via `navigator.onLine`, persistent banner
117- Mutations disabled when offline
118- Background refresh when connectivity returns
119
120### Pinned Files
121
122Users can pin/save references to files for offline reading:
123
124- Pin action on file viewer saves content + metadata to the Dexie pinned store
125- Pinned files list accessible from profile or a dedicated section
126- Content persists until the user explicitly unpins
127- Pinned items show last-fetched timestamp; refresh when online
128
129### Cache Management
130
131- Per-type limits: repo metadata (200 items/7 days), file trees (50/3 days), profiles (100/7 days), search results (20/1 day)
132- Eviction on app launch and periodically
133- Pinned content exempt from eviction
134- Measure and cap IndexedDB usage
135
136### Performance
137
138- Prefetch on hover/visibility for likely navigation targets
139- Virtualized lists for large datasets (1000+ items)
140- Lazy-load avatars with initials fallback
141- Route-level code splitting
142- Tree-shake Ionic components
143- Target: under 500KB JS, shell first-paint under 2s
144
145## Real-Time & Advanced
146
147**Depends on:** Authentication, Activity Feed
148
149### Jetstream Integration
150
151- Connect to Jetstream for real-time `sh.tangled.*` events
152- Filter and normalize into ActivityItem, merge into TanStack Query cache
153- Connect on foreground, disconnect on background
154- Cursor tracking for gap-free resume
155- Battery-aware throttling
156
157### Live UI Indicators
158
159- "New commits" banner in repo detail
160- "X new items" pill on activity feed
161- Live status updates on PR detail
162- Issue comment count updates
163
164### Custom Feeds
165
166- Presets: "My repos", "Watching", "Team"
167- Feed builder UI for custom filters
168- Local storage in IndexedDB
169
170### Advanced Features
171
172- **Repo forking:** Create repo with source field, show fork status, sync action
173- **Labels:** Display color-coded chips, filter by label, add/remove with auth
174- **Expanded reactions:** Emoji picker, grouped counts, add/remove
175- **PR interdiff:** Compare rounds via `sh.tangled.repo.compare`
176- **Knot info:** Show hostname, version, health status on repo detail