How primalhq/primal-web-app works
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: Router.tsx Router · PrimalNostr.ts Nostr IO · App.tsx App shell · Thread.tsx Content pages
Components 21
Runtime
Browser entry, app shell, and route selection
UI
Pages and reusable visual components
- Layout · Desktop and phone layout variants
src/components/Layout/Layout.tsx - Nav chrome · Menus, headers, sidebars, and page chrome
src/components/NavMenu/NavMenu.tsx - Feed pages · Home, feed, explore, bookmarks, and related content views
src/pages/Home.tsx - Profile pages · Profile, edit profile, and account-facing views
src/pages/Profile.tsx - Content pages · Thread, reads, longform, search, and notifications views
src/pages/Thread.tsx - Settings pages · Settings, moderation, wallet, network, and account options
src/pages/Settings/Settings.tsx - Premium · Membership, subscription, backup, and payment flows
src/pages/Premium/Premium.tsx
State
Contexts and stores coordinating app state
- Account ctx · Global account, auth, and onboarding state
src/contexts/AccountContext.tsx - Feature ctx · Route-scoped contexts for home, profile, thread, search, DM, explore, notifications, settings, and reads
src/contexts/HomeContext.tsx - Shared 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 · Feed selection, feed assembly, and mega feed aggregation
src/handleFeeds.ts - Note core · Note parsing, rendering, markdown, and thread composition
src/handleNotes.ts - People search · Profile lookup, search, and discovery helpers
src/lib/profile.ts - Messages · Direct messages, notifications, reactions, and social interactions
src/lib/messages.ts
Platform
Transport, persistence, workers, and external integrations
- Nostr IO · Relay, nostr API, keys, sockets, and NIP-46 integration
src/lib/PrimalNostr.ts - Workers · Relay, cache, and upload workers for off-thread processing
relayWorker.ts - Media upload · Uploads, images, streaming, and rich media transport
src/uploadSocket.tsx - Persistence · Local storage, releases, settings, wallet, membership, and premium infrastructure
src/lib/localStore.ts
Connections 24
- 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