first commit

Made-with: Cursor

context/Frontend_overview.md

@@ -0,0 +1,267 @@
+# 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.