Recurring deep-dive: mine patterns from established open-source Nostr apps #42

New issue

Open

opened 2026-05-05 18:07:11 +00:00 by padreug · 0 comments

padreug commented

2026-05-05 18:07:11 +00:00

Owner

Living reference at docs/nostr-patterns/ consolidates the Nostr patterns we've harvested from our own modules (RSVPs, reactions, profiles, bookmarks, subscriptions, services/DI). It only sees what we've already built — there are whole categories of pattern (relay selection, NIP-46 signing, NIP-89 client kind handling, blossom integration, gift-wrap routing, custom-emoji rendering, NIP-32 labels, marketplaces, threading/replies, slow-relay tolerance, "outbox model", inbox model, NIP-65 relay lists, etc.) that we either don't use yet or use naively.

This issue tracks periodic deep dives into well-known open-source Nostr apps to mine patterns we should adopt or refine. Each pass should pick a few apps, read for 1-2 hours each, and land concrete updates in docs/nostr-patterns/ (new topics or refinements of existing ones).

Apps worth studying

Coracle (https://github.com/coracle-social/coracle) — outbox model, relay selection, repository-of-relays.
Snort (https://github.com/v0l/snort) — feed pagination, NIP-49 password-protected nsec, reaction UX.
NoStrudel (https://github.com/hzrd149/nostrudel) — explicit "advanced" client; pattern density per LOC is high.
Damus (https://github.com/damus-io/damus) — Swift, but iOS-specific subscription lifecycle handling and DM patterns translate.
Habla (https://github.com/verbiricha/habla.news) — long-form (kind 30023) editor + cache, NIP-23 polish.
Highlighter (https://github.com/pablof7z/highlighter) — NDK-based, monetization patterns, gated content.
Flotilla (https://github.com/coracle-social/flotilla) — NIP-29 group chats, room-scoped subscriptions.
Zap.cooking (https://github.com/seth-for-breakfast/zap.cooking) — single-purpose niche app, useful for "minimal correct" reference.
NDK (https://github.com/nostr-dev-kit/ndk) — not an app, but its docs and helpers are the de facto best-practice library.

Concrete categories to look for each pass

Relay selection / outbox model — which relays to publish to, which to read from, NIP-65.
NIP-46 (Nostr Connect / bunker) signing flows.
NIP-49 encrypted nsec import.
NIP-89 / NIP-31 — client kind handling, "this client supports X" hints.
NIP-32 labels for moderation / categorization.
NIP-29 group chat semantics (rooms, members, admin events).
Blossom (BUD-01..04) media servers — how to upload, retrieve, fall back.
Custom emoji + NIP-30 rendering.
Threading / reply ordering (NIP-10, marker tags).
"Slow relay" handling — per-relay timeouts, partial-result UI.
Local relay / cache strategy (e.g., NDK cache adapters).
Cleanup / retention / NIP-40 expiration tags — actually evicting events client-side.
Subscription pooling and merging (one filter for many components).
Authentication patterns beyond raw nsec.

Process

Each deep dive PR:

Pick 2-3 apps + 2-3 categories from above.
Read code; take notes; write a short summary as a comment on this issue.
Update docs/nostr-patterns/ with the patterns worth adopting (or note explicitly why we're rejecting one).
Open separate implementation issues for any pattern we want to actually port (don't bundle implementation into the deep-dive PR — keep them separate so the docs land first).

Cadence: aim for one deep dive per quarter, ad-hoc whenever someone hits a Nostr-shaped problem and wants to know "how do the grown-ups do this".

Out of scope for this issue

Implementing any pattern we discover. That's a separate issue per pattern.
Engaging with the upstream projects (PRs, contributions). Welcome but not required.
Comprehensive coverage. Better to do five small focused passes than one giant one.

Living reference at `docs/nostr-patterns/` consolidates the Nostr patterns we've harvested from our own modules (RSVPs, reactions, profiles, bookmarks, subscriptions, services/DI). It only sees what we've already built — there are whole categories of pattern (relay selection, NIP-46 signing, NIP-89 client kind handling, blossom integration, gift-wrap routing, custom-emoji rendering, NIP-32 labels, marketplaces, threading/replies, slow-relay tolerance, "outbox model", inbox model, NIP-65 relay lists, etc.) that we either don't use yet or use naively. This issue tracks **periodic deep dives** into well-known open-source Nostr apps to mine patterns we should adopt or refine. Each pass should pick a few apps, read for 1-2 hours each, and land concrete updates in `docs/nostr-patterns/` (new topics or refinements of existing ones). ## Apps worth studying - **Coracle** (https://github.com/coracle-social/coracle) — outbox model, relay selection, repository-of-relays. - **Snort** (https://github.com/v0l/snort) — feed pagination, NIP-49 password-protected nsec, reaction UX. - **NoStrudel** (https://github.com/hzrd149/nostrudel) — explicit "advanced" client; pattern density per LOC is high. - **Damus** (https://github.com/damus-io/damus) — Swift, but iOS-specific subscription lifecycle handling and DM patterns translate. - **Habla** (https://github.com/verbiricha/habla.news) — long-form (kind 30023) editor + cache, NIP-23 polish. - **Highlighter** (https://github.com/pablof7z/highlighter) — NDK-based, monetization patterns, gated content. - **Flotilla** (https://github.com/coracle-social/flotilla) — NIP-29 group chats, room-scoped subscriptions. - **Zap.cooking** (https://github.com/seth-for-breakfast/zap.cooking) — single-purpose niche app, useful for "minimal correct" reference. - **NDK** (https://github.com/nostr-dev-kit/ndk) — not an app, but its docs and helpers are the de facto best-practice library. ## Concrete categories to look for each pass - Relay selection / outbox model — which relays to publish to, which to read from, NIP-65. - NIP-46 (Nostr Connect / bunker) signing flows. - NIP-49 encrypted nsec import. - NIP-89 / NIP-31 — client kind handling, "this client supports X" hints. - NIP-32 labels for moderation / categorization. - NIP-29 group chat semantics (rooms, members, admin events). - Blossom (BUD-01..04) media servers — how to upload, retrieve, fall back. - Custom emoji + NIP-30 rendering. - Threading / reply ordering (NIP-10, marker tags). - "Slow relay" handling — per-relay timeouts, partial-result UI. - Local relay / cache strategy (e.g., NDK cache adapters). - Cleanup / retention / NIP-40 expiration tags — actually evicting events client-side. - Subscription pooling and merging (one filter for many components). - Authentication patterns beyond raw nsec. ## Process Each deep dive PR: 1. Pick 2-3 apps + 2-3 categories from above. 2. Read code; take notes; write a short summary as a comment on this issue. 3. Update `docs/nostr-patterns/` with the patterns worth adopting (or note explicitly why we're rejecting one). 4. Open separate implementation issues for any pattern we want to actually port (don't bundle implementation into the deep-dive PR — keep them separate so the docs land first). Cadence: aim for one deep dive per quarter, ad-hoc whenever someone hits a Nostr-shaped problem and wants to know "how do the grown-ups do this". ## Out of scope for this issue - Implementing any pattern we discover. That's a separate issue per pattern. - Engaging with the upstream projects (PRs, contributions). Welcome but not required. - Comprehensive coverage. Better to do five small focused passes than one giant one.

padreug referenced this issue from a commit

2026-05-05 18:24:43 +00:00

docs(nostr): add reusable Nostr patterns reference

padreug added the

app:webapp

enhancement

labels

2026-05-17 21:23:57 +00:00