# bluesky-social/social-app architecture

> Architecture diagram of the GitHub repository bluesky-social/social-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bluesky-social/social-app
- Repository: https://github.com/bluesky-social/social-app

## Overview

Bluesky is a React Native social-network client for web, iOS, and Android, built on AT Protocol. The principal workflow is app launch, account/session setup, social discovery through feed and preference queries, then navigation to social content and notifications. The repository also includes a Go service that serves the web app and separate embed, link, and OG-card products. The graph emphasizes these product stages and a shared analytics layer. Some runtime wiring is unsampled, so uncertain links are omitted or dashed.

Main entry points: [`src/state/queries/useOnboardingSuggestedStarterPacksQuery.ts`](https://github.com/bluesky-social/social-app/blob/main/src/state/queries/useOnboardingSuggestedStarterPacksQuery.ts) (Feed discovery), [`src/App.tsx`](https://github.com/bluesky-social/social-app/blob/main/src/App.tsx) (App startup), [`src/lib/hooks/useNotificationHandler.ts`](https://github.com/bluesky-social/social-app/blob/main/src/lib/hooks/useNotificationHandler.ts) (Notification handling), [`src/Navigation.tsx`](https://github.com/bluesky-social/social-app/blob/main/src/Navigation.tsx) (Navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Social app"]
  node_app["App startup<br/>[App.tsx]"]
  node_navigation["Navigation<br/>[Navigation.tsx]"]
end

subgraph group_state["Identity and data"]
  node_session["Session management<br/>[index.tsx]"]
  node_preferences["Preferences<br/>[index.ts]"]
  node_language["Language settings<br/>[languages.tsx]"]
  node_discovery["Feed discovery"]
  node_feed_helpers["Feed request context<br/>[utils.ts]"]
  node_query_storage[("Query persistence")]
end

subgraph group_engagement["Social interactions"]
  node_notifications["Notification handling"]
  node_age["Age assurance<br/>[data.tsx]"]
  node_composer["Post composer<br/>[index.tsx]"]
end

subgraph group_web["Web services"]
  node_bskyweb["Web app server<br/>[server.go]"]
  node_embed["Post embeds<br/>[post.tsx]"]
  node_link_service["Link service<br/>[index.ts]"]
  node_ogcard["OG cards<br/>[index.ts]"]
end

subgraph group_observability["Analytics and logging"]
  node_analytics["Analytics<br/>[index.tsx]"]
  node_logger["Logging<br/>[index.tsx]"]
end

node_user(("User"))
node_atproto{{"AT Protocol services"}}

node_user -.->|"opens"| node_app
node_app -.->|"starts navigation"| node_navigation
node_navigation -.->|"uses session"| node_session
node_session -->|"creates or resumes sessions"| node_atproto
node_discovery -->|"reads preferences"| node_preferences
node_discovery -->|"reads content languages"| node_language
node_discovery -->|"builds request headers"| node_feed_helpers
node_discovery -->|"requests starter packs"| node_atproto
node_query_storage -.->|"persists query cache"| node_atproto
node_notifications -->|"routes notifications"| node_navigation
node_notifications -->|"reads session"| node_session
node_notifications -->|"uses analytics"| node_analytics
node_app -.->|"initializes analytics"| node_analytics
node_analytics -->|"creates loggers"| node_logger
node_bskyweb -->|"serves web app"| node_app
node_user -.->|"views shared posts"| node_embed
node_user -.->|"follows shared links"| node_link_service
node_user -.->|"previews shared content"| node_ogcard

click node_app "https://github.com/bluesky-social/social-app/blob/main/src/App.tsx"
click node_navigation "https://github.com/bluesky-social/social-app/blob/main/src/Navigation.tsx"
click node_session "https://github.com/bluesky-social/social-app/blob/main/src/state/session/index.tsx"
click node_preferences "https://github.com/bluesky-social/social-app/blob/main/src/state/queries/preferences/index.ts"
click node_language "https://github.com/bluesky-social/social-app/blob/main/src/state/preferences/languages.tsx"
click node_discovery "https://github.com/bluesky-social/social-app/blob/main/src/state/queries/useOnboardingSuggestedStarterPacksQuery.ts"
click node_feed_helpers "https://github.com/bluesky-social/social-app/blob/main/src/lib/api/feed/utils.ts"
click node_query_storage "https://github.com/bluesky-social/social-app/blob/main/src/lib/persisted-query-storage.ts"
click node_notifications "https://github.com/bluesky-social/social-app/blob/main/src/lib/hooks/useNotificationHandler.ts"
click node_age "https://github.com/bluesky-social/social-app/blob/main/src/ageAssurance/data.tsx"
click node_composer "https://github.com/bluesky-social/social-app/blob/main/src/components/Composer/index.tsx"
click node_analytics "https://github.com/bluesky-social/social-app/blob/main/src/analytics/index.tsx"
click node_logger "https://github.com/bluesky-social/social-app/blob/main/src/logger/index.tsx"
click node_bskyweb "https://github.com/bluesky-social/social-app/blob/main/bskyweb/cmd/bskyweb/server.go"
click node_embed "https://github.com/bluesky-social/social-app/blob/main/bskyembed/src/screens/post.tsx"
click node_link_service "https://github.com/bluesky-social/social-app/blob/main/bskylink/src/index.ts"
click node_ogcard "https://github.com/bluesky-social/social-app/blob/main/bskyogcard/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_navigation,node_user toneBlue
class node_session,node_preferences,node_language,node_discovery,node_feed_helpers,node_query_storage toneAmber
class node_notifications,node_age,node_composer toneMint
class node_bskyweb,node_embed,node_link_service,node_ogcard toneRose
class node_analytics,node_logger,node_atproto toneIndigo
```

## Components

### Social app

- [App startup](https://github.com/bluesky-social/social-app/blob/main/src/App.tsx): `src/App.tsx`
- [Navigation](https://github.com/bluesky-social/social-app/blob/main/src/Navigation.tsx): `src/Navigation.tsx`

### Identity and data

- [Session management](https://github.com/bluesky-social/social-app/blob/main/src/state/session/index.tsx): `src/state/session/index.tsx`
- [Preferences](https://github.com/bluesky-social/social-app/blob/main/src/state/queries/preferences/index.ts): `src/state/queries/preferences/index.ts`
- [Language settings](https://github.com/bluesky-social/social-app/blob/main/src/state/preferences/languages.tsx): `src/state/preferences/languages.tsx`
- [Feed discovery](https://github.com/bluesky-social/social-app/blob/main/src/state/queries/useOnboardingSuggestedStarterPacksQuery.ts): `src/state/queries/useOnboardingSuggestedStarterPacksQuery.ts`
- [Feed request context](https://github.com/bluesky-social/social-app/blob/main/src/lib/api/feed/utils.ts): `src/lib/api/feed/utils.ts`
- [Query persistence](https://github.com/bluesky-social/social-app/blob/main/src/lib/persisted-query-storage.ts): `src/lib/persisted-query-storage.ts`

### Social interactions

- [Notification handling](https://github.com/bluesky-social/social-app/blob/main/src/lib/hooks/useNotificationHandler.ts): `src/lib/hooks/useNotificationHandler.ts`
- [Age assurance](https://github.com/bluesky-social/social-app/blob/main/src/ageAssurance/data.tsx): `src/ageAssurance/data.tsx`
- [Post composer](https://github.com/bluesky-social/social-app/blob/main/src/components/Composer/index.tsx): `src/components/Composer/index.tsx`

### Web services

- [Web app server](https://github.com/bluesky-social/social-app/blob/main/bskyweb/cmd/bskyweb/server.go): `bskyweb/cmd/bskyweb/server.go`
- [Post embeds](https://github.com/bluesky-social/social-app/blob/main/bskyembed/src/screens/post.tsx): `bskyembed/src/screens/post.tsx`
- [Link service](https://github.com/bluesky-social/social-app/blob/main/bskylink/src/index.ts): `bskylink/src/index.ts`
- [OG cards](https://github.com/bluesky-social/social-app/blob/main/bskyogcard/src/index.ts): `bskyogcard/src/index.ts`

### Analytics and logging

- [Analytics](https://github.com/bluesky-social/social-app/blob/main/src/analytics/index.tsx): `src/analytics/index.tsx`
- [Logging](https://github.com/bluesky-social/social-app/blob/main/src/logger/index.tsx): `src/logger/index.tsx`

### Other components

- **User**
- **AT Protocol services**

## Connections

- User → App startup: opens
- App startup → Navigation: starts navigation
- Navigation → Session management: uses session
- Session management → AT Protocol services: creates or resumes sessions (evidence: `src/state/session/index.tsx`)
- Feed discovery → Preferences: reads preferences (evidence: `src/state/queries/useOnboardingSuggestedStarterPacksQuery.ts`)
- Feed discovery → Language settings: reads content languages (evidence: `src/state/queries/useOnboardingSuggestedStarterPacksQuery.ts`)
- Feed discovery → Feed request context: builds request headers (evidence: `src/state/queries/useOnboardingSuggestedStarterPacksQuery.ts`)
- Feed discovery → AT Protocol services: requests starter packs (evidence: `src/state/queries/useOnboardingSuggestedStarterPacksQuery.ts`)
- Query persistence → AT Protocol services: persists query cache
- Notification handling → Navigation: routes notifications (evidence: `src/lib/hooks/useNotificationHandler.ts`)
- Notification handling → Session management: reads session (evidence: `src/lib/hooks/useNotificationHandler.ts`)
- Notification handling → Analytics: uses analytics (evidence: `src/lib/hooks/useNotificationHandler.ts`)
- App startup → Analytics: initializes analytics
- Analytics → Logging: creates loggers (evidence: `src/analytics/index.tsx`)
- Web app server → App startup: serves web app (evidence: `README.md`)
- User → Post embeds: views shared posts
- User → Link service: follows shared links
- User → OG cards: previews shared content
