# 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.