# Documentation technique – zapwall4science (Dec 2025)

## 1) Cartographie services/hooks/types (responsabilités, dépendances)

- **Services Nostr**
  - `lib/nostr.ts` : pool SimplePool, publish générique, clés locales; queries article.
  - `lib/nostrEventParsing.ts` : parsing events → Article/Series/Review (tags kind_type, series, media, banner).
  - `lib/nostrTags.ts` : construction des tags article/série/avis (site, type science-fiction/research, kind_type, media/bannière).
  - `lib/seriesQueries.ts`, `lib/articleQueries.ts`, `lib/reviews.ts` : fetch séries, articles par série, critiques.
  - `lib/articlePublisher.ts`, `lib/articleMutations.ts` : publication article/preview/presentation, update/delete, kind_type, séries, médias, bannière.
  - `lib/seriesAggregation.ts`, `lib/reviewAggregation.ts`, `lib/zapAggregation.ts` : agrégats sponsoring/achats/remerciements.
  - `lib/zapVerification.ts` : vérification zap receipts (verifyEvent).
  - `lib/nostrconnect.ts` : Nostr Connect (handler, sécurité).
  - `lib/nostrRemoteSigner.ts` : signature distante (pas de fallback silencieux).
  - `lib/nip95.ts` : upload médias NIP-95 (images ≤5Mo, vidéos ≤45Mo, types restreints).
- **Paiement / Lightning**
  - `lib/alby.ts` : WebLN (enable, makeInvoice, sendPayment).
  - `lib/payment.ts`, `lib/paymentPolling.ts` : statut paiements, polling.
  - `lib/articleInvoice.ts` : facture article (zapAmount, expiry), tags preview.
- **Stockage**
  - `lib/storage/cryptoHelpers.ts` : AES-GCM, dérivation/import clé, conversions b64.
  - `lib/storage/indexedDB.ts` : set/get/delete/clearExpired chiffré, TTL.
  - `lib/articleStorage.ts` : clé maître locale (base64), secret par article, persistance contenu privé + facture.
- **Hooks**
  - `hooks/useArticles.ts`, `hooks/useUserArticles.ts` : subscriptions articles, filtres catégorie, unsubscribe direct (pas de .then).
  - `hooks/useArticleEditing.ts` : édition/suppression article.
  - Autres : `useNotificationCenter`, `useNostrConnect`, etc.
- **Types**
  - `types/nostr.ts` : Article, Series, Review, MediaRef, KindType, catégories; exactOptionalPropertyTypes respecté.
  - `types/nostr-tools-extended.ts` : extensions SimplePool/Sub.
  - `types/alby.ts` : WebLNProvider, invoice types.

## 2) Guide Nostr (publication, update/delete, zap, remote signer)

- Publication générique : `nostrService.publishEvent(eventTemplate)` (signEvent, created_at contrôlé).
- Article : `articlePublisher.publishArticle` (preview + tags kind_type/site/category/series/banner/media), contenu privé chiffré stocké.
- Update article : `publishArticleUpdate` (`lib/articleMutations.ts`) tags `e` (original) + `replace`, publie preview + contenu privé chiffré.
- Delete article : `deleteArticleEvent` (kind 5, tag e) — erreurs remontées, pas de fallback.
- Série : `publishSeries` (kind 1, tags kind_type=series, cover, description).
- Avis : `publishReview` (kind 1, kind_type=review, article/series/author tags).
- Zap verification : `lib/zapVerification.ts` (verifyEvent).
- Agrégats : `aggregateZapSats` / `getSeriesAggregates` / `getReviewTipsForArticle`.
- Remote signer : `lib/nostrRemoteSigner.ts` (clé fournie), sans valeurs de repli implicites.

## 3) Guide Stockage

- Chiffrement : `cryptoHelpers` (AES-GCM), entrée BufferSource conforme Web Crypto.
- IndexedDB : `storage/indexedDB.ts` stocke `{ iv, ciphertext, expiresAt }`, purge `clearExpired`.
- Secret : `articleStorage` génère clé maître (localStorage, base64, 32 bytes) puis secret `<master>:<articleId>`.
- Données : contenu privé + facture, TTL 30 jours, suppression via `removeStoredPrivateContent`.

## 4) Guide Paiements

- WebLN/Alby : `lib/alby.ts` (enable, makeInvoice, sendPayment).
- Facture article : `createArticleInvoice` (zapAmount, expiry).
- Publication article : `articlePublisher` gère preview event + stockage contenu privé.
- Polling / vérif : `paymentPolling.ts`, `payment.ts`; agrégats via zap receipts (`zapAggregation.ts`).
- Envoi contenu privé : via publisher/mutations après paiement confirmé.

## 5) Médias / NIP-95

- Upload via `uploadMedia(file)` (URL `NEXT_PUBLIC_NIP95_UPLOAD_URL`), validation type/taille.
- Utilisation dans `MarkdownEditor` (insertion markdown), bannière dans ArticleDraft.

## 6) Contrib (référence rapide)

- Lint/typage obligatoires (`npm run lint`, `npm run type-check`).
- Pas de tests/analytics ajoutés.
- Pas de fallback implicite, pas de `ts-ignore`/`any` non justifié.
- Accessibilité : ARIA/clavier/contraste.
- Documentation : corrections dans `fixKnowledge/`, features dans `features/`.