Architecture Overview

3. Document Roadmap

4. Executive Summary

Bluesky Social (social-app) is a decentralized social networking application built on the AT Protocol (Authenticated Transfer Protocol), an open standard for federated social data. The application allows users to create accounts, compose posts, follow other users, discover content through algorithmic and custom feeds, exchange direct messages, and manage moderation preferences. The primary users are individuals seeking an open, user-controlled social media experience across iOS, Android, and web platforms.

The application is built with React Native and Expo (bare workflow), sharing a single TypeScript codebase across iOS, Android, and Expo Web. Navigation is implemented with React Navigation using native stack navigators. Server state is managed exclusively with TanStack Query (React Query), which handles caching, pagination, and background refetching for all AT Protocol API calls. The application communicates with the AT Protocol network — specifically Bluesky's AppView and Personal Data Servers — using the @atproto/api SDK. All user-facing strings are internationalized using Lingui, with support for over 40 locales.

The most significant architectural characteristics of this system are: (1) the AT Protocol as the sole backend integration point, meaning all data — posts, profiles, feeds, notifications, direct messages, and preferences — flows through AT Protocol XRPC endpoints; (2) a multi-platform codebase with a consistent platform-branching strategy using IS_IOS, IS_ANDROID, IS_NATIVE, and IS_WEB constants derived at build time; (3) a rich set of custom Expo native modules for capabilities not covered by the standard Expo SDK, including background notification handling, GIF rendering, emoji picking, and shared preferences; and (4) OTA (over-the-air) update delivery via EAS Updates with RSA code-signing, enabling production updates without App Store review cycles.

This Architecture Overview covers 130 screens of the Bluesky Social React Native application. The screens assessed include: Value Proposition Pager.shared, Reply Notification Settings, Index.web (onboarding/step-find-contacts-intro), Settings (messages), Index.web (onboarding/step-find-contacts), Profile Follows, Profile Header Standard, Choose Account Form, Avatar Circle, Status Bar Shadow.web, Handle, Miscellaneous Notification Settings, Mention Notification Settings, Quote Notification Settings, App Passwords, About Settings, Interests Settings, Policies, Types (app-icon-settings), Use App Icon Sets, Content And Media Settings, Automation Label Settings, Appearance Settings, Following Feed Preferences, External Media Preferences, Find Contacts Settings, Profile Header Labeler, Shared Preferences Tester, Shell (profile/header), Status Bar Shadow, Like Notification Settings, Likes On Reposts Notification Settings, Index.web (settings/app-icon-settings), App Icon Image, Settings List Item (app-icon-settings), Activity Privacy Settings, Account Settings, Settings List Item.web, Signup Queued, Legacy Notification Settings, Utils (search), State (onboarding), Metrics, Use Suggested Onboarding Users, Accessibility Settings, Deactivated, Language Settings, Gesture Action, Activity Notification Settings, Settings, Splash, Inbox, Expo Scroll Forwarder, Gif, List Hidden, Find Contacts Flow, No Saved Feeds Of Any Type, Set New Password Form, Password Updated Form, No Following Feed, Log, Activity List, Form Container, Chat List, Emoji Picker, Forgot Password Form, Layout (onboarding), Verification Settings, Login Form, No Feeds Pinned, Conversation, Hashtag, Growable Banner, Edit Profile Dialog, Avatar Creator Items, Const (post-thread), Types (onboarding/step-profile), Interest Button, Avatar Creator Circle, Util (onboarding), Placeholder Canvas, Post Reposted By, Post Liked By, Error State, Display Name, Post Quotes, Starter Pack Card, Growable Avatar, Feed Section, About Section, Types (profile/sections), Profile Labeler Liked By, Profile Followers, Profile Search, Known Followers, Explore Suggested Accounts, Labels, Suggested Follows, Feed (profile/sections), Explore Interests Card, Explore Recommendations, Search Results, Saved Feeds, Explore Trending Videos, Explore Trending Topics, Explore, Shell (search), Back Next Buttons, New Follower Notification Settings, Handle Suggestions, Repost Notification Settings, Thread Preferences, Reposts On Reposts Notification Settings, State (signup), Captcha Web View.web, Captcha Web, Privacy And Security Settings, Draggable Scroll, State (starter-pack/wizard), Error, Step Profiles, Index.web (video-feed), Step Details, Starter Pack Landing, Starter Pack, Step Feeds, Takendown, Types (video-feed), Feed (src/view/com/feeds/feed), and Topic. 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 130 screens represent a significant but not exhaustive portion of the full codebase.

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

5. Stakeholders & Concerns

5.1 Stakeholder Table

5.2 Top Architectural Quality Goals

Based on patterns observed across the 130 assessed screens, the following quality goals are demonstrably prioritized in the codebase:

1. Cross-Platform Consistency — A single TypeScript codebase targets iOS, Android, and web with explicit, controlled platform divergence via IS_IOS, IS_NATIVE, and IS_WEB constants.
2. AT Protocol Compliance — All data operations flow through the @atproto/api SDK; no alternative backend integrations are present.
3. Internationalization Completeness — All user-facing strings are wrapped in Lingui macros (msg, <Trans>, <Plural>), supporting 40+ locales.
4. Performance at Scale — TanStack Query infinite queries with FlatList/FlashList virtualization, React.memo, useMemo, and useCallback are applied consistently across list-heavy screens.
5. Moderation & Safety — moderateProfile and related AT Protocol moderation functions are applied before rendering user-generated content throughout the profile and feed surfaces.

6. System Context

6.1 System Boundary Description

The Bluesky Social mobile application is the system under description. It runs as a React Native JavaScript bundle executing within the iOS and Android runtimes (and as a web application in browsers via Expo Web). The application boundary encompasses all JavaScript/TypeScript code, bundled assets, and custom native modules.

Outside the application boundary are: the AT Protocol network (Bluesky AppView, Personal Data Servers), the native iOS and Android operating system layers, push notification delivery infrastructure (APNs and FCM), the EAS Updates OTA service, the Sentry crash reporting service (when configured), the hCaptcha verification service (used during signup), and the Bitdrift network instrumentation service.

The mobile client communicates with the AT Protocol backend exclusively over HTTPS using the XRPC protocol (a JSON-over-HTTP RPC convention defined by the AT Protocol lexicon). Authentication uses JWT-based session tokens managed by the @atproto/api agent.

[Diagram: System Context — show the React Native application as a box in the center with the iOS runtime, Android runtime, AT Protocol AppView/PDS, EAS Updates service, APNs, FCM, Sentry, hCaptcha, and Bitdrift connected as external systems]

6.2 External Interfaces Table

7. Solution Strategy

7.1 Technology Stack

7.2 Platform-Branching Strategy

The codebase uses a constants-based branching strategy as its primary mechanism. Platform constants are defined in #/env and derived from Platform.OS at build time:

• IS_IOS — true when Platform.OS === 'ios'
• IS_ANDROID — true when Platform.OS === 'android'
• IS_NATIVE — true on iOS or Android (not web)
• IS_WEB — true on Expo Web

These constants are used throughout the codebase in conditional expressions (e.g., IS_NATIVE ? 2 : 0.25 for onEndReachedThreshold), style utilities (e.g., native(a.absolute), web(a.sticky)), and full component exclusions (e.g., if (IS_ANDROID) return null in ProfileHeaderSuggestedFollows).

File-extension platform splits (.web.tsx) are used for screens that have no viable web implementation. Examples observed:

• StepFindContactsIntro/index.web.tsx — throws Error('StepFindContactsIntro is not available on web')
• StepFindContacts/index.web.tsx — throws Error('StepFindContacts is not available on web')
• AppIconSettings/index.web.tsx — throws Error('Not supported on web')
• AppIconSettings/settings-list-item.web.tsx — returns undefined (stub)
• StatusBarShadow.web.tsx — returns null
• CaptchaWebView.web.tsx — web-specific iframe implementation
• VideoFeed/index.web.tsx — returns null (stub)

Platform.select() is not observed as a primary branching mechanism; the constants approach is dominant.

7.3 Navigation System Choice

The application uses React Navigation with native stack navigators. The root navigator structure is not fully visible from the assessed screens alone, but the following navigator types are evidenced:

• NativeStackScreenProps is used as the screen props type across all navigated screens, confirming React Navigation native stack usage.
• CommonNavigatorParams and AllNavigatorParams are the typed param lists for the two primary navigator scopes.
• MessagesTabNavigatorParams is a separate param list for the messages tab navigator.
• A Pager component (used in Profile, Search/Explore, Hashtag, and Topic screens) provides horizontal swipe-between-tabs behavior within screens, distinct from the navigator hierarchy.

[Not documented — WHO: Mobile platform lead; WHAT: What is the complete root navigator structure (root navigator type, auth stack vs. main stack split, tab navigator configuration, drawer navigator if any)?; WHERE: §7.3 Navigation System Choice and §8.2 Navigator Hierarchy]

7.4 Key Architectural Patterns

1. TanStack Query for all server state — Every API call is wrapped in a useQuery, useMutation, or useInfiniteQuery hook. No raw fetch calls appear in screen components (except in ExportCarDialog for a specific JSONL endpoint that the XRPC client cannot handle).
2. Custom hooks for data fetching — Query hooks are co-located in #/state/queries/ and expose typed data, loading, and error states to screens.
3. Profile shadow system — useProfileShadow wraps profile data with a local optimistic overlay, allowing follow/block state changes to reflect immediately without a full refetch.
4. Shared wizard state via React Context — Multi-step flows (onboarding, signup, starter pack wizard) use a useReducer-backed context provider (useWizardState, useOnboardingInternalState, SignupContext) to share state across steps.
5. Layout component system — Layout.Screen, Layout.Header.*, and Layout.Content are shared primitives used consistently across all settings and profile screens.
6. SettingsList component system — SettingsList.Container, SettingsList.Item, SettingsList.LinkItem, SettingsList.Group, and related components provide a consistent settings list UI across all settings screens.
7. Portal-based layout injection — createPortalGroup() is used in SettingsList.Group and the onboarding Layout to teleport icon/header content into a parent row without prop drilling.
8. cleanError for user-facing error messages — All API error strings are passed through cleanError() before display to strip internal details.

7.5 Approach to Quality Goals

8. Building Block View

8.1 Level 1 — High-Level Containers

8.2 Level 2 — Navigator Hierarchy

The following hierarchy is derived from NativeStackScreenProps type annotations, CommonNavigatorParams, AllNavigatorParams, and MessagesTabNavigatorParams observed across the 130 assessed screens. The root navigator structure is inferred from the presence of auth-gated screens and the logged-out shell.

[Not documented — WHO: Mobile platform lead; WHAT: The complete root navigator definition file(s) — specifically the root navigator type (Stack/Tab/Drawer), the auth stack vs. main stack split condition, and the tab navigator configuration for the main app; WHERE: §8.2 Navigator Hierarchy tree below]

Root Navigator (type: Stack — inferred from NativeStackScreenProps usage — verify against root navigator definition)
  ├── Logged-Out Shell
  │     ├── Splash (/src/view/com/auth/splash)
  │     ├── Login Stack
  │     │     ├── LoginForm (/login/login-form)
  │     │     ├── ChooseAccountForm (/login/choose-account-form)
  │     │     ├── ForgotPasswordForm (/login/forgot-password-form)
  │     │     ├── SetNewPasswordForm (/login/set-new-password-form)
  │     │     └── PasswordUpdatedForm (/login/password-updated-form)
  │     ├── Signup Stack
  │     │     ├── State (/signup/state)
  │     │     ├── BackNextButtons (/signup/back-next-buttons)
  │     │     ├── Policies (/signup/step-info/policies)
  │     │     ├── HandleSuggestions (/signup/step-handle/handle-suggestions)
  │     │     ├── CaptchaWeb (/signup/step-captcha/captcha-web)
  │     │     └── CaptchaWebView.web (/signup/step-captcha/captcha-web-view.web)
  │     ├── SignupQueued (/signup-queued)
  │     └── StarterPackLanding (/starter-pack/starter-pack-landing)
  │
  └── Main App (authenticated)
        ├── Deactivated (/deactivated)
        ├── Takendown (/takendown)
        ├── Onboarding Stack
        │     ├── Layout (/onboarding/layout)
        │     ├── State (/onboarding/state)
        │     ├── AvatarCircle (/onboarding/step-profile/avatar-circle)
        │     ├── AvatarCreatorCircle (/onboarding/step-profile/avatar-creator-circle)
        │     ├── AvatarCreatorItems (/onboarding/step-profile/avatar-creator-items)
        │     ├── PlaceholderCanvas (/onboarding/step-profile/placeholder-canvas)
        │     ├── InterestButton (/onboarding/step-interests/interest-button)
        │     ├── StarterPackCard (/onboarding/step-suggested-starterpacks/starter-pack-card)
        │     ├── ValuePropositionPager.shared (/onboarding/step-finished/value-proposition-pager.shared)
        │     ├── Index.web — StepFindContactsIntro (/onboarding/step-find-contacts-intro/index.web)
        │     └── Index.web — StepFindContacts (/onboarding/step-find-contacts/index.web)
        │
        ├── Tab Navigator (inferred — verify against root navigator definition)
        │     ├── Home Tab
        │     │     ├── Feed (/src/view/com/feeds/feed)
        │     │     ├── NoFeedsPinned (/home/no-feeds-pinned)
        │     │     ├── NoFollowingFeed (/feeds/no-following-feed)
        │     │     └── NoSavedFeedsOfAnyType (/feeds/no-saved-feeds-of-any-type)
        │     ├── Search Tab
        │     │     ├── Shell (/search/shell)
        │     │     ├── Explore (/search/explore)
        │     │     ├── SearchResults (/search/search-results)
        │     │     ├── Utils (/search/utils)
        │     │     ├── ExploreSuggestedAccounts (/search/modules/explore-suggested-accounts)
        │     │     ├── ExploreInterestsCard (/search/modules/explore-interests-card)
        │     │     ├── ExploreRecommendations (/search/modules/explore-recommendations)
        │     │     ├── ExploreTrendingVideos (/search/modules/explore-trending-videos)
        │     │     └── ExploreTrendingTopics (/search/modules/explore-trending-topics)
        │     ├── Notifications Tab
        │     │     ├── ActivityList (/notifications/activity-list)
        │     │     └── Log (/log)
        │     └── Messages Tab (MessagesTabNavigatorParams)
        │           ├── Inbox (/messages/inbox)
        │           ├── ChatList (/messages/chat-list)
        │           ├── Conversation (/messages/conversation)
        │           └── Settings (/messages/settings)
        │
        ├── CommonNavigatorParams screens (modal/push stack)
        │     ├── Profile Stack
        │     │     ├── ProfileHeaderStandard (/profile/header/profile-header-standard)
        │     │     ├── ProfileHeaderLabeler (/profile/header/profile-header-labeler)
        │     │     ├── Shell (/profile/header/shell)
        │     │     ├── Handle (/profile/header/handle)
        │     │     ├── DisplayName (/profile/header/display-name)
        │     │     ├── Metrics (/profile/header/metrics)
        │     │     ├── GrowableBanner (/profile/header/growable-banner)
        │     │     ├── GrowableAvatar (/profile/header/growable-avatar)
        │     │     ├── StatusBarShadow (/profile/header/status-bar-shadow)
        │     │     ├── StatusBarShadow.web (/profile/header/status-bar-shadow.web)
        │     │     ├── EditProfileDialog (/profile/header/edit-profile-dialog)
        │     │     ├── SuggestedFollows (/profile/header/suggested-follows)
        │     │     ├── ErrorState (/profile/error-state)
        │     │     ├── ProfileFollows (/profile/profile-follows)
        │     │     ├── ProfileFollowers (/profile/profile-followers)
        │     │     ├── ProfileSearch (/profile/profile-search)
        │     │     ├── KnownFollowers (/profile/known-followers)
        │     │     ├── ProfileLabelerLikedBy (/profile/profile-labeler-liked-by)
        │     │     ├── Labels (/profile/sections/labels)
        │     │     ├── Feed (/profile/sections/feed)
        │     │     └── Types (/profile/sections/types)
        │     ├── Post Stack
        │     │     ├── PostRepostedBy (/post/post-reposted-by)
        │     │     ├── PostLikedBy (/post/post-liked-by)
        │     │     ├── PostQuotes (/post/post-quotes)
        │     │     └── Const (/post-thread/const)
        │     ├── Hashtag (/hashtag)
        │     ├── Topic (/topic)
        │     ├── SavedFeeds (/saved-feeds)
        │     ├── ListHidden (/list/list-hidden)
        │     ├── FindContactsFlow (/find-contacts-flow)
        │     ├── ProfileList Stack
        │     │     ├── FeedSection (/profile-list/feed-section)
        │     │     └── AboutSection (/profile-list/about-section)
        │     ├── StarterPack (/starter-pack)
        │     ├── StarterPackLanding (/starter-pack/starter-pack-landing)
        │     ├── StarterPack Wizard
        │     │     ├── State (/starter-pack/wizard/state)
        │     │     ├── StepDetails (/starter-pack/wizard/step-details)
        │     │     ├── StepProfiles (/starter-pack/wizard/step-profiles)
        │     │     └── StepFeeds (/starter-pack/wizard/step-feeds)
        │     ├── VideoFeed
        │     │     ├── Index.web (/video-feed/index.web)
        │     │     └── Types (/video-feed/types)
        │     └── Settings Stack
        │           ├── Settings (/settings)
        │           ├── AccountSettings (/settings/account-settings)
        │           ├── AppPasswords (/settings/app-passwords)
        │           ├── AboutSettings (/settings/about-settings)
        │           ├── InterestsSettings (/settings/interests-settings)
        │           ├── AppearanceSettings (/settings/appearance-settings)
        │           ├── AccessibilitySettings (/settings/accessibility-settings)
        │           ├── LanguageSettings (/settings/language-settings)
        │           ├── ContentAndMediaSettings (/settings/content-and-media-settings)
        │           ├── AutomationLabelSettings (/settings/automation-label-settings)
        │           ├── FollowingFeedPreferences (/settings/following-feed-preferences)
        │           ├── ExternalMediaPreferences (/settings/external-media-preferences)
        │           ├── FindContactsSettings (/settings/find-contacts-settings)
        │           ├── ThreadPreferences (/settings/thread-preferences)
        │           ├── PrivacyAndSecuritySettings (/settings/privacy-and-security-settings)
        │           ├── ActivityPrivacySettings (/settings/activity-privacy-settings)
        │           ├── VerificationSettings (/moderation/verification-settings)
        │           ├── LegacyNotificationSettings (/settings/legacy-notification-settings)
        │           ├── AppIconSettings Stack
        │           │     ├── Index.web (/settings/app-icon-settings/index.web)
        │           │     ├── Types (/settings/app-icon-settings/types)
        │           │     ├── UseAppIconSets (/settings/app-icon-settings/use-app-icon-sets)
        │           │     ├── AppIconImage (/settings/app-icon-settings/app-icon-image)
        │           │     ├── SettingsListItem (/settings/app-icon-settings/settings-list-item)
        │           │     └── SettingsListItem.web (/settings/app-icon-settings/settings-list-item.web)
        │           └── Notification Settings Stack
        │                 ├── ReplyNotificationSettings (/settings/notification-settings/reply-notification-settings)
        │                 ├── MiscellaneousNotificationSettings (/settings/notification-settings/miscellaneous-notification-settings)
        │                 ├── MentionNotificationSettings (/settings/notification-settings/mention-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)
        │                 ├── RepostsOnRepostsNotificationSettings (/settings/notification-settings/reposts-on-reposts-notification-settings)
        │                 ├── NewFollowerNotificationSettings (/settings/notification-settings/new-follower-notification-settings)
        │                 └── ActivityNotificationSettings (/settings/notification-settings/activity-notification-settings)
        │
        └── E2E / Dev Screens
              └── SharedPreferencesTester (/e2e/shared-preferences-tester)

[Diagram: Building Block View — show the navigator hierarchy tree, screen components as leaves, and native module integration points (ExpoBackgroundNotificationHandler, ExpoBlueskyGifView, EmojiPicker, ExpoScrollForwarder, SharedPrefs)]

8.3 Shared Building Blocks

9. Runtime View

9.1 App Launch & Auth State Check

Participants: JS bundle, useSession, SplashScreen, root navigator, LoggedOutShell or main app navigator

Sequence:

1. Metro-bundled JS bundle loads; React Native runtime initializes.
2. Root component mounts; useSession reads persisted session tokens from the session store.
3. SplashScreen renders the Bluesky logo and background illustration while session state is being hydrated.
4. If no valid session exists → root navigator renders LoggedOutShell → SplashScreen with "Create account" and "Sign in" buttons.
5. If a valid session exists → root navigator renders the main app navigator → home feed loads.
6. If the session is a queued-signup session (isSignupQueued(accessJwt)) → SignupQueued screen renders with a 60-second polling loop.
7. If the account is deactivated → Deactivated screen renders.
8. If the account is taken down → Takendown screen renders.

Error path: If session hydration fails (e.g., corrupted token store), the app falls back to the logged-out shell.

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

9.2 Authenticated Feed Load

Participants: Feed screen, usePostFeedQuery, AT Protocol AppView, PostFeed, List (FlatList)

Sequence:

1. User navigates to the Home tab; Feed screen mounts with feed="following" descriptor.
2. usePostFeedQuery("following", ...) fires; TanStack Query checks cache — if stale or absent, sends GET /xrpc/app.bsky.feed.getTimeline to the AT Protocol AppView.
3. Response arrives; TanStack Query stores pages in cache; feedItems array is computed via useMemo.
4. PostFeed renders List (Animated.FlatList) with initialNumToRender items.
5. User scrolls; onEndReached fires when 2 viewport-heights remain; fetchNextPage() is called.
6. After 60 seconds, checkForNew() polls for new posts; if new posts exist, hasNew becomes true and LoadLatestBtn appears.
7. User taps LoadLatestBtn; truncateAndInvalidate clears cached pages beyond page 1 and triggers a background refetch; list scrolls to top.

Error path: Network failure → isError becomes true → PostFeedErrorMessage renders with detectKnownError() classification and a retry button.

[Diagram: Sequence — Authenticated Feed Load]

9.3 Notification Settings Update

Participants: ReplyNotificationSettings (representative of all 10 notification settings screens), useNotificationSettingsQuery, useNotificationSettingsUpdateMutation, AT Protocol PDS, PreferenceControls

Sequence:

1. User navigates to a notification settings screen (e.g., Reply Notification Settings).
2. useNotificationSettingsQuery() fires on mount; fetches AppBskyNotificationDefs.Preferences from the AT Protocol backend.
3. preferences.reply is passed to PreferenceControls; toggle group renders with current channel state.
4. User toggles "Push notifications" off; onChangeChannels(['list']) fires in PreferenceControls.
5. ax.metric('activityPreference:changeChannels', ...) fires for analytics.
6. useNotificationSettingsUpdateMutation().mutate({ reply: { ...preference, push: false } }) is called.
7. AT Protocol backend persists the updated preference; TanStack Query cache is updated.
8. UI reflects the new state (toggle is now off).

Error path: Mutation fails → error is silently swallowed (no error UI shown to user — see §14 Risks & Technical Debt).

[Diagram: Sequence — Notification Settings Update]

9.4 Background → Foreground Transition

Participants: AppState (React Native), PostFeed, usePostFeedQuery, Messages screens, useMessagesEventBus

Sequence:

1. App moves to background; AppState changes to 'background'.
2. Message polling interval requests are released by useFocusEffect cleanup functions.
3. App returns to foreground; AppState changes to 'active'.
4. PostFeed's AppState.addEventListener callback fires; checkForNew() is called for the active feed.
5. If new posts exist, hasNew becomes true; LoadLatestBtn appears with a dot indicator.
6. If the Messages screen is focused, messagesBus.requestPollInterval(MESSAGE_SCREEN_POLL_INTERVAL) is re-registered via useFocusEffect.
7. useRefreshOnFocus triggers a refetch of conversation lists when the Messages screen regains focus.

Error path: Network unavailable on foreground → checkForNew() fails silently (network errors are swallowed in the polling path).

[Diagram: Sequence — Background → Foreground Transition]

9.5 Signup Flow

Participants: SignupContext (reducer), StepInfo, StepHandle, StepCaptcha, useSubmitSignup, AT Protocol PDS, onboardingDispatch

Sequence:

1. User taps "Create account" on SplashScreen; signup navigator mounts; SignupContext initializes with createInitialState().
2. StepInfo renders; user enters email, password, date of birth, and optionally an invite code.
3. User taps "Next"; dispatch({ type: 'next' }) advances to StepHandle.
4. User enters a handle; useActorAutocompleteQuery provides suggestions via HandleSuggestions.
5. User taps "Next"; if serviceDescription.phoneVerificationRequired, dispatch({ type: 'next' }) advances to StepCaptcha.
6. CaptchaWebView (native) or CaptchaWebView.web (web) loads the hCaptcha challenge URL in a WebView/iframe.
7. User completes the CAPTCHA; the WebView detects the redirect to bsky.app and extracts the code parameter.
8. dispatch({ type: 'setPendingSubmit', value: { verificationCode: code } }) stores the code.
9. useSubmitSignup calls createAccount(...) on the AT Protocol PDS.
10. On success, onboardingDispatch({ type: 'start' }) initiates the onboarding flow.

Error path: createAccount fails with InvalidInviteCodeError → user is returned to StepInfo with an error on the invite code field. Other errors → user is returned to StepInfo with a generic error message.

⚠️ This workflow continues beyond the documented screens. Steps involving the full onboarding wizard (StepProfile, StepInterests, StepSuggestedStarterpacks, StepFindContacts, StepFinished) are partially documented but the complete onboarding navigator structure is not fully covered in this document. Verify the complete workflow with the development team before treating this as a comprehensive process description.

[Diagram: Sequence — Signup Flow]

10. Data Flow & State Management

10.1 Data Sources

10.2 State Management Approach

The application uses a layered state management strategy:

1. Server state — TanStack Query (React Query) is the exclusive mechanism for all AT Protocol API data. Screens do not hold server data in local useState; they read from the query cache.
2. Global UI state — React Context with useReducer is used for multi-step wizard flows (onboarding, signup, starter pack wizard) and for shell-level state (minimal shell mode, active starter pack, logged-out view controls).
3. Local component state — useState is used for ephemeral UI state (loading flags, form inputs, dialog open/close, pull-to-refresh indicators).
4. Persisted preferences — Custom hooks in #/state/preferences/ abstract the underlying storage mechanism (likely MMKV) for user preferences that survive app restarts.
5. Profile shadow system — useProfileShadow provides a local optimistic overlay on top of TanStack Query-cached profile data, enabling immediate UI updates for follow/block/like actions.

10.3 Navigation State as Data

Route params are used as the primary mechanism for passing data between screens in the navigator stack:

• ProfileFollows, ProfileFollowers, KnownFollowers, ProfileSearch — receive name (handle or DID) as a route param; resolve it to a full profile via useResolveDidQuery + useProfileQuery.
• PostRepostedBy, PostLikedBy, PostQuotes — receive name and rkey params; construct an AT URI via makeRecordUri.
• ActivityList — receives posts (URI-encoded list of post URIs) as a route param.
• Hashtag, Topic — receive topic (URI-encoded string) as a route param.
• MessagesConversation — receives conversation (convo ID) and optional accept flag.
• StarterPack — receives name, rkey, and optional new flag.

10.4 Persistence Layer

10.5 Data Transformation Pipeline

AT Protocol API response (JSON)
  → @atproto/api SDK (typed deserialization)
  → TanStack Query cache (in-memory, keyed by RQKEY)
  → Custom hook (usePostFeedQuery, useProfileQuery, etc.)
  → Screen component (reads data, isLoading, error)
  → Moderation layer (moderateProfile, moderatePost)
  → Sanitization (sanitizeDisplayName, sanitizeHandle, cleanError)
  → UI rendering (PostFeed, ProfileHeader, etc.)

For preferences:

AT Protocol preferences API
  → usePreferencesQuery (TanStack Query)
  → normalizeSort / normalizeView / channels derivation (useMemo)
  → Toggle.Group / Toggle.Item (controlled components)
  → useNotificationSettingsUpdateMutation / useSetFeedViewPreferencesMutation
  → AT Protocol preferences API (write)

10.6 Cross-Screen Data Sharing

11. Cross-Cutting Concerns

11.1 Safe-Area Handling

Safe-area handling is consistently delegated to the Layout component system. Layout.Screen, Layout.Header.Outer, and Layout.Content are shared primitives that internally handle SafeAreaView behavior. Individual screen components do not directly import SafeAreaView or call useSafeAreaInsets in most cases.

Exceptions where useSafeAreaInsets is called directly:

• ProfileHeaderShell (Shell.tsx) — for back button and status bar gradient positioning.
• GrowableBanner — for spinner positioning on iOS.
• StatusBarShadow — for gradient height.
• SignupQueued — for bottom padding of the fixed footer.
• Deactivated — for top and bottom padding of the content area.
• Takendown — for bottom padding of the fixed button panel.

This pattern is consistent and appropriate. No screens were observed to lack safe-area handling where it would be expected.

11.2 Keyboard Handling

Keyboard handling is inconsistent across the codebase:

• Multi-step wizard flows (signup, starter pack wizard) use KeyboardAwareScrollView from react-native-keyboard-controller for automatic keyboard avoidance.
• Settings screens do not use KeyboardAvoidingView because they contain no text inputs.
• Dialog components (Dialog.ScrollableInner, DisableEmail2FADialog) handle keyboard avoidance internally.
• StepDetails (starter pack wizard) has a multiline description field with minHeight: 150 but no KeyboardAvoidingView — the keyboard may obscure this field on smaller devices.
• LoginForm uses Keyboard.dismiss() imperatively in onPressSelectService and onPressNext.

There is no single, app-wide KeyboardAvoidingView strategy. Keyboard handling is addressed per-screen or per-dialog as needed.

11.3 Gesture Handling System

react-native-gesture-handler is used in the application, evidenced by:

• GestureActionView — uses Gesture and GestureDetector from react-native-gesture-handler for swipe-to-action in feed and chat list rows.
• BlockDrawerGesture — prevents drawer-open gestures within horizontal scroll areas (used in SearchHistory, SuggestedAccountsTabBar, ExploreTrendingVideos).
• DraggableScrollView — uses useDraggableScrollView for mouse-drag scrolling on web.

[Not documented — WHO: Mobile platform lead; WHAT: Is GestureHandlerRootView wrapping the root of the application? If not, gesture handling may fail on Android; WHERE: §11.3 Gesture Handling System and §14 Risks & Technical Debt]

11.4 Platform-Branching Consistency

The platform-branching strategy is consistent across the assessed screens. The primary mechanism is the IS_IOS, IS_ANDROID, IS_NATIVE, and IS_WEB constants from #/env, supplemented by the platform(), native(), ios(), android(), and web() style utilities from #/alf.

The .web.tsx file-extension split is used exclusively for screens that have no viable web implementation (throwing an error or returning null). This is a deliberate, documented pattern.

No screens were observed using Platform.OS === 'ios' or Platform.select() directly in screen-level code; these are abstracted behind the constants. This is a positive consistency finding.

11.5 Error Handling Strategy

The error handling strategy is layered but partially inconsistent:

• API errors — TanStack Query surfaces errors via isError and error fields. Screens branch on isError to show error UI (typically Admonition, ListMaybePlaceholder, or ErrorScreen).
• Error message sanitization — cleanError() is applied before displaying error strings to users across all observed screens.
• Mutation errors — Inconsistently handled. Some mutations (e.g., profile update, account deletion) show inline error UI. Others (e.g., notification settings update mutations) silently swallow errors with no user feedback.
• Network vs. application errors — isNetworkError(e) is used in several screens (login, password reset, forgot password) to show a connectivity-specific message.
• Error boundaries — No React Error Boundary usage is observed in the assessed screen documentation. The ErrorScreen component is used as a full-screen error state but is not a React Error Boundary.
• Logging — logger.error(...) is used consistently for non-user-facing error logging.

11.6 Authentication & Authorization

Authentication is enforced at the navigator level (not within individual screens). Screens assume a valid session exists and use useSession() to access currentAccount. The useRequireAuth() hook is used in specific action handlers (e.g., follow/unfollow in ProfileHeaderStandard) to redirect unauthenticated users to login before executing mutations.

Auth tokens are managed by the @atproto/api BskyAgent instance, which handles token refresh automatically. Screens do not directly read or write JWT tokens.

The session storage mechanism is abstracted behind useSession / useSessionApi. The underlying storage (SecureStore, Keychain, MMKV, or AsyncStorage) is not visible in the assessed screen documentation and represents a security concern (see §14 Risks & Technical Debt).

11.7 Loading & Empty States

Loading and empty states are handled consistently using shared components:

• ListMaybePlaceholder — used across list screens (Profile Followers, Known Followers, Activity List, Starter Pack, Find Contacts Settings) for loading, error, and empty states.
• Loader — a shared spinner component used inline in buttons (during mutations) and as a full-screen loading indicator.
• Admonition — used in settings screens to show error states when preference fetches fail.
• FeedFeedLoadingPlaceholder / PostFeedLoadingPlaceholder — skeleton placeholders for feed loading states.
• ChatListLoadingPlaceholder — skeleton for chat list loading.

The pattern of showing a Loader spinner when preference is undefined (loading) and an Admonition error when isError is true is applied consistently across all 10 notification settings screens.

11.8 Logging & Observability

[Not documented — WHO: Analytics/data engineering team; WHAT: What is the analytics provider behind useAnalytics() / ax.metric()? Is it PostHog, Mixpanel, a custom system, or another provider?; WHERE: §11.8 Logging & Observability]

11.9 Performance Patterns

11.10 Missing or Not Observed

• GestureHandlerRootView at app root — Not confirmed in the assessed documentation. If absent, react-native-gesture-handler gestures may fail on Android. This is a critical risk (see §14 Risks & Technical Debt).
• React Error Boundaries — No ErrorBoundary component usage is observed in the assessed screen documentation. Unhandled render errors (e.g., from the .web.tsx stubs that throw) would propagate to the nearest error boundary or crash the app.
• Centralized mutation error handling — Notification settings update mutations silently swallow errors. No global mutation error handler (e.g., TanStack Query's onError default) is observed.
• FlashList from @shopify/flash-list — Not observed in the assessed screens; FlatList is used throughout. For very long lists, FlashList would offer better performance.
• Offline queue / retry on reconnect — No NetInfo-based offline detection or queued-action mechanism is observed in any assessed screen. Network failures surface as error states requiring manual retry.

12. Architecture Decisions

AD-1: React Navigation with Native Stack

• Context: The application needs navigation across iOS, Android, and web with native-feeling transitions and type-safe route params.
• Decision: React Navigation with @react-navigation/native-stack is used as the navigation library. All screens are typed via NativeStackScreenProps<ParamList, RouteName>.
• Rationale: React Navigation's native stack provides platform-native transitions (UINavigationController on iOS, Fragment transactions on Android) without a JavaScript-driven animation layer. The typed ParamList pattern (CommonNavigatorParams, AllNavigatorParams, MessagesTabNavigatorParams) provides compile-time safety for route params.
• Consequences: The navigator hierarchy must be explicitly defined and maintained. Deep linking requires manual route configuration. Expo Router's file-based routing is not used, meaning route definitions are code-based rather than file-system-based.

AD-2: Expo Bare Workflow with EAS Build

• Context: The application requires custom native modules (background notification handler, GIF view, emoji picker, shared preferences) that are not available in Expo's managed workflow.
• Decision: Expo bare workflow is used, with EAS Build for CI/CD and native binary production.
• Rationale: The bare workflow provides full access to the native layer (CocoaPods, Gradle) while retaining Expo's configuration plugins (app.config.js) for managing Info.plist, AndroidManifest.xml, and native build settings. EAS Build provides reproducible cloud builds without requiring local Xcode/Android Studio setup for most developers.
• Consequences: Native module changes require a new binary release (cannot be OTA-updated). The ios/ and android/ directories are generated and managed by Expo's config plugin system. buildReactNativeFromSource: true is set for iOS (always) and Android (production only), increasing build times.

AD-3: TanStack Query for Server State

• Context: The application has extensive server state requirements: paginated feeds, profile data, notification preferences, conversation lists, and more — all requiring caching, background refetching, and optimistic updates.
• Decision: TanStack Query (React Query) is used as the exclusive server state management library. All AT Protocol API calls are wrapped in useQuery, useMutation, or useInfiniteQuery hooks in #/state/queries/.
• Rationale: TanStack Query provides cache deduplication, background refetching, infinite query pagination, and optimistic update patterns out of the box. Co-locating query hooks in #/state/queries/ creates a clear service layer boundary.
• Consequences: All screens depend on TanStack Query's cache for server data. Cache key management (RQKEY, FEED_RQKEY, etc.) must be maintained carefully to avoid stale data. The useQueryClient hook is used directly in some screens for manual cache manipulation (truncateAndInvalidate, resetQueries, setQueryData).

AD-4: AT Protocol as the Exclusive Backend API

• Context: Bluesky Social is built on the AT Protocol, an open standard for decentralized social networking.
• Decision: All data operations — reads and writes — flow through the @atproto/api SDK. No alternative REST APIs, GraphQL endpoints, or direct database connections are used.
• Rationale: AT Protocol compliance is a core product requirement. Using the SDK ensures lexicon type safety, correct XRPC encoding, and automatic session management (token refresh).
• Consequences: The application is tightly coupled to the AT Protocol lexicon. Any lexicon changes require SDK updates. The app.bsky.unspecced namespace (used in trending topics and recommendations) is explicitly unstable and subject to breaking changes.

AD-5: Platform-Branching via IS_IOS / IS_NATIVE / IS_WEB Constants

• Context: The application targets iOS, Android, and web from a single codebase, requiring controlled platform divergence.
• Decision: Platform differences are handled via IS_IOS, IS_ANDROID, IS_NATIVE, and IS_WEB boolean constants from #/env, supplemented by platform(), native(), ios(), android(), and web() style utilities from #/alf. File-extension splits (.web.tsx) are used only for screens with no viable web implementation.
• Rationale: Constants-based branching is more readable and tree-shakeable than Platform.OS string comparisons scattered throughout the codebase. The #/alf utilities enable platform-conditional styles without StyleSheet.create duplication.
• Consequences: The #/env module must be kept in sync with actual platform detection logic. The constants are build-time values, meaning they cannot be changed at runtime.

AD-6: 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. All user-facing strings are wrapped in msg, <Trans>, <Plural>, or t\...`macros. Thebabel-plugin-lingui-macro` transforms these at build time.
• Rationale: Lingui's macro-based approach provides compile-time string extraction without runtime overhead. The compileNamespace: 'ts' setting in lingui.config.ts generates TypeScript-typed message catalogs.
• Consequences: All new user-facing strings must use Lingui macros. The eslint-plugin-lingui and bsky-internal/avoid-unwrapped-text ESLint rules enforce this at the linting level. Translation catalogs must be maintained for 40+ locales.

AD-7: React Compiler (babel-plugin-react-compiler)

• Context: The application has many list-heavy screens where unnecessary re-renders degrade performance.
• Decision: babel-plugin-react-compiler (targeting React 19) is included in the Babel configuration. The eslint-plugin-react-compiler enforces compiler compatibility rules.
• Rationale: The React Compiler automatically memoizes components and hooks that follow the Rules of React, reducing the need for manual useMemo, useCallback, and React.memo annotations. The target: '19' setting enables React 19 compatibility mode.
• Consequences: Code must comply with the Rules of React for the compiler to apply optimizations. The ESLint plugin reports violations as warnings ('react-compiler/react-compiler': 'warn'), indicating the compiler is not yet fully enforced across the codebase.

AD-8: EAS Updates with Code-Signing for OTA Delivery

• Context: The application needs to deliver JavaScript bundle updates to production users without requiring App Store review cycles.
• Decision: EAS Updates is used for OTA bundle delivery. RSA code-signing (rsa-v1_5-sha256) is applied to all production and TestFlight updates. The checkAutomatically: 'NEVER' setting means updates are checked programmatically (via Updates.checkForUpdateAsync() in AboutSettings).
• Rationale: OTA updates enable rapid bug fixes and feature rollouts. Code-signing prevents malicious bundle injection. The appVersion runtime version policy ties OTA updates to the native binary version, preventing incompatible JS bundles from being applied.
• Consequences: OTA updates are only enabled in production and TestFlight builds (IS_TESTFLIGHT || IS_PRODUCTION). Development builds do not receive OTA updates. The About Settings screen exposes an OTA update UI for internal builds.

AD-9: Custom Native Modules via Expo Modules API

• Context: Several features require native capabilities not available in the standard Expo SDK.
• Decision: Custom Expo modules are implemented in modules/ using the Expo Modules API:
  • expo-background-notification-handler — background notification sound preferences
  • expo-bluesky-gif-view — native GIF rendering
  • expo-emoji-picker — native emoji picker
  • expo-scroll-forwarder — scroll position forwarding between native views
  • expo-bluesky-swiss-army (includes SharedPrefs) — cross-platform native key-value storage
• Rationale: The Expo Modules API provides a type-safe, auto-linking bridge between JavaScript and native code, reducing boilerplate compared to the legacy NativeModules API.
• Consequences: Custom native modules require native build steps and cannot be updated via OTA. Changes to native module APIs require coordinated JS and native releases.

AD-10: Sentry for Crash Reporting (Conditional)

• Context: Production crash visibility is required for reliability monitoring.
• Decision: Sentry is integrated via @sentry/react-native/expo but is conditionally enabled — only when SENTRY_AUTH_TOKEN is present in the build environment. The Metro config uses getSentryExpoConfig unconditionally, but the Expo plugin is only added when USE_SENTRY is true.
• Rationale: Conditional enablement allows local development without Sentry overhead. The SENTRY_AUTH_TOKEN environment variable gates production-only instrumentation.
• Consequences: Crash reporting is absent in development builds and in any production build where SENTRY_AUTH_TOKEN is not configured. The ax.logger.error calls observed in screen documentation may route to Sentry in production but to the internal logger in development.

AD-11: New Architecture Disabled (newArchEnabled: false)

• Context: React Native's New Architecture (Fabric renderer, Turbo Modules, JSI) is available but not yet universally compatible with all dependencies.
• Decision: newArchEnabled: false is set in app.config.js, keeping the application on the legacy bridge architecture.
• Rationale: Several dependencies (including some custom native modules and third-party packages) may not yet be compatible with the New Architecture. The legacy bridge provides stability.
• Consequences: The application does not benefit from JSI's synchronous native calls, Fabric's concurrent rendering, or Turbo Modules' lazy loading. Migration to the New Architecture will require auditing all native modules for compatibility. The metro.config.js explicitly disables unstable_enablePackageExports due to compatibility issues with Lingui and other packages.

13. Quality Attributes

14. Risks & Technical Debt

15. Glossary

15.1 Domain Terms

15.2 Architecture Terms