268 lines
4.7 KiB
Markdown
268 lines
4.7 KiB
Markdown
# 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
|
||
|
||
1. Home Page (/)
|
||
2. Claim Modal or Claim Section
|
||
3. Transparency / Stats Section
|
||
4. Deposit Section
|
||
5. 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.
|