Architecture Overview

Document Roadmap

Executive Summary

The Bluesky social-app is a cross-platform social networking application built on the AT Protocol (Authenticated Transfer Protocol), a decentralized social networking standard. The application enables users to post short-form content, follow other users, engage with feeds curated by third-party feed generators, send direct messages, manage moderation preferences, and participate in a federated social graph. The primary users are individuals seeking an open, decentralized alternative to centralized social media platforms. The application targets iOS, Android, and web browsers from a single React Native codebase.

The technical approach is built on Expo's bare workflow with React Native, enabling access to custom native modules while retaining Expo's build tooling (EAS Build) and over-the-air update infrastructure (EAS Updates). The AT Protocol SDK (@atproto/api) serves as the sole data access layer — there is no traditional REST API or GraphQL layer; all data operations are AT Protocol XRPC calls to the user's Personal Data Server (PDS) and the Bluesky AppView. TanStack Query (React Query) manages all server state, caching, and pagination. React Navigation provides the navigator hierarchy. Lingui handles internationalization across more than 40 locales. React Native Reanimated drives all scroll-synchronized and gesture-driven animations on the UI thread.

The most significant architectural characteristics of this system are: (1) its deep coupling to the AT Protocol as both the identity and data layer, making the application a first-class AT Protocol client rather than a traditional mobile app with a proprietary backend; (2) its cross-platform scope — iOS, Android, and web are all served from the same codebase with platform branching handled through Platform.OS checks, platform() utilities, and .web.tsx file splits; (3) its use of a large number of custom Expo native modules for capabilities such as GIF playback, emoji picking, shared preferences, and scroll forwarding; and (4) its investment in performance through Reanimated UI-thread animations, TanStack Query caching, and the React Compiler for automatic memoization.

This Architecture Overview covers 131 screens of the Bluesky social-app React Native application. The screens assessed include: Inbox, Shell (Search), Feed, Images (Onboarding), Choose Account Form, Status Bar Shadow, Shell (Profile Header), Handle Suggestions, Miscellaneous Notification Settings, Account Settings, Settings (Messages), Utils (Search), Mention Notification Settings, Settings, Deactivated, Log, Hashtag, No Saved Feeds Of Any Type, No Following Feed, No Feeds Pinned, Find Contacts Flow, List Hidden, Shared Preferences Tester, Form Container, Set New Password Form, State (Onboarding), Login Form, Chat List, Emoji Picker, Value Proposition Pager.shared, Gif, Password Updated Form, Verification Settings, Forgot Password Form, Value Proposition Pager, Expo Scroll Forwarder, Index.web (Step Find Contacts Intro), Index.web (Step Find Contacts), Activity List, Layout (Onboarding), Conversation, Avatar Creator Items, Edit Profile Dialog, Growable Banner, Starter Pack Card, Feed Section, Types (Onboarding Step Profile), Const (Post Thread), Value Proposition Pager.web, Interest Button, Metrics, Handle, Growable Avatar, Avatar Circle, Util (Onboarding), Post Liked By, Status Bar Shadow.web, Profile Labeler Liked By, Explore Trending Videos, Explore Trending Topics, Suggested Follows, Profile Followers, Profile Follows, Known Followers, Profile Search, Explore Recommendations, Feed (Profile Sections), Explore Suggested Accounts, Labels (Profile Sections), Search Results, Saved Feeds, Types (Profile Sections), Explore Interests Card, Explore, App Passwords, Activity Privacy Settings, External Media Preferences, Index.web (App Icon Settings), Settings List Item.web (App Icon Settings), App Icon Image, Settings List Item (App Icon Settings), Types (App Icon Settings), Automation Label Settings, Accessibility Settings, Appearance Settings, About Settings, Interests Settings, Content And Media Settings, Find Contacts Settings, Following Feed Preferences, Legacy Notification Settings, Reposts On Reposts Notification Settings, New Follower Notification Settings, Reply Notification Settings, Quote Notification Settings, Privacy And Security Settings, Like Notification Settings, Thread Preferences, Likes On Reposts Notification Settings, Repost Notification Settings, Splash, Starter Pack, Gesture Action, Signup Queued, Draggable Scroll, Takendown, Index.web (Video Feed), Error, Back Next Buttons, Step Details (Starter Pack Wizard), Captcha Web, Types (Video Feed), State (Signup), State (Starter Pack Wizard), Starter Pack Landing, Topic, Step Profiles (Starter Pack Wizard), Step Feeds (Starter Pack Wizard), Policies, Captcha Web View.web, Placeholder Canvas, Display Name, Post Quotes, Avatar Creator Circle, Activity Notification Settings, Profile Header Standard, Post Reposted By, Language Settings, Error State, About Section, and Profile Header Labeler.

Components, patterns, and features not included in the assessed documentation are outside the scope of this document. This document reflects a partial view of the application, as 131 screens represent a significant but not exhaustive portion of the full codebase.

Generated by Inkwell Forge — automated codebase documentation analysis. Subject matter expert review is recommended before distribution.

Stakeholders & Concerns

5.1 Stakeholder Table

5.2 Top Architectural Quality Goals

Derived from patterns observed across the 131 assessed screens:

1. Cross-Platform Consistency — The codebase serves iOS, Android, and web from a single React Native source. Platform differences are handled through explicit branching rather than separate codebases.
2. AT Protocol Compliance — All data operations must conform to AT Protocol lexicons. The application is a first-class AT Protocol client, not a proprietary-backend app.
3. Performance at Scale — Feed screens handle large paginated datasets. Reanimated UI-thread animations, TanStack Query caching, FlatList virtualization, and the React Compiler are all employed to maintain responsiveness.
4. Internationalization — The application supports 40+ locales via Lingui. All user-facing strings must be wrapped in translation macros.
5. Moderation & Safety — Content moderation decisions from the AT Protocol moderation system must be applied consistently across all profile, feed, and messaging surfaces.

System Context

6.1 System Boundary Description

The Bluesky social-app JavaScript bundle runs inside the React Native runtime on iOS and Android, and inside a browser on web. The application boundary encompasses the React Native JavaScript bundle, the custom Expo native modules, and the platform-specific native layers (iOS CocoaPods-linked modules, Android Gradle-linked modules).

Outside the application boundary are: the AT Protocol network (the user's Personal Data Server, the Bluesky AppView, feed generator servers, and labeler services), the Bluesky chat service (a separate DM service endpoint), the Bluesky moderation service (Ozone), push notification infrastructure (APNs on iOS, FCM on Android), the EAS Updates server for OTA bundle delivery, the Sentry error reporting service (when SENTRY_AUTH_TOKEN is configured), and the Bitdrift network instrumentation service.

The mobile client → backend API boundary is the HTTPS/XRPC boundary between the React Native JavaScript runtime and the AT Protocol network. Authentication at this boundary uses AT Protocol session tokens (JWTs) managed by the BskyAgent from @atproto/api. The base URL for the primary Bluesky AppView is https://bsky.social (production) or https://staging.bsky.dev (staging). The chat service uses a separate endpoint routed via DM_SERVICE_HEADERS.

[Diagram: System Context — show the React Native application as a box in the center with the iOS runtime, Android runtime, AT Protocol network (PDS, AppView, feed generators, labelers), Bluesky chat service, Bluesky moderation service (Ozone), APNs, FCM, EAS Updates server, Sentry, and Bitdrift connected]

6.2 External Interfaces Table

Solution Strategy

7.1 Technology Stack

7.2 Platform-Branching Strategy

The codebase uses multiple coexisting platform-branching strategies:

1. Platform.OS === 'ios' / 'android' / 'web' inline checks — Used throughout for platform-specific behavior (e.g., IS_IOS, IS_ANDROID, IS_NATIVE, IS_WEB constants from #/env).
2. Platform.select({ ios: ..., android: ..., web: ... }) — Used for value-based branching (e.g., onEndReachedThreshold, maxToRenderPerBatch).
3. .web.tsx file splits — Used to provide web-specific implementations or stubs. Examples observed: StatusBarShadow.web.tsx (returns null), ValuePropositionPager.web.tsx, CaptchaWebView.web.tsx, VideoFeed/index.web.tsx (returns null), StepFindContactsIntro/index.web.tsx (throws), StepFindContacts/index.web.tsx (throws), AppIconSettings/index.web.tsx (throws), AppIconSettings/SettingsListItem.web.tsx (empty stub).
4. platform() utility from #/alf — Used within the design system for style-level platform branching (e.g., platform({ios: ..., android: ...})).
5. native() / web() utilities from #/alf — Used to apply styles conditionally to native or web only.
6. IS_NATIVE / IS_WEB constants — Build-time constants from #/env used to gate entire feature sections (e.g., the Notification Sounds section in Messages Settings is gated by IS_NATIVE).

The primary strategy is inline IS_* constant checks for behavioral branching and .web.tsx file splits for complete platform-specific implementations or stubs.

7.3 Navigation System Choice

The application uses React Navigation with a combination of Stack and Tab navigators. Expo Router (file-based routing) is not used. The navigator hierarchy is documented in Section 8.2.

Key navigation characteristics observed:

• NativeStackScreenProps is used for type-safe screen props throughout.
• CommonNavigatorParams is a shared type defining route keys and their param shapes.
• navigation.replace() is used for redirect screens (e.g., LegacyNotificationSettings redirects to NotificationSettings).
• useFocusEffect is used extensively for screen-focus lifecycle management (shell mode, data refresh, analytics).
• Deep links are configured via associatedDomains (iOS) and intentFilters (Android) in app.config.js, targeting bsky.app and staging.bsky.app.

[Not documented — WHO: Navigation/routing engineer; WHAT: What is the root navigator type (Stack or Tab) and what are the top-level tab names and their associated stack navigators? WHERE: Section 8.2, Navigator Hierarchy tree]

7.4 Key Architectural Patterns

• Custom hooks for data fetching: All AT Protocol API calls are wrapped in TanStack Query hooks (e.g., usePostFeedQuery, useListConvosQuery, useProfileQuery, useNotificationSettingsQuery). These hooks are the single source of truth for server state.
• Shadow/optimistic state pattern: useProfileShadow and similar hooks maintain a local optimistic copy of server data that reflects in-flight mutations before server confirmation.
• Mutation queue pattern: useProfileFollowMutationQueue and useProfileBlockMutationQueue serialize rapid user interactions to prevent race conditions.
• Portal-based layout: SettingsList.Group uses a custom Portal system to teleport icon and title children to a header row, enabling flexible layout composition.
• Wizard state machines: Multi-step flows (Signup, Onboarding, Starter Pack Wizard, Find Contacts) use useReducer-style state machines with dispatch actions and ScreenTransition animations.
• #/alf design system: All styling uses atomic style tokens from the internal #/alf module rather than inline styles or a third-party UI library.
• Lazy imports for native modules: Heavy native modules (e.g., react-native-view-shot) are loaded via React.lazy() to reduce initial bundle size.

7.5 Approach to Quality Goals

Building Block View

8.1 Level 1 — High-Level Containers

8.2 Level 2 — Navigator Hierarchy

The following tree is derived from screen documentation. Screens not covered in the assessed documentation are marked with [not assessed].

Root Navigator [type not documented — verify with navigation engineer]
  ├── Auth Flow (condition: user is not authenticated or account is deactivated)
  │     ├── Splash (/src/view/com/auth/splash)
  │     ├── Login Flow
  │     │     ├── FormContainer (/login/form-container)
  │     │     ├── ChooseAccountForm (/login/choose-account-form)
  │     │     ├── LoginForm (/login/login-form)
  │     │     ├── ForgotPasswordForm (/login/forgot-password-form)
  │     │     ├── SetNewPasswordForm (/login/set-new-password-form)
  │     │     └── PasswordUpdatedForm (/login/password-updated-form)
  │     ├── Signup Flow
  │     │     ├── State (/signup/state)
  │     │     ├── BackNextButtons (/signup/back-next-buttons)
  │     │     ├── StepInfo → Policies (/signup/step-info/policies)
  │     │     ├── StepHandle → HandleSuggestions (/signup/step-handle/handle-suggestions)
  │     │     ├── StepCaptcha → CaptchaWeb (/signup/step-captcha/captcha-web)
  │     │     │                → CaptchaWebView.web (/signup/step-captcha/captcha-web-view.web)
  │     │     └── SignupQueued (/signup-queued)
  │     ├── Deactivated (/deactivated)
  │     └── Takendown (/takendown)
  │
  └── Main Navigator [type: Tab — not documented, verify with navigation engineer]
        ├── Home Tab [not assessed]
        │     └── Home Stack
        │           ├── NoFeedsPinned (/home/no-feeds-pinned)
        │           └── Feed (/src/view/com/feeds/feed)
        │
        ├── Search Tab
        │     └── Search Stack
        │           ├── Shell (/search/shell)
        │           ├── Utils (/search/utils)
        │           ├── SearchResults (/search/search-results)
        │           ├── Explore (/search/explore)
        │           ├── Explore Modules:
        │           │     ├── ExploreTrendingVideos (/search/modules/explore-trending-videos)
        │           │     ├── ExploreTrendingTopics (/search/modules/explore-trending-topics)
        │           │     ├── ExploreRecommendations (/search/modules/explore-recommendations)
        │           │     ├── ExploreSuggestedAccounts (/search/modules/explore-suggested-accounts)
        │           │     └── ExploreInterestsCard (/search/modules/explore-interests-card)
        │           ├── Hashtag (/hashtag)
        │           └── Topic (/topic)
        │
        ├── Notifications Tab [not assessed]
        │     └── Notifications Stack
        │           └── ActivityList (/notifications/activity-list)
        │
        ├── Messages Tab
        │     └── Messages Stack
        │           ├── ChatList (/messages/chat-list)
        │           ├── Inbox (/messages/inbox)
        │           ├── Conversation (/messages/conversation)
        │           └── Settings (/messages/settings)
        │
        └── Profile/Settings Tab [not assessed]
              └── Settings Stack
                    ├── Settings (/settings)
                    ├── AccountSettings (/settings/account-settings)
                    ├── AppPasswords (/settings/app-passwords)
                    ├── ActivityPrivacySettings (/settings/activity-privacy-settings)
                    ├── ExternalMediaPreferences (/settings/external-media-preferences)
                    ├── AppIconSettings (native only)
                    │     ├── Index.web (/settings/app-icon-settings/index.web) [throws on web]
                    │     ├── SettingsListItem (/settings/app-icon-settings/settings-list-item)
                    │     ├── SettingsListItem.web (/settings/app-icon-settings/settings-list-item.web) [stub]
                    │     ├── AppIconImage (/settings/app-icon-settings/app-icon-image)
                    │     └── Types (/settings/app-icon-settings/types)
                    ├── AutomationLabelSettings (/settings/automation-label-settings)
                    ├── AccessibilitySettings (/settings/accessibility-settings)
                    ├── AppearanceSettings (/settings/appearance-settings)
                    ├── AboutSettings (/settings/about-settings)
                    ├── InterestsSettings (/settings/interests-settings)
                    ├── ContentAndMediaSettings (/settings/content-and-media-settings)
                    ├── FindContactsSettings (/settings/find-contacts-settings)
                    ├── FollowingFeedPreferences (/settings/following-feed-preferences)
                    ├── LegacyNotificationSettings (/settings/legacy-notification-settings) [redirects]
                    ├── NotificationSettings [not assessed]
                    │     └── Notification Sub-Settings:
                    │           ├── MiscellaneousNotificationSettings (/settings/notification-settings/miscellaneous-notification-settings)
                    │           ├── MentionNotificationSettings (/settings/notification-settings/mention-notification-settings)
                    │           ├── RepostsOnRepostsNotificationSettings (/settings/notification-settings/reposts-on-reposts-notification-settings)
                    │           ├── NewFollowerNotificationSettings (/settings/notification-settings/new-follower-notification-settings)
                    │           ├── ReplyNotificationSettings (/settings/notification-settings/reply-notification-settings)
                    │           ├── QuoteNotificationSettings (/settings/notification-settings/quote-notification-settings)
                    │           ├── LikeNotificationSettings (/settings/notification-settings/like-notification-settings)
                    │           ├── LikesOnRepostsNotificationSettings (/settings/notification-settings/likes-on-reposts-notification-settings)
                    │           ├── RepostNotificationSettings (/settings/notification-settings/repost-notification-settings)
                    │           └── ActivityNotificationSettings (/settings/notification-settings/activity-notification-settings)
                    ├── PrivacyAndSecuritySettings (/settings/privacy-and-security-settings)
                    ├── ThreadPreferences (/settings/thread-preferences)
                    ├── LanguageSettings (/settings/language-settings)
                    └── VerificationSettings (/moderation/verification-settings)

Profile Screens (accessible from multiple tabs):
  ├── Profile Header Shell (/profile/header/shell)
  ├── ProfileHeaderStandard (/profile/header/profile-header-standard)
  ├── ProfileHeaderLabeler (/profile/header/profile-header-labeler)
  ├── Profile Header Components:
  │     ├── StatusBarShadow (/profile/header/status-bar-shadow)
  │     ├── StatusBarShadow.web (/profile/header/status-bar-shadow.web) [returns null]
  │     ├── GrowableBanner (/profile/header/growable-banner)
  │     ├── GrowableAvatar (/profile/header/growable-avatar)
  │     ├── DisplayName (/profile/header/display-name)
  │     ├── Handle (/profile/header/handle)
  │     ├── Metrics (/profile/header/metrics)
  │     ├── SuggestedFollows (/profile/header/suggested-follows)
  │     └── EditProfileDialog (/profile/header/edit-profile-dialog)
  ├── Profile Sections:
  │     ├── Feed (/profile/sections/feed)
  │     ├── Labels (/profile/sections/labels)
  │     └── Types (/profile/sections/types)
  ├── ProfileFollowers (/profile/profile-followers)
  ├── ProfileFollows (/profile/profile-follows)
  ├── KnownFollowers (/profile/known-followers)
  ├── ProfileSearch (/profile/profile-search)
  ├── ProfileLabelerLikedBy (/profile/profile-labeler-liked-by)
  └── ErrorState (/profile/error-state)

Post Screens:
  ├── PostLikedBy (/post/post-liked-by)
  ├── PostQuotes (/post/post-quotes)
  └── PostRepostedBy (/post/post-reposted-by)

Onboarding Flow:
  ├── Layout (/onboarding/layout)
  ├── State (/onboarding/state)
  ├── Util (/onboarding/util)
  ├── StepProfile:
  │     ├── AvatarCreatorItems (/onboarding/step-profile/avatar-creator-items)
  │     ├── AvatarCreatorCircle (/onboarding/step-profile/avatar-creator-circle)
  │     ├── AvatarCircle (/onboarding/step-profile/avatar-circle)
  │     ├── PlaceholderCanvas (/onboarding/step-profile/placeholder-canvas)
  │     └── Types (/onboarding/step-profile/types)
  ├── StepInterests → InterestButton (/onboarding/step-interests/interest-button)
  ├── StepSuggestedStarterpacks → StarterPackCard (/onboarding/step-suggested-starterpacks/starter-pack-card)
  ├── StepFindContactsIntro:
  │     └── Index.web (/onboarding/step-find-contacts-intro/index.web) [throws on web]
  ├── StepFindContacts:
  │     └── Index.web (/onboarding/step-find-contacts/index.web) [throws on web]
  └── StepFinished:
        ├── Images (/onboarding/step-finished/images)
        ├── ValuePropositionPager (/onboarding/step-finished/value-proposition-pager)
        ├── ValuePropositionPager.shared (/onboarding/step-finished/value-proposition-pager.shared)
        └── ValuePropositionPager.web (/onboarding/step-finished/value-proposition-pager.web)

Starter Pack Screens:
  ├── StarterPack (/starter-pack)
  ├── StarterPackLanding (/starter-pack/starter-pack-landing)
  └── Wizard:
        ├── State (/starter-pack/wizard/state)
        ├── StepDetails (/starter-pack/wizard/step-details)
        ├── StepProfiles (/starter-pack/wizard/step-profiles)
        └── StepFeeds (/starter-pack/wizard/step-feeds)

Feeds Screens:
  ├── SavedFeeds (/saved-feeds)
  ├── NoSavedFeedsOfAnyType (/feeds/no-saved-feeds-of-any-type)
  └── NoFollowingFeed (/feeds/no-following-feed)

List Screens:
  ├── ListHidden (/list/list-hidden)
  ├── ProfileList → FeedSection (/profile-list/feed-section)
  └── ProfileList → AboutSection (/profile-list/about-section)

Video Feed:
  ├── Index.web (/video-feed/index.web) [returns null]
  └── Types (/video-feed/types)

Find Contacts Flow (/find-contacts-flow)

Utility Screens:
  ├── Log (/log)
  ├── Error (/src/view/com/util/error)
  └── SharedPreferencesTester (/e2e/shared-preferences-tester) [E2E only]

Custom Animations:
  └── GestureAction (/src/lib/custom-animations/gesture-action)

Pager Components:
  └── DraggableScroll (/src/view/com/pager/draggable-scroll)

Native Modules (Custom Expo Modules):
  ├── EmojiPicker (/modules/expo-emoji-picker/src/emoji-picker)
  ├── GifView (/modules/expo-bluesky-gif-view/src/gif)
  └── ExpoScrollForwarder (/modules/expo-scroll-forwarder/src/expo-scroll-forwarder)

⚠️ The root navigator type and the complete tab structure are not fully documented in the assessed screens. The navigator hierarchy above is reconstructed from route keys and screen props observed across 131 screens. Verify the complete navigator tree against the application's root navigation configuration file before treating this as authoritative.

[Diagram: Building Block View — show the navigator hierarchy tree as above, with screen components as leaves, native module integration points (EmojiPicker, GifView, ExpoScrollForwarder, SharedPrefs), and the AT Protocol API boundary]

8.3 Shared Building Blocks

Runtime View

9.1 App Launch & Auth State Resolution

Participants: Root navigator, session state (useSession), BskyAgent, TanStack Query client, Splash screen, Auth flow, Main navigator

Sequence:

1. Metro/Webpack bundle loads; React Native runtime initializes.
2. Root component mounts; SessionProvider initializes and reads persisted session data from device storage.
3. If a valid session exists, BskyAgent is configured with the stored access token.
4. Root navigator evaluates auth state: if currentAccount is defined and not deactivated/takendown, the Main navigator is rendered; otherwise the Auth flow is rendered.
5. If the account is deactivated, the Deactivated screen is shown.
6. If the account is takendown, the Takendown screen is shown.
7. If no session exists, the Splash screen is shown with "Sign In" and "Create Account" CTAs.
8. On successful authentication, onboardingDispatch({type: 'start'}) is called if the user is new; otherwise the Main navigator is shown directly.

Error path: If session restoration fails (e.g., expired token), the user is redirected to the login flow. If the AT Protocol PDS is unreachable, the Deactivated or error screen is shown with a retry option.

[Diagram: Sequence — App Launch & Auth State Resolution]

9.2 Feed Load & Infinite Scroll

Participants: PostFeed component, usePostFeedQuery hook, TanStack Query cache, AT Protocol AppView (app.bsky.feed.getTimeline / app.bsky.feed.getFeed), FlatList (via List component)

Sequence:

1. PostFeed mounts with a FeedDescriptor prop (e.g., "following" or "feedgen|at://...").
2. usePostFeedQuery(feed, feedParams) fires; TanStack Query checks the cache for RQKEY(feed, feedParams).
3. If cache miss or stale, an XRPC GET request is sent to the AT Protocol AppView.
4. Response pages are accumulated in the TanStack Query infinite query cache.
5. feedItems is computed via useMemo — pages are flattened, interstitials are inserted at configured positions, and blocked/muted authors are filtered.
6. List renders the first initialNumToRender items (calculated by useInitialNumToRender).
7. As the user scrolls, onEndReached fires when onEndReachedThreshold is crossed; fetchNextPage() is called.
8. New pages are appended to the cache; feedItems recomputes; List renders new items.
9. A setInterval at POLL_FREQ (60 seconds) calls pollLatest() to check for new content; if found, hasNew is set to true and LoadLatestBtn appears.

Error path: Network errors during initial load render PostFeedErrorMessage with a retry button. Errors during fetchNextPage render LoadMoreRetryBtn at the bottom of the list. HTTP 429 from feed generators surfaces a "high traffic" message.

[Diagram: Sequence — Feed Load & Infinite Scroll]

9.3 Background → Foreground Transition

Participants: AppState (React Native), PostFeed, useMessagesEventBus, useFocusEffect

Sequence:

1. User switches away from the app; AppState transitions to 'background'.
2. PostFeed's AppState.addEventListener('change') listener fires; polling is paused.
3. The messages event bus stops requesting poll intervals (the useFocusEffect cleanup fires in ChatList and Inbox).
4. User returns to the app; AppState transitions to 'active'.
5. PostFeed's AppState listener fires checkForNew(), which calls pollLatest() to check for new feed content.
6. ChatList and Inbox re-register their poll interval requests with useMessagesEventBus.
7. useRefreshOnFocus hooks on focused screens trigger refetch() calls to refresh stale data.

Error path: If the network is unavailable when the app returns to foreground, pollLatest() errors are silently ignored. Data remains stale until the next successful poll or user-initiated pull-to-refresh.

[Diagram: Sequence — Background → Foreground Transition]

9.4 Messaging Real-Time Poll Cycle

Participants: ChatList, Inbox, useMessagesEventBus, useListConvosQuery, AT Protocol chat service

Sequence:

1. ChatList or Inbox gains focus; useFocusEffect fires.
2. useMessagesEventBus().requestPollInterval(MESSAGE_SCREEN_POLL_INTERVAL) is called (10-second interval).
3. The event bus schedules polling at the requested interval.
4. Every 10 seconds, useListConvosQuery is refetched via the event bus mechanism.
5. New conversations or unread counts are reflected in the UI.
6. When the screen loses focus or the app goes to background, the useFocusEffect cleanup calls unsub(), removing the poll interval request.

Error path: Poll errors are caught and logged via logger.error. The UI retains the last successfully fetched state.

[Diagram: Sequence — Messaging Real-Time Poll Cycle]

9.5 Account Creation (Signup) Flow

Participants: Signup state machine (useReducer), BskyAgent, AT Protocol PDS (com.atproto.server.createSession), hCaptcha (via CaptchaWeb / CaptchaWebView.web), useOnboardingDispatch

Sequence:

1. User navigates to the Signup flow; SignupContext initializes with createInitialState.
2. User completes StepInfo (email, password, date of birth, invite code).
3. User completes StepHandle (handle selection with HandleSuggestions).
4. If serviceDescription.phoneVerificationRequired is true, StepCaptcha is shown; CaptchaWeb (native) or CaptchaWebView.web (web) loads the hCaptcha challenge.
5. On CAPTCHA completion, the redirect URL is intercepted; code is extracted and stored in pendingSubmit.
6. useSubmitSignup fires createAccount via useSessionApi(), sending email, handle, password, birthDate, inviteCode, and verificationCode to the AT Protocol PDS.
7. On success, onboardingDispatch({type: 'start'}) transitions the user to the Onboarding flow.
8. On failure, the error is classified (invite code error → back to StepInfo; handle error → back to StepHandle; other → back to StepInfo).

Error path: Network errors surface a connectivity message. InvalidInviteCodeError surfaces a specific invite code message. Handle conflicts surface a handle-specific error.

[Diagram: Sequence — Account Creation (Signup) Flow]

Data Flow & State Management

10.1 Data Sources

10.2 State Management Approach

The application uses a layered state management approach:

10.3 Navigation State as Data

Route params represent data flowing between screens. Key patterns observed:

• Post URI params: name (handle/DID) + rkey (record key) are passed as route params to PostLikedBy, PostQuotes, PostRepostedBy; the screen constructs the AT URI via makeRecordUri(name, 'app.bsky.feed.post', rkey).
• Profile handle params: name (handle or DID) is passed to ProfileFollowers, ProfileFollows, KnownFollowers, ProfileSearch; the screen resolves it to a DID via useResolveDidQuery.
• Search params: q (query) and tab (active tab index) are passed to SearchScreenShell.
• Conversation params: conversation (convoId) and accept (boolean) are passed to Conversation.
• Starter pack params: name + rkey are passed to StarterPack; code is passed to StarterPackScreenShort.
• Notification push params: pushToConversation (convoId) is passed to ChatList to auto-navigate on notification tap.

10.4 Persistence Layer

[Not documented — WHO: Platform/security engineer; WHAT: What storage mechanism is used for session tokens (access JWT, refresh JWT)? Is it Keychain on iOS and Keystore on Android, or AsyncStorage? Is it encrypted?; WHERE: Section 10.4, Persistence Layer table, "Session tokens" row]

10.5 Data Transformation Pipeline

The standard pipeline for AT Protocol data:

AT Protocol XRPC response (JSON)
  → TanStack Query cache (keyed by RQKEY)
  → Custom hook (e.g., usePostFeedQuery, useProfileQuery)
  → useMemo transformation (flatten pages, filter, deduplicate)
  → moderateProfile() / moderation.ui() (apply content moderation)
  → sanitizeDisplayName() / sanitizeHandle() (sanitize for display)
  → Screen component renders

For feed content specifically:

usePostFeedQuery → data.pages → feedItems (useMemo: flatten + interstitial insertion + author filter)
  → List → renderItem → PostFeedItem → RichText + embedded media

For notification settings:

useNotificationSettingsQuery → preferences → PreferenceControls
  → channels (useMemo from preference.list + preference.push)
  → Toggle.Group renders
  → user interaction → useNotificationSettingsUpdateMutation → API write

10.6 Cross-Screen Data Sharing

Cross-Cutting Concerns

11.1 Safe-Area Handling

Safe-area handling is implemented consistently across the application using react-native-safe-area-context. The useSafeAreaInsets() hook is used in:

• StatusBarShadow — sets gradient height to topInset to precisely cover the status bar area.
• ProfileHeaderShell — uses topInset for back button positioning.
• Deactivated screen — applies safeAreaInsets.bottom for bottom padding.
• SignupQueued screen — applies useSafeAreaInsets for bottom action area padding.
• Takendown screen — applies safe area insets for bottom action area.

The Layout.Screen component (used as the root wrapper on virtually all screens) is expected to handle safe area insets system-wide. The react-native-edge-to-edge plugin is configured in app.config.js with enforceNavigationBarContrast: false for Android, enabling edge-to-edge rendering.

11.2 Keyboard Handling

Keyboard handling is not fully consistent across the application:

• KeyboardAwareScrollView from react-native-keyboard-controller is used in Takendown (appeal form), StepProfiles (search input), and StepFeeds (search input).
• KeyboardAvoidingView usage is not directly observed in the assessed screens; keyboard avoidance appears to be delegated to KeyboardAwareScrollView where needed.
• Keyboard.dismiss() is called in ForgotPasswordForm when the hosting provider selector is opened.
• TextField.Input components (used throughout settings and login screens) handle keyboard behavior via their own internal implementation.

[Not documented — WHO: React Native developer; WHAT: Is there a global KeyboardAvoidingView wrapper at the navigator level, or is keyboard handling entirely per-screen? WHERE: Section 11.2, Keyboard Handling]

11.3 Gesture Handling System

react-native-gesture-handler is used for swipe gestures in the messaging screens (GestureActionView in ChatList and Inbox) and for the DraggableScroll horizontal scroll component. The GestureDetector and Gesture APIs from react-native-gesture-handler are used in GestureAction.

The webpack configuration explicitly aliases react-native-gesture-handler to false on web ('react-native-gesture-handler': false), causing a build error if it is accidentally imported in web-only code. This is a deliberate architectural guard.

[Not documented — WHO: React Native developer; WHAT: Is GestureHandlerRootView wrapping the root navigator? If not, swipe gestures in GestureActionView may not function correctly on Android.; WHERE: Section 11.3, Gesture Handling System, and Section 14, Risks & Technical Debt]

11.4 Platform-Branching Consistency

Platform branching is not fully consistent across the codebase — multiple strategies coexist (see Section 7.2). This is an architectural smell but appears to be a deliberate pragmatic choice given the codebase's scale.

The most consistent pattern is the use of IS_* constants from #/env for behavioral branching and .web.tsx file splits for complete platform-specific implementations. The platform() / native() / web() utilities from #/alf are used for style-level branching.

Inconsistencies observed:

• Some screens use IS_NATIVE for feature gating; others use Platform.OS === 'ios' directly.
• The Notification Sounds section in Settings (/messages/settings) is gated by IS_NATIVE; the App Icon Settings link in Settings (/settings) is gated by IS_INTERNAL && IS_NATIVE.
• The SuggestedFollows component returns null on Android (IS_ANDROID) due to scroll interaction conflicts — this is a platform-specific behavioral difference not surfaced through the standard branching utilities.

11.5 Error Handling Strategy

Error handling is per-screen and per-mutation rather than centralized:

• Network errors: Detected via isNetworkError(e) utility; surface a connectivity message to the user.
• AT Protocol errors: Caught in try/catch blocks; error messages are sanitized via cleanError(e) before display.
• TanStack Query errors: Surfaced via isError boolean and error object from query hooks; screens render error states (e.g., ListMaybePlaceholder, Admonition with type="error", ErrorScreen).
• Mutation errors: Surfaced via Toast.show(...) for transient errors; inline ErrorMessage or Admonition for persistent errors.
• Feed generator errors: detectKnownError in PostFeedErrorMessage maps specific error strings to user-friendly messages (HTTP 429, BlockedActorError, FeedgenDoesNotExist, etc.).
• Error logging: logger.error(...) from #/logger is used throughout for structured error logging. Sentry integration (when configured) captures crashes.

No global React Error Boundary is observed in the assessed screens. Error boundaries, if present, are at the navigator or provider level.

11.6 Authentication & Authorization

Authentication is enforced at multiple layers:

1. Navigator level: The root navigator gates the Main navigator behind session state (currentAccount must be defined and not deactivated/takendown).
2. Hook level: useSession() provides currentAccount; components return null or redirect if no account is present.
3. Action level: useRequireAuth() wraps mutating actions (e.g., follow, subscribe) to redirect unauthenticated users to sign-in.
4. API level: The BskyAgent attaches the access JWT to all XRPC requests; the AT Protocol PDS rejects unauthenticated requests.

The access JWT is managed by BskyAgent and refreshed automatically. The resumeSession function is called after account activation and handle changes to refresh the in-memory session.

App Password restriction: Several operations (account deactivation, handle changes) require a full-privilege session token, not an App Password. The server returns 'Bad token scope' for App Password sessions; the client surfaces this as a specific error message.

11.7 Loading & Empty States

Loading and empty states are handled consistently through a set of shared components:

• ListMaybePlaceholder: Used across feed, search, and list screens for loading/empty/error states with a spinner, error message, or empty message.
• PostFeedLoadingPlaceholder: Skeleton rows for the post feed during initial load.
• ChatListLoadingPlaceholder: Skeleton rows for the chat list.
• Loader: Spinner component used inline in buttons, headers, and content areas.
• EmptyState: Icon + message component for empty list states.
• Admonition: Info/warning/error callout box used for inline error states in settings screens.
• Skele.Text: Skeleton text placeholder used in ItemTextWithSubtitle during loading.

The pattern of {data && (...)} guards (rendering nothing until data loads) is used in header subtitle areas (e.g., PostLikedBy, PostRepostedBy, ProfileFollowers).

11.8 Logging & Observability

• Internal logger (#/logger): Used throughout for structured logger.error(...), logger.warn(...), logger.debug(...) calls. The Log screen (/log) provides an in-app viewer for the in-memory log buffer.
• Sentry (@sentry/react-native): Configured conditionally via USE_SENTRY = Boolean(process.env.SENTRY_AUTH_TOKEN). Metro is configured via getSentryExpoConfig; Webpack uses sentryWebpackPlugin. Sentry captures crashes and errors in production builds.
• Bitdrift (@bitdrift/react-native): Configured as an Expo plugin with networkInstrumentation: true, providing network-level observability.
• Analytics (useAnalytics from #/analytics): A custom analytics abstraction used throughout. Fires ax.metric(eventName, payload) for user interactions. The underlying analytics provider is not identifiable from the assessed screens.
• Privacy manifest (iOS): The app.config.js declares collected data types (crash data, performance data, diagnostic data) and accessed API types (file timestamps, disk space, system boot time, user defaults) in the iOS privacy manifest.

11.9 Performance Patterns

11.10 Missing or Not Observed

The following cross-cutting concerns are absent or not observed in the assessed documentation and are architecturally significant:

• GestureHandlerRootView wrapper: Not observed in the assessed screens. If the root navigator is not wrapped in GestureHandlerRootView, swipe gestures in GestureActionView (used in ChatList and Inbox) may not function correctly on Android. This should be verified against the root component.
• Global React Error Boundary: No global error boundary is observed in the assessed screens. Unhandled render errors in any screen could crash the entire navigator subtree.
• Centralized loading state management: Loading states are handled per-screen with no global loading overlay or skeleton system.
• Client-side rate limiting: No client-side rate limiting is implemented for any mutation. Rapid toggling of notification settings, for example, could generate many sequential API calls.
• Debouncing of toggle mutations: Notification settings toggles fire mutations immediately without debouncing. This is consistent across all 10+ notification settings screens.

Architecture Decisions

AD-1: AT Protocol as the Sole Data Layer

• Context: The application needed a data layer for social networking features (posts, follows, profiles, feeds, messages).
• Decision: The AT Protocol (@atproto/api) is the sole data access layer. There is no proprietary REST API, GraphQL endpoint, or direct database connection. All data operations are AT Protocol XRPC calls.
• Rationale: Bluesky is built on the AT Protocol as a decentralized social networking standard. Using the AT Protocol directly makes the application a first-class protocol client, enabling federation with other AT Protocol servers and ensuring data portability.
• Consequences: All data shapes are defined by AT Protocol lexicons. The application is tightly coupled to the AT Protocol SDK version. Feed generator servers are external dependencies with their own failure modes. The detectKnownError function in PostFeedErrorMessage handles feed generator-specific error strings.

AD-2: Expo Bare Workflow with EAS Build

• Context: The application requires custom native modules (GIF playback, emoji picker, shared preferences, scroll forwarding) that are not available in Expo's managed workflow.
• Decision: Expo bare workflow is used, giving full access to the native iOS and Android project files while retaining Expo's build tooling (EAS Build) and update infrastructure (EAS Updates).
• Rationale: The bare workflow provides the flexibility of a fully custom native project while retaining Expo's developer experience for builds, updates, and plugin configuration.
• Consequences: The app.config.js is the single source of truth for native configuration. Custom Expo plugins (withStarterPackAppClip, withGradleJVMHeapSizeIncrease, etc.) handle native configuration that cannot be expressed in app.config.js alone. iOS deployment target is 15.1; Android compileSdkVersion is 36.

AD-3: TanStack Query for All Server State

• Context: The application fetches large amounts of paginated data from the AT Protocol network and needs caching, deduplication, background refetching, and infinite scroll support.
• Decision: TanStack Query v5 (@tanstack/react-query) is used for all server state management. No Redux, Zustand, or MobX is used for server state.
• Rationale: TanStack Query provides built-in support for infinite queries (pagination), cache invalidation, optimistic updates, and background refetching — all of which are required for a social feed application.
• Consequences: All AT Protocol data fetching is wrapped in custom hooks (e.g., usePostFeedQuery, useProfileQuery). Cache keys (RQKEY) are the primary mechanism for cache invalidation across screens. queryClient.invalidateQueries and queryClient.resetQueries are used for cross-screen cache management.

AD-4: React Navigation (Stack + Tab) over Expo Router

• Context: The application needed a navigation solution for a complex multi-tab, multi-stack navigator hierarchy.
• Decision: React Navigation with Stack and Tab navigators is used. Expo Router (file-based routing) is not used.
• Rationale: (inferred from NativeStackScreenProps usage and CommonNavigatorParams type pattern — verify against the navigation configuration file) React Navigation provides more explicit control over navigator configuration and type-safe route params via ParamList types, which is important for a large codebase with many screens.
• Consequences: All screens are registered in a navigator configuration file (not assessed). Route params are typed via CommonNavigatorParams. Deep links are configured via associatedDomains (iOS) and intentFilters (Android) in app.config.js.

AD-5: Lingui for Internationalization

• Context: The application targets a global audience and must support 40+ locales.
• Decision: Lingui (@lingui/core, @lingui/react) is used for all internationalization. The @lingui/babel-plugin-lingui-macro Babel plugin enables compile-time string extraction.
• Rationale: Lingui provides a macro-based approach that integrates with the build pipeline for string extraction, supports pluralization via Plural, and enables runtime locale switching.
• Consequences: All user-facing strings must be wrapped in msg, Trans, or Plural macros. The lingui.config.ts defines 40+ supported locales. The eslint-plugin-lingui enforces correct macro usage. The bsky-internal/lingui-msg-rule ESLint rule enforces project-specific Lingui conventions.

AD-6: React Compiler (Babel Plugin) for Automatic Memoization

• Context: A large React Native codebase with many components requires careful memoization to maintain performance.
• Decision: babel-plugin-react-compiler with target: '19' is configured globally in babel.config.js. The eslint-plugin-react-compiler enforces compiler compatibility.
• Rationale: The React Compiler automatically inserts useMemo, useCallback, and React.memo equivalents, reducing the manual memoization burden on developers.
• Consequences: Components must be written in a way that is compatible with the React Compiler (pure functions, no side effects in render). The react-compiler/react-compiler ESLint rule is set to 'warn' to surface incompatible patterns. Some screens still use explicit useMemo/useCallback for cases where the compiler cannot infer the correct behavior.

AD-7: Reanimated Worklets for Scroll-Driven Animation

• Context: The profile header requires smooth parallax animations (banner scale, avatar scale, blur intensity) synchronized with scroll position.
• Decision: React Native Reanimated with UI-thread worklets is used for all scroll-driven and gesture-driven animations. useAnimatedStyle, useAnimatedProps, useAnimatedReaction, and interpolate run on the UI thread.
• Rationale: Scroll-driven animations must run at 60/120fps without JS thread involvement. Reanimated's worklet system executes animation logic on the native UI thread, bypassing the React JS thread entirely.
• Consequences: Animation logic must be written as Reanimated worklets (no JS-only APIs). SharedValue is used for scroll position; runOnJS bridges back to React state only when necessary (e.g., setActiveAction in GestureAction). collapsable={false} must be set on animated views that need to be measured.

AD-8: OTA Updates via EAS Updates with Code Signing

• Context: The application needs to deliver JavaScript bundle updates to users without requiring App Store/Play Store review cycles.
• Decision: EAS Updates is used for OTA bundle delivery. Code signing is enabled in production and TestFlight builds using RSA (rsa-v1_5-sha256) with a certificate at ./code-signing/certificate.pem.
• Rationale: OTA updates enable rapid bug fixes and feature rollouts. Code signing ensures that only bundles signed by Bluesky can be applied, preventing malicious bundle injection.
• Consequences: checkAutomatically: 'NEVER' means the application controls when to check for updates (not on every launch). The runtimeVersion policy is 'appVersion', meaning OTA updates are scoped to a specific app version. The UPDATES_ENABLED flag gates OTA in TestFlight and production only (not development).

AD-9: New Architecture Disabled

• Context: React Native's New Architecture (Fabric renderer, Turbo Modules, JSI) is available but not yet stable for all use cases.
• Decision: newArchEnabled: false is set in app.config.js.
• Rationale: (inferred from newArchEnabled: false in app.config.js — verify against engineering decision records) The New Architecture may introduce compatibility issues with existing native modules and third-party libraries. The application prioritizes stability over adopting the New Architecture.
• Consequences: The application uses the legacy Bridge architecture. Hermes is used as the JavaScript engine (standard for Expo bare workflow). Turbo Modules and Fabric are not available. This decision should be revisited as the New Architecture matures and third-party library support improves.

AD-10: Platform-Specific File Splits for Web Stubs

• Context: Several features (contact sync, app icon customization, find contacts onboarding) are native-only and must not be accessible on web.
• Decision: .web.tsx file splits are used to provide web-specific stubs that either throw an error, return null, or return an empty component.
• Rationale: Metro's platform-specific file resolution automatically selects .web.tsx files for web builds, ensuring native-only code is never bundled for web without requiring runtime IS_WEB checks in every component.
• Consequences: Web stubs must be maintained alongside native implementations. Stubs that throw (StepFindContactsIntro/index.web.tsx, StepFindContacts/index.web.tsx, AppIconSettings/index.web.tsx) will cause React render errors if not caught by an error boundary. Stubs that return null or empty components (StatusBarShadow.web.tsx, VideoFeed/index.web.tsx, AppIconSettings/SettingsListItem.web.tsx) silently suppress features on web.

AD-11: Custom Native Modules via Expo Modules API

• Context: The application requires native capabilities not available in the standard React Native or Expo SDK: GIF playback, emoji picking, shared preferences, and scroll forwarding.
• Decision: Custom Expo native modules are built using the Expo Modules API and located in the modules/ directory: expo-bluesky-gif-view, expo-emoji-picker, expo-scroll-forwarder, expo-bluesky-swiss-army (shared preferences, background notification handler).
• Rationale: The Expo Modules API provides a type-safe, Swift/Kotlin-first approach to building native modules that integrates cleanly with the Expo bare workflow.
• Consequences: Custom native modules require native code maintenance for both iOS and Android. The expo-bluesky-swiss-army module's SharedPrefs index file contains stub implementations that throw NotImplementedError on web — the actual implementations are in platform-specific native code.

AD-12: Sentry for Crash Reporting (Conditional)

• Context: Production crash reporting is needed to identify and fix issues affecting users.
• Decision: Sentry (@sentry/react-native) is integrated conditionally: USE_SENTRY = Boolean(process.env.SENTRY_AUTH_TOKEN). Metro is configured via getSentryExpoConfig; Webpack uses sentryWebpackPlugin.
• Rationale: Conditional integration allows development builds to run without Sentry overhead while ensuring production builds have full crash reporting.
• Consequences: The SENTRY_AUTH_TOKEN environment variable must be set in EAS Build secrets for production builds. The Metro configuration uses getSentryExpoConfig as the base, which may affect source map generation and bundle splitting.

Quality Attributes

Risks & Technical Debt

Glossary

15.1 Domain Terms

15.2 Architecture Terms