4.7 KiB
frontend_overview.md
1. Purpose
This document defines the complete frontend architecture, user experience, and interaction model for the Sats Faucet application.
The frontend must:
- Provide a simple, clean, and trustworthy interface.
- Integrate Nostr login (NIP-07 or external signer).
- Guide users through eligibility check and claim confirmation.
- Display transparent faucet statistics and funding information.
- Clearly communicate rules, cooldowns, and denial reasons.
The frontend must never expose secrets or LNbits keys.
2. Tech Stack Requirements
Recommended:
- Framework: React (Next.js preferred) or similar SPA framework
- Styling: TailwindCSS or clean minimal CSS system
- QR generation library for Lightning deposit QR
- Nostr integration via NIP-07 browser extension (window.nostr)
Frontend must be deployable as static site or server-rendered app.
3. Global App Structure
3.1 Pages
- Home Page (/)
- Claim Modal or Claim Section
- Transparency / Stats Section
- Deposit Section
- Optional: About / Rules page
Navigation should be minimal and focused.
4. Nostr Authentication
4.1 Connect Flow
- User clicks "Connect Nostr".
- Frontend requests pubkey via NIP-07.
- Pubkey stored in memory (not localStorage unless necessary).
- Show truncated pubkey (npub format preferred).
4.2 NIP-98 Signing
For protected API calls:
- Build request payload (method + URL + timestamp + nonce).
- Request signature via NIP-07.
- Attach NIP-98 header to backend request.
Frontend must:
- Generate secure nonce.
- Handle signature errors gracefully.
5. Home Page Layout
5.1 Hero Section
- Title: Sats Faucet
- Short description of rules
- Claim button
5.2 Live Stats Section
Display:
- Current pool balance
- Total sats paid
- Total claims
- Claims in last 24h
- Daily budget progress bar
Stats pulled from GET /stats.
Must auto-refresh every 30–60 seconds.
6. Claim Flow UI
6.1 Step 1: Connect
If not connected:
- Disable claim button.
- Prompt user to connect Nostr.
6.2 Step 2: Enter Lightning Address
Input field:
- Validate basic format (user@domain).
- Do not over-validate client-side.
6.3 Step 3: Quote
On "Check Eligibility":
- Send POST /claim/quote with NIP-98.
Possible responses:
Eligible:
- Show payout amount.
- Show Confirm button.
Not eligible:
- Show clear message from backend.
- If cooldown, show next eligible date.
- If account too new, show required age.
6.4 Step 4: Confirm
On confirm:
-
Call POST /claim/confirm.
-
Show loading state.
-
On success:
- Show payout amount.
- Show next eligible time.
-
On failure:
- Show clear error.
Must prevent double-click submission.
7. Deposit Section
Display:
- Lightning Address (copyable).
- QR code of LNURL.
- Optional: "Create invoice" button.
Copy buttons required for:
- Lightning address
- LNURL
Deposit section must feel transparent and trustworthy.
8. Transparency Section
Display:
- Recent payouts (anonymized pubkey prefix).
- Payout amount.
- Timestamp.
Optional:
- Distribution breakdown (small/medium/large payouts).
9. Error Handling UX
Frontend must handle:
- Network failures.
- Signature rejection.
- Expired quote.
- Payout failure.
All errors must be displayed in a clean alert component.
Do not expose internal error stack traces.
10. State Management
Minimal state required:
- pubkey
- lightning_address
- eligibility result
- quote_id
- payout_sats
- next_eligible_at
Use React state or lightweight state manager.
No need for complex global store.
11. Security Requirements
Frontend must:
- Never store secrets.
- Never expose LNbits keys.
- Never trust client-side eligibility logic.
- Rely entirely on backend for final validation.
If Turnstile or CAPTCHA enabled:
- Include widget only when backend indicates required.
12. Design Principles
- Minimal, modern UI.
- Clear visual feedback.
- No clutter.
- Show transparency clearly.
- Make it feel fair and legitimate.
Recommended style:
- Dark mode default.
- Bitcoin-inspired accent color.
- Clean typography.
13. Performance Requirements
- Fast initial load.
- Avoid blocking Nostr relay calls on frontend.
- All relay interaction handled by backend.
14. Accessibility
- Buttons must have disabled states.
- Inputs labeled clearly.
- QR accessible with copy option.
15. Completion Criteria
Frontend is complete when:
- User can connect via NIP-07.
- Eligibility check works and displays correct messages.
- Confirm claim triggers payout.
- Deposit Lightning address and QR visible.
- Live stats update correctly.
- Cooldown and denial reasons clearly displayed.
- No sensitive data exposed in frontend code.