NostrCounter/architecture.md

Architecture.md

Overview

"Nostr Count" is a fully client-side web app that allows users to track and share life counters using the Nostr protocol. Events are stored as kind: 30078 and fetched using Nostr relays. It includes two counter types:

• Days since a past date (e.g., quit smoking)
• Days until a future event (e.g., vacation)

The app does not require a backend, but can optionally use one for caching, trending counters, and zap analytics.

---

Tech Stack

Frontend

• React 18 + TypeScript – UI and component structure
• Tailwind CSS – Styling
• NDK (Nostr Dev Kit) – Nostr integration
• Day.js – Date calculation and formatting
• Vite – Build tool (or Next.js if SSR required)

Nostr Relays

• Default relays (configurable via .env or app settings):

  • wss://relay.azzamo.net
  • wss://relay.damus.io
  • wss://nostr.oxtr.dev

• Events published and read via NDK

Optional Backend (Future Option)

• Node.js/Express or FastAPI

• Purpose:

  • Cache counters per pubkey
  • Track zap totals per counter
  • Optional user API for bookmarks/favorites

---

Event Structure (kind: 30078)

{
  "kind": 30078,
  "content": "", // Not used for now
  "tags": [
    ["d", "quit-smoking"],
    ["type", "since"],
    ["title", "Quit smoking"],
    ["date", "2023-09-01"],
    ["visibility", "public"]
  ],
  "created_at": 1690000000,
  "pubkey": "<user-pubkey>"
}

Required Tags

• d: unique ID or slug (e.g. kebab-case of title)
• type: since or until
• title: human-readable name of the counter
• date: ISO date string (YYYY-MM-DD)
• visibility: public or private

---

App Pages / Routes

/

• Landing page
• Featured public counters
• CTA: "Create a Counter"

/dashboard

• Login required
• List of user’s counters (from pubkey)
• Create new counter button

/counter/:slug

• View a public counter
• Show days since/until, zap button, author

---

Components

CounterCard

• Displays a single counter (days diff + title)
• Button to share or open

CounterFormModal

• Modal for creating/editing a counter
• Inputs: title, date, type, visibility

ZapButton

• Renders LN zap request if author has Lightning address in NIP-05/metadata

NDKProvider

• Provides global access to NDK instance
• Handles login, signer, and event fetch/publish

---

Future Features (Not MVP)

• Comments (reply to counter event)
• Counter streaks
• Private reminders
• iCal export or notification system