---
title: App Features
updated: 2026-03-24
---

## Search & Discovery

**Depends on:** Search API (Twister), Constellation API

### Search

- Create search service pointing at Twister API
- Debounced search input on Explore tab
- Segmented results: repos, users, issues/PRs
- Recent search history (local storage, clearable)
- Graceful fallback when search API is unavailable

### Discovery Sections

- Explore tab shows search prominently
- Optional: trending repos or recently active repos (if data supports it)
- Profile summaries enriched with Constellation data (star counts, follower counts)

### Home Tab

- Handle-based direct browsing (already works)
- Surface recently viewed repos/profiles from local history
- Optional: personalized suggestions for signed-in users (later)

### Activity Feed

- Investigate data sources: Jetstream, polling PDS, or Twister-aggregated feed
- Activity tab shows recent events from followed users and starred repos
- Filters by event type (commits, issues, PRs, stars)
- Infinite scroll with pull-to-refresh

## Authentication & Social

**Depends on:** Bluesky OAuth, Constellation API

### OAuth Sign-In

- Install `@atcute/oauth-browser-client`
- Host client metadata JSON with required scopes
- Login page: handle input → resolution → OAuth redirect → callback
- Capacitor deep link handling for native redirect
- Session restoration on app launch, automatic token refresh
- Logout, account switcher for multiple accounts
- Auth state: idle → authenticating → authenticated → error

### Social Actions

All social actions are AT Protocol record writes to the user's PDS. Counts come from Constellation.

- **Star:** Create/delete `sh.tangled.feed.star` record. Show star count via Constellation `getBacklinksCount`.
- **Follow:** Create/delete `sh.tangled.graph.follow` record. Show follower count via Constellation.
- **React:** Create `sh.tangled.feed.reaction` record. Show reaction counts via Constellation.
- Optimistic UI updates via TanStack Query mutation + cache invalidation.

### Authenticated Profile

- Profile tab shows current user's data when signed in
- Pinned repos, stats (repos, stars, followers via Constellation)
- Starred repos list
- Following/followers lists (via Constellation `getBacklinks`)
- Settings and logout

### Personalized Feed

- Filter activity feed to followed users and starred repos
- "For You" / "Global" toggle on activity tab

## Write Features

**Depends on:** Authentication

### Issues

- Create issue: title + markdown body, posted as `sh.tangled.repo.issue` record
- Comment on issue: threaded comments as `sh.tangled.repo.issue.comment` records
- Close/reopen: create `sh.tangled.repo.issue.state` record

### Pull Requests

- Comment on PR: `sh.tangled.repo.pull.comment` records

### Profile Editing

- Edit bio, links, location, pronouns, pinned repos
- Avatar upload (max 1MB, png/jpeg)
- Cross-posting toggle
- Posted as updated `sh.tangled.actor.profile` record

### OAuth Scope Upgrade

- Detect when an action requires a scope not yet granted
- Prompt user to re-authorize with expanded scopes

## Offline & Performance

### Local Storage

All 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.

Three storage layers, each with a distinct purpose:

- **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).
- **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.
- **Capacitor Preferences** — Small key-value settings (theme, recent search history, feed preferences).
- **Capacitor Secure Storage** — Auth tokens only. Never in Dexie or the query cache.

### Offline Behavior

- TanStack Query serves cached data when offline (stale-while-revalidate)
- Pinned files always available regardless of connectivity
- Offline detection via `navigator.onLine`, persistent banner
- Mutations disabled when offline
- Background refresh when connectivity returns

### Pinned Files

Users can pin/save references to files for offline reading:

- Pin action on file viewer saves content + metadata to the Dexie pinned store
- Pinned files list accessible from profile or a dedicated section
- Content persists until the user explicitly unpins
- Pinned items show last-fetched timestamp; refresh when online

### Cache Management

- Per-type limits: repo metadata (200 items/7 days), file trees (50/3 days), profiles (100/7 days), search results (20/1 day)
- Eviction on app launch and periodically
- Pinned content exempt from eviction
- Measure and cap IndexedDB usage

### Performance

- Prefetch on hover/visibility for likely navigation targets
- Virtualized lists for large datasets (1000+ items)
- Lazy-load avatars with initials fallback
- Route-level code splitting
- Tree-shake Ionic components
- Target: under 500KB JS, shell first-paint under 2s

## Real-Time & Advanced

**Depends on:** Authentication, Activity Feed

### Jetstream Integration

- Connect to Jetstream for real-time `sh.tangled.*` events
- Filter and normalize into ActivityItem, merge into TanStack Query cache
- Connect on foreground, disconnect on background
- Cursor tracking for gap-free resume
- Battery-aware throttling

### Live UI Indicators

- "New commits" banner in repo detail
- "X new items" pill on activity feed
- Live status updates on PR detail
- Issue comment count updates

### Custom Feeds

- Presets: "My repos", "Watching", "Team"
- Feed builder UI for custom filters
- Local storage in IndexedDB

### Advanced Features

- **Repo forking:** Create repo with source field, show fork status, sync action
- **Labels:** Display color-coded chips, filter by label, add/remove with auth
- **Expanded reactions:** Emoji picker, grouped counts, add/remove
- **PR interdiff:** Compare rounds via `sh.tangled.repo.compare`
- **Knot info:** Show hostname, version, health status on repo detail