# primalhq/primal-web-app architecture

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

- Interactive diagram: https://gitdiagram.com/primalhq/primal-web-app
- Repository: https://github.com/primalhq/primal-web-app

## Overview

1. This is a client-side SPA for Primal, a Nostr-based social/content app. The stack is SolidJS with TypeScript and Sass, built and served through Vite (`index.html`, `src/index.tsx`, `vite.config.ts`).

2. The top-level app flow is simple: `src/index.tsx` boots the app, `App.tsx` composes global providers, and `Router.tsx` selects the page-level views. Most architecture decisions are route-driven rather than server-driven, because the repo is primarily a frontend.

3. The repository is organized around feature pages in `src/pages` and reusable UI in `src/components`. Pages represent major product areas such as Home/Feed, Profile, Thread, Search, Notifications, Direct Messages, Reads editor, Explore, Settings, Premium, and onboarding/account creation. Components are highly granular and shared across those pages.

4. The state boundary is split between route/local contexts and shared stores. `src/contexts` contains feature-scoped providers like Account, Home, Profile, Thread, Notifications, Reads, Search, Settings, DM, and Explore. `src/stores` contains more persistent/shared data models such as account, note, profile, trending, and mega feed state.

5. Data access and protocol logic are isolated in `src/lib`, `src/services`, and a few root helpers. This layer handles Nostr/relay interactions, caching, feeds, notes, search, profiles, notifications, zaps, wallets, premium/membership, streaming, and local persistence. It is the boundary between the UI and external services.

6. External integration is a major architectural concern. The app talks to Nostr relays, a Primal cache websocket, and an upload websocket; these are configurable via `PRIMAL_CACHE_URL` and `PRIMAL_UPLOAD_URL` per the README. It also appears to integrate with Lightning/NWC, Blossom uploads, and premium/payment flows.

7. The app has a strong “feed and content” core. Feed handling is split between feed utilities (`handleFeeds.ts`, `src/lib/feed.ts`, `src/lib/availableFeeds.ts`, `src/megaFeeds.ts`) and note/content utilities (`handleNotes.ts`, `src/lib/notes.tsx`, `src/lib/markdown.ts`, markdown plugins). The feed pipeline likely feeds Home/Explore/Profile pages, while note parsing/rendering feeds thread, reply, highlight, repost, and media views.

8. Media and rich content are first-class subsystems. There are dedicated components and libs for images, uploads, video/live streams, QR codes, emoji/polls, markdown editing, and highlight/annotation flows. `imageCacheWorker.js`, `relayWorker.ts`, and `uploadSocket.tsx` indicate background work for caching, relay processing, and upload transport.

9. The UI is layout-aware and device-specific. `src/components/Layout` and the Home/Nav sidebars have desktop and phone variants, suggesting responsive branching at the component boundary rather than separate apps. Many feature components also have mobile-specific skeletons and alternate render paths.

10. Modals, drawers, and overlays are a major interaction pattern. Authentication/onboarding, account/pin creation, confirmation dialogs, search, feed marketplace, premium dialogs, zaps, QR code modals, reporting, and settings all live as modal-heavy flows. This implies the app uses transient UI state heavily, coordinated through contexts and shared stores.

11. The product has a significant premium/membership subsystem. `src/pages/Premium` and related components support legends, subscriptions, featured content, backups, renewals, promo codes, and Stripe-like payment flows. This is separate from core social browsing and appears to gate or enhance parts of the app.

12. Persistence and client infrastructure are handled on the frontend. There are helpers for local storage/cache, releases/update checks, logging, scrolling, text areas, and developer tooling. The presence of `public/public/*` fonts/assets and custom workers suggests the repo is responsible for most runtime behavior in the browser, with little or no application backend in this codebase.

Main entry points: [`src/Router.tsx`](https://github.com/primalhq/primal-web-app/blob/main/src/Router.tsx) (Router), [`src/lib/PrimalNostr.ts`](https://github.com/primalhq/primal-web-app/blob/main/src/lib/PrimalNostr.ts) (Nostr IO), [`src/App.tsx`](https://github.com/primalhq/primal-web-app/blob/main/src/App.tsx) (App shell), [`src/pages/Thread.tsx`](https://github.com/primalhq/primal-web-app/blob/main/src/pages/Thread.tsx) (Content pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_index["Entry<br/>bootstrap<br/>[index.tsx]"]
  node_app["App shell<br/>composition<br/>[App.tsx]"]
  node_router["Router<br/>navigation<br/>[Router.tsx]"]
end

subgraph group_ui["UI"]
  node_layout["Layout<br/>responsive shell<br/>[Layout.tsx]"]
  node_nav["Nav chrome<br/>navigation UI<br/>[NavMenu.tsx]"]
  node_feed_pages["Feed pages<br/>page cluster<br/>[Home.tsx]"]
  node_profile_pages["Profile pages<br/>page cluster<br/>[Profile.tsx]"]
  node_content_pages["Content pages<br/>page cluster<br/>[Thread.tsx]"]
  node_settings_pages["Settings pages<br/>page cluster<br/>[Settings.tsx]"]
  node_premium_pages["Premium<br/>membership UI<br/>[Premium.tsx]"]
end

subgraph group_state["State"]
  node_account_ctx["Account ctx<br/>context<br/>[AccountContext.tsx]"]
  node_feature_ctx["Feature ctx<br/>contexts<br/>[HomeContext.tsx]"]
  node_shared_stores["Shared stores<br/>[accountStore.ts]"]
end

subgraph group_domain["Domain"]
  node_feed_core["Feed core<br/>feed pipeline<br/>[handleFeeds.ts]"]
  node_note_core["Note core<br/>content pipeline<br/>[handleNotes.ts]"]
  node_profile_search["People search<br/>profile/search domain<br/>[profile.ts]"]
  node_messages_social["Messages<br/>social domain<br/>[messages.ts]"]
end

subgraph group_platform["Platform"]
  node_nostr_io["Nostr IO<br/>protocol layer<br/>[PrimalNostr.ts]"]
  node_cache_workers["Workers<br/>background processing<br/>[relayWorker.ts]"]
  node_media_upload["Media upload<br/>media/integration<br/>[uploadSocket.tsx]"]
  node_persistence_premium["Persistence<br/>local/premium infra<br/>[localStore.ts]"]
end

node_index -->|"boot"| node_app
node_app -->|"routes"| node_router
node_app -->|"providers"| node_account_ctx
node_app -->|"providers"| node_feature_ctx
node_router -->|"shell"| node_layout
node_layout -->|"chrome"| node_nav
node_router -->|"feed routes"| node_feed_pages
node_router -->|"profile routes"| node_profile_pages
node_router -->|"content routes"| node_content_pages
node_router -->|"settings routes"| node_settings_pages
node_router -->|"premium routes"| node_premium_pages
node_feed_pages -->|"feeds"| node_feed_core
node_content_pages -->|"notes"| node_note_core
node_profile_pages -->|"profiles"| node_profile_search
node_content_pages -->|"social"| node_messages_social
node_feature_ctx -->|"state"| node_shared_stores
node_feed_core -->|"relay data"| node_nostr_io
node_note_core -->|"events"| node_nostr_io
node_profile_search -->|"queries"| node_nostr_io
node_messages_social -->|"events"| node_nostr_io
node_nostr_io -->|"off-thread"| node_cache_workers
node_nostr_io -->|"uploads"| node_media_upload
node_media_upload -->|"settings"| node_persistence_premium
node_persistence_premium -->|"storage"| node_shared_stores

click node_index "https://github.com/primalhq/primal-web-app/blob/main/src/index.tsx"
click node_app "https://github.com/primalhq/primal-web-app/blob/main/src/App.tsx"
click node_router "https://github.com/primalhq/primal-web-app/blob/main/src/Router.tsx"
click node_layout "https://github.com/primalhq/primal-web-app/blob/main/src/components/Layout/Layout.tsx"
click node_nav "https://github.com/primalhq/primal-web-app/blob/main/src/components/NavMenu/NavMenu.tsx"
click node_feed_pages "https://github.com/primalhq/primal-web-app/blob/main/src/pages/Home.tsx"
click node_profile_pages "https://github.com/primalhq/primal-web-app/blob/main/src/pages/Profile.tsx"
click node_content_pages "https://github.com/primalhq/primal-web-app/blob/main/src/pages/Thread.tsx"
click node_settings_pages "https://github.com/primalhq/primal-web-app/blob/main/src/pages/Settings/Settings.tsx"
click node_premium_pages "https://github.com/primalhq/primal-web-app/blob/main/src/pages/Premium/Premium.tsx"
click node_account_ctx "https://github.com/primalhq/primal-web-app/blob/main/src/contexts/AccountContext.tsx"
click node_feature_ctx "https://github.com/primalhq/primal-web-app/blob/main/src/contexts/HomeContext.tsx"
click node_shared_stores "https://github.com/primalhq/primal-web-app/blob/main/src/stores/accountStore.ts"
click node_feed_core "https://github.com/primalhq/primal-web-app/blob/main/src/handleFeeds.ts"
click node_note_core "https://github.com/primalhq/primal-web-app/blob/main/src/handleNotes.ts"
click node_profile_search "https://github.com/primalhq/primal-web-app/blob/main/src/lib/profile.ts"
click node_messages_social "https://github.com/primalhq/primal-web-app/blob/main/src/lib/messages.ts"
click node_nostr_io "https://github.com/primalhq/primal-web-app/blob/main/src/lib/PrimalNostr.ts"
click node_cache_workers "https://github.com/primalhq/primal-web-app/blob/main/relayWorker.ts"
click node_media_upload "https://github.com/primalhq/primal-web-app/blob/main/src/uploadSocket.tsx"
click node_persistence_premium "https://github.com/primalhq/primal-web-app/blob/main/src/lib/localStore.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_index,node_app,node_router toneBlue
class node_layout,node_nav,node_feed_pages,node_profile_pages,node_content_pages,node_settings_pages,node_premium_pages toneAmber
class node_account_ctx,node_feature_ctx,node_shared_stores toneMint
class node_feed_core,node_note_core,node_profile_search,node_messages_social toneRose
class node_nostr_io,node_cache_workers,node_media_upload,node_persistence_premium toneIndigo
```

## Components

### Runtime

Browser entry, app shell, and route selection

- [Entry](https://github.com/primalhq/primal-web-app/blob/main/src/index.tsx): bootstrap · Vite entry that mounts the SPA · `src/index.tsx`
- [App shell](https://github.com/primalhq/primal-web-app/blob/main/src/App.tsx): composition · Composes global providers and top-level layout · `src/App.tsx`
- [Router](https://github.com/primalhq/primal-web-app/blob/main/src/Router.tsx): navigation · Selects route-level views and page flows · `src/Router.tsx`

### UI

Pages and reusable visual components

- [Layout](https://github.com/primalhq/primal-web-app/blob/main/src/components/Layout/Layout.tsx): responsive shell · Desktop and phone layout variants · `src/components/Layout/Layout.tsx`
- [Nav chrome](https://github.com/primalhq/primal-web-app/blob/main/src/components/NavMenu/NavMenu.tsx): navigation UI · Menus, headers, sidebars, and page chrome · `src/components/NavMenu/NavMenu.tsx`
- [Feed pages](https://github.com/primalhq/primal-web-app/blob/main/src/pages/Home.tsx): page cluster · Home, feed, explore, bookmarks, and related content views · `src/pages/Home.tsx`
- [Profile pages](https://github.com/primalhq/primal-web-app/blob/main/src/pages/Profile.tsx): page cluster · Profile, edit profile, and account-facing views · `src/pages/Profile.tsx`
- [Content pages](https://github.com/primalhq/primal-web-app/blob/main/src/pages/Thread.tsx): page cluster · Thread, reads, longform, search, and notifications views · `src/pages/Thread.tsx`
- [Settings pages](https://github.com/primalhq/primal-web-app/blob/main/src/pages/Settings/Settings.tsx): page cluster · Settings, moderation, wallet, network, and account options · `src/pages/Settings/Settings.tsx`
- [Premium](https://github.com/primalhq/primal-web-app/blob/main/src/pages/Premium/Premium.tsx): membership UI · Membership, subscription, backup, and payment flows · `src/pages/Premium/Premium.tsx`

### State

Contexts and stores coordinating app state

- [Account ctx](https://github.com/primalhq/primal-web-app/blob/main/src/contexts/AccountContext.tsx): context · Global account, auth, and onboarding state · `src/contexts/AccountContext.tsx`
- [Feature ctx](https://github.com/primalhq/primal-web-app/blob/main/src/contexts/HomeContext.tsx): contexts · Route-scoped contexts for home, profile, thread, search, DM, explore, notifications, settings, and reads · `src/contexts/HomeContext.tsx`
- [Shared stores](https://github.com/primalhq/primal-web-app/blob/main/src/stores/accountStore.ts): stores · Persistent app stores for account, notes, profiles, trending, and mega feeds · `src/stores/accountStore.ts`

### Domain

Feed, note, profile, search, and messaging logic

- [Feed core](https://github.com/primalhq/primal-web-app/blob/main/src/handleFeeds.ts): feed pipeline · Feed selection, feed assembly, and mega feed aggregation · `src/handleFeeds.ts`
- [Note core](https://github.com/primalhq/primal-web-app/blob/main/src/handleNotes.ts): content pipeline · Note parsing, rendering, markdown, and thread composition · `src/handleNotes.ts`
- [People search](https://github.com/primalhq/primal-web-app/blob/main/src/lib/profile.ts): profile/search domain · Profile lookup, search, and discovery helpers · `src/lib/profile.ts`
- [Messages](https://github.com/primalhq/primal-web-app/blob/main/src/lib/messages.ts): social domain · Direct messages, notifications, reactions, and social interactions · `src/lib/messages.ts`

### Platform

Transport, persistence, workers, and external integrations

- [Nostr IO](https://github.com/primalhq/primal-web-app/blob/main/src/lib/PrimalNostr.ts): protocol layer · Relay, nostr API, keys, sockets, and NIP-46 integration · `src/lib/PrimalNostr.ts`
- [Workers](https://github.com/primalhq/primal-web-app/blob/main/relayWorker.ts): background processing · Relay, cache, and upload workers for off-thread processing · `relayWorker.ts`
- [Media upload](https://github.com/primalhq/primal-web-app/blob/main/src/uploadSocket.tsx): media/integration · Uploads, images, streaming, and rich media transport · `src/uploadSocket.tsx`
- [Persistence](https://github.com/primalhq/primal-web-app/blob/main/src/lib/localStore.ts): local/premium infra · Local storage, releases, settings, wallet, membership, and premium infrastructure · `src/lib/localStore.ts`

## Connections

- Entry → App shell: boot · Mount the application shell
- App shell → Router: routes · Delegate page selection to the router
- App shell → Account ctx: providers · Install global account and app providers
- App shell → Feature ctx: providers · Provide route-scoped feature contexts
- Router → Layout: shell · Render the responsive app shell around pages
- Layout → Nav chrome: chrome · Compose navigation and page chrome
- Router → Feed pages: feed routes · Route into home, feed, and explore views
- Router → Profile pages: profile routes · Route into profile and edit flows
- Router → Content pages: content routes · Route into thread, reads, search, and notifications
- Router → Settings pages: settings routes · Route into settings and account configuration
- Router → Premium: premium routes · Route into membership and payment flows
- Feed pages → Feed core: feeds · Consume feed assembly and selection logic
- Content pages → Note core: notes · Render threads, markdown, and note content
- Profile pages → People search: profiles · Load profile and discovery data
- Content pages → Messages: social · Use notifications and messaging-related domain logic
- Feature ctx → Shared stores: state · Bridge route state to shared persistent stores
- Feed core → Nostr IO: relay data · Fetch and assemble feeds from Nostr sources
- Note core → Nostr IO: events · Parse and publish note-related events
- People search → Nostr IO: queries · Resolve profiles and search over protocol data
- Messages → Nostr IO: events · Sync notifications, messages, and reactions via relays
- Nostr IO → Workers: off-thread · Use workers for relay/cache processing
- Nostr IO → Media upload: uploads · Connect to upload and media transport services
- Media upload → Persistence: settings · Persist upload, wallet, and premium-related client state
- Persistence → Shared stores: storage · Back shared stores with local persistence and settings
