padreug/web-app
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
web-app/web-app-specification.md
padreug 13b3adf876 add app specification
2025-07-02 16:23:48 +02:00

9.2 KiB
Raw Blame History

Protocols

Finance

Layer 1: Bitcoin on-chain Layer 2: Bitcoin Lightning Layer 2+: LNBits

Communication

NOSTR

Resources

https://nostr.how https://github.com/nostr-protocol/nips

Notes on integration

NOSTR and Bitcoin lightning are closely integrated. Each NOSTR profile will have a lightning "zap" address that is likely to be <username>@<domain>.<ext>. We want users to be easily able to "zap" each other

resources

What are Zaps

Objective

The objective of this project is to make an app for a social network that serve people in a close physical community. This core tenets of this app are that it be made with FOSS so that it may easily be reproduced.

This app will be able to function on a LAN that is not connected to WAN.

We want this app to foster a strong social network that allows for easy exchange of value. On the server that hosts the application will be a NOSTR Relay which will be the database that stores any content.

Components

  • LNBits Server
  • LNBits User Web app
  • Front end app designed for enhanced UX/UI

The vast majority of the backend will be handled by the LNBits stack. LNBits includes both a server that facilitates the exchange of value compatible with the lightning network. Technically, this would be described as layer 2+ in the context of Bitcoin. While it is fully compatible with the lightning network, it can also have internal payments that occur mostly at the database level.

LNBits has a collection of extensions that we will leverage in order to super-charge the user experience. When we make a user for a person, we will be creating an lnbits user. A user has access to their lnbits settings through the lnbits front end that is run in tandem with the lnbits server.

We will also create a UI that provides a streamlined experience for less technical users who do not need the level of control that the lnbits quasar web app provides. For this, we will be using Vue3, shadcn-vue (implying tailwind v4), vite, etc. This UI will focus on displaying the content in a visually pleasing way that also provides the ability to interact through their nostr profile. E.g., they can send messages to friends, purchase items from the nostr marketplace, exchange money with friends, etc

LNBits Server + Extensions

  • NOSTR Relay
  • NOSTR Client
  • NOSTR Marketplace

Features

  • Newsfeed page with filters. E.g., Important Announcements, GenPop, Event notifications, etc
  • Communal calendar page
  • Communal Marketplace
  • Events Page (already present)

User Experience Details

Authentication & User Management

  • User registration creates both LNBits user and NOSTR key-pair via LNBits API
  • Keys stored securely, minimal technical exposure to users
  • Simplified onboarding for non-technical users

User Profiles

  • Displayed Info: Avatar, username, display name, bio
  • Zap Address: <username>@<hostname> format
  • Wallet Integration: Show LNBits wallet balance
  • Future Features: Badges and gamification elements

Content & Interactions

  • Primary Content: Moderator posts and automated system posts (e.g., event creation notifications)
  • User Actions: Reply and react to existing content (limited user-generated content initially)
  • Real-time Updates: WebSocket-based NOSTR client for live feed updates
  • Data Persistence: Local storage for offline capability and improved UX

Technical Architecture

  • PWA Deployment: Mobile-optimized progressive web app
  • Network: Functions on LAN without WAN dependency
  • API Integration: All transactions through LNBits API
  • User Roles: Admin/moderator/user permissions handled via LNBits

Development Phases

Phase 1 (Current Focus): Newsfeed and Events Phase 2 (Future): Marketplace integration
Phase 3 (Future): Location-aware features and maps

Technical Integration Specifications

Environment Variables

VITE_LNBITS_BASE_URL=http://localhost:5000  # LNBits server URL
VITE_NOSTR_RELAY_URL=ws://localhost:5000/nostrrelay/<relay-id>  # NOSTR relay WebSocket
VITE_HOSTNAME=localhost  # For zap addresses (username@hostname)

LNBits API Integration Points

User Management

  • Create User: POST /api/v1/user - Creates LNBits user with NOSTR key-pair
  • Get User: GET /api/v1/user/{user_id} - Retrieve user profile data
  • Update User: PUT /api/v1/user/{user_id} - Update profile (avatar, username, display name, bio)

Wallet Operations

  • Get Wallet Balance: GET /api/v1/wallet - Retrieve current wallet balance
  • Create Payment: POST /api/v1/payments - Handle zap transactions
  • Payment Status: GET /api/v1/payments/{payment_hash} - Check payment status

NOSTR Integration

  • NOSTR Client Extension: /extensions/nostrclient - Manages NOSTR connections and messaging
  • NOSTR Relay Extension: /extensions/nostrrelay - Local relay for community content
  • WebSocket Connection: Real-time event streaming via relay WebSocket

UI/UX Component Architecture

Main Navigation

  • Newsfeed (tabs: All, Important, Events, General)
  • Events (existing page, integrate with newsfeed notifications)
  • Profile (modal: user info, wallet balance, settings)

Newsfeed Features

  • Real-time WebSocket updates from NOSTR relay
  • Visual priority system for Important Announcements
  • Reply and reaction capabilities (zap, like, comment)
  • Local storage for offline content persistence

Zapping Interface

  • Quick zap buttons (preset amounts: 10, 50, 100 sats)
  • Custom amount modal for larger transactions
  • Visual feedback for successful zaps
  • Integration with LNBits payment API

Profile Management

  • Editable: avatar, username, display name, bio
  • Read-only: zap address (username@hostname), wallet balance
  • Future: badges and gamification elements

Data Flow

  1. User Registration: Vue app → LNBits API → NOSTR key-pair generation
  2. Content Publishing: Moderator/System → NOSTR relay → WebSocket → Vue app
  3. User Interactions: Vue app → LNBits API (payments) + NOSTR relay (social)
  4. Real-time Updates: NOSTR relay WebSocket → Vue app state management

NOSTR Event Types for Implementation

Based on NOSTR Improvement Proposals (NIPs), the following event types are relevant for our community app:

Core Event Types

User Profile (Kind 0 - NIP-01)

{
  "kind": 0,
  "content": "{\"name\":\"username\", \"about\":\"bio text\", \"picture\":\"avatar_url\"}"
}
  • Usage: User profile management
  • UI Components: Profile modal, user avatar/name display

Text Notes (Kind 1 - NIP-10)

{
  "kind": 1,
  "content": "Post content text",
  "tags": [
    ["p", "pubkey", "relay_url"],  // mentions
    ["e", "event_id", "relay_url", "marker"]  // replies/threads
  ]
}
  • Usage: Main newsfeed content, moderator announcements
  • UI Components: Post display, reply threads

Reactions (Kind 7 - NIP-25)

{
  "kind": 7,
  "content": "+",  // or "-", or emoji
  "tags": [
    ["e", "target_event_id", "relay_url", "target_pubkey"],
    ["p", "target_pubkey", "relay_url"],
    ["k", "target_event_kind"]
  ]
}
  • Usage: Like/dislike posts, emoji reactions
  • UI Components: Reaction buttons, reaction counts

Calendar Events (Kind 31922/31923 - NIP-52)

{
  "kind": 31922,  // date-based events
  "content": "Event description",
  "tags": [
    ["d", "unique_identifier"],
    ["title", "Event Title"],
    ["start", "YYYY-MM-DD"],
    ["end", "YYYY-MM-DD"],
    ["location", "Event location"],
    ["p", "participant_pubkey", "relay_url", "role"]
  ]
}
  • Usage: Community calendar, event announcements
  • UI Components: Event cards, calendar integration, automatic newsfeed posts

Lightning/Payment Events

Zap Requests (Kind 9734 - NIP-57)

{
  "kind": 9734,
  "content": "Zap message",
  "tags": [
    ["relays", "relay1", "relay2"],
    ["amount", "21000"],  // millisats
    ["p", "recipient_pubkey"],
    ["e", "target_event_id"]  // if zapping a post
  ]
}
  • Usage: Lightning zap payments
  • UI Components: Zap buttons, amount selection, payment confirmation

Zap Receipts (Kind 9735 - NIP-57)

{
  "kind": 9735,
  "content": "",
  "tags": [
    ["bolt11", "lightning_invoice"],
    ["description", "zap_request_json"],
    ["p", "recipient_pubkey"],
    ["e", "target_event_id"]
  ]
}
  • Usage: Payment confirmation display
  • UI Components: Zap success indicators, payment history

Content Types for Future Implementation

Long-form Content (Kind 30023 - NIP-23)

  • Usage: Community announcements, detailed posts
  • Tags: title, summary, image, published_at

Marketplace Events (NIP-15)

  • Usage: Community marketplace integration (Phase 2)

Implementation Notes

Event Filtering for Newsfeed Tabs

  • All: Subscribe to kinds [0, 1, 7, 31922, 31923, 9735]
  • Important: Filter by specific pubkeys (moderators) or tags
  • Events: Filter specifically for kinds [31922, 31923]
  • General: Filter for kind 1 excluding moderator pubkeys

WebSocket Subscription Filters

{
  "kinds": [1, 7, 31922, 31923, 9735],
  "since": <timestamp>,
  "limit": 50
}

Local Storage Schema

  • Events by kind and timestamp
  • User profiles by pubkey
  • Reaction counts by event_id
  • Zap totals by event_id and recipient