Sylvain Duchesne
7459d49e83
RECADRAGE — la doctrine était trop étroite. rule_app-uses-sdk-surface-only disait « le polyfill existe pour le WALLET VIRTUEL » : juste sur le fond, mais à la lettre l'émulation des caps qu'on vient de livrer n'entrait pas dans son mandat. Nouvelle formulation, portée aussi dans AGENTS.md : @ng-eventually/client est un POLYFILL, et ce mot dit toute sa mission : compenser l'écart entre le SDK tel qu'il devrait être et ce que NextGraph fournit aujourd'hui. Le wallet virtuel en est la plus grosse pièce, pas la totalité. Avec la conséquence opérationnelle : quand quelque chose ne marche pas, la question n'est jamais « comment contourner dans l'app » mais « qu'est-ce que le polyfill doit compenser ». Un contournement côté app est une violation même quand il fonctionne — il grave un état temporaire de NextGraph dans du code qui doit lui survivre. Et l'ignorance de l'état d'implémentation est durcie : ENTIÈREMENT, pas « sauf quand ça mord ». NOUVEAU — data-layer/knowledge_sdk-surface : le contrat SDK cible, écrit dans CE repo pour qu'un agent n'ait jamais à ouvrir le repo du polyfill. Couvre lectures réactives, écritures, placement par scope, inbox, discovery, capabilities (capFor/shareCap/publishRepoLink, livrées avec P1a), identité, sûreté SPARQL — et les surfaces exportées mais interdites à l'app. DOCTRINE PÉRIMÉE corrigée, après vérification dans le code : - rule_document-per-entity décrivait la lecture via readEntities/readUnion/ registerDoc/bumpRead : ZÉRO site d'appel, readEntities.ts supprimé. Réécrite sur watchShape/useShapeQuery. Le fond (un document par entité) est intact. - brief_2026-07-06 §P3 réaffirmait une phrase que son propre encadré déclare fausse : rétractée explicitement. - knowledge_data-modes citait useShapeWithDefaults(), qui n'existe nulle part. - ConnectScreen : les fiches avaient raison mais étaient vagues — l'écran existe, est routé et monté, et est bien absent du registre. Précisé. FIX CODE — build:orm était CASSÉ : il pointait ./src/shapes/, qui n'existe pas (les shapes vivent sous src/shared/shapes/), et sortait en erreur. Donc la commande que la doctrine prescrit après tout changement de .shex ne marchait pas. Corrigé et vérifié : exit 0. La fiche avait raison, c'est le code qui était faux — le point 4 approuvé, simplement situé dans l'autre fichier. Régénération NON embarquée : lancer build:orm reformate les bindings et retire l'annotation `: Schema`. C'est une montée de version d'outil, pas une correction de contenu — elle mérite son propre changement validé, pas un passage clandestin. Noté dans la fiche. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014GbGgNEHRejVKoREvFuDFg
41 lines
3.5 KiB
Markdown
41 lines
3.5 KiB
Markdown
# Festipod
|
|
|
|
Web app mobile-first où les utilisateurs créent des **points de rencontre** qui se *greffent* sur des **événements publics** existants, pour favoriser les rencontres. L'événement n'est qu'un prétexte/ancrage ; la valeur, c'est le point de rencontre — **on s'inscrit à un point de rencontre, pas à un événement**. Stack : Bun + React + NextGraph (P2P, local-first, chiffré).
|
|
|
|
## Invariants à toujours garder
|
|
|
|
- **Architecture feature-based** : le code est organisé par domaine métier, pas par couche technique.
|
|
```
|
|
src/modules/{event,user,home,auth,workshop,meeting,notification}/
|
|
src/shared/ # Composants, context, data — importable par tous les modules
|
|
src/app/ # App shell (router, providers, entrée)
|
|
src/screens/index.ts # Registre d'écrans (utilisé par Storybook)
|
|
```
|
|
- **Un module n'importe QUE depuis `shared/` — jamais d'un autre module.** C'est l'invariant qui rend l'archi réelle.
|
|
- **Bun-first** : `bun` / `bun install` / `bun test` / `bun build`, jamais node/npm/vite/jest. `bun run dev` (port 3000).
|
|
|
|
## Frontière SDK NextGraph
|
|
|
|
Le SDK de données de Festipod est **`@ng-eventually/client`** — traité comme un **SDK NextGraph fini et mature** (documents par entité placés par scope public/protected/private, capabilities, inboxes). Il est injecté une seule fois via `ngSession.configure(...)`.
|
|
|
|
**`@ng-eventually/client` est un POLYFILL**, et ce mot dit toute sa mission : **compenser l'écart** entre le SDK **tel qu'il devrait être** et ce que NextGraph fournit **aujourd'hui**. Le wallet virtuel (plusieurs identités sur un wallet physique) en est la plus grosse pièce, pas la totalité.
|
|
|
|
**L'app ignore ENTIÈREMENT l'état d'implémentation de NextGraph.** Elle est codée contre le SDK cible, dont le contrat est écrit **dans ce repo** (concept `data-layer`, fiche `knowledge_sdk-surface`). Aucun code ni commentaire du type « on fait X parce que NextGraph fait Y aujourd'hui ». Quand quelque chose ne marche pas, la question n'est jamais « comment contourner dans l'app » mais **« qu'est-ce que le polyfill doit compenser »**.
|
|
|
|
**Ne jamais documenter dans ce repo l'état courant de NextGraph** (contraintes du SDK sous-jacent, contournements, internes broker/verifier) : cela vit dans le repo `@ng-eventually/client`. La doctrine Festipod décrit uniquement *le contrat SDK cible* + *comment Festipod l'utilise* + le domaine + l'architecture + le contrat BDD.
|
|
|
|
## Doctrine du projet — concepts (livrée automatiquement)
|
|
|
|
La connaissance détaillée vit dans `.project/concepts/` (système *concept*) : fiches courtes, typées, **livrées par un hook quand tu touches leur territoire** — tu n'as pas à les charger d'avance. Les 6 concepts :
|
|
|
|
| Concept | Couvre |
|
|
|---|---|
|
|
| `functional-domain` | Modèle produit : point de rencontre, acteurs, concepts métier, périmètres public/protected/private par entité, découverte, défi déduplication |
|
|
| `app-architecture` | Modules, invariant d'imports, app shell, routing path-based, écrans |
|
|
| `tech-stack` | Bun-first, APIs Bun, build pipeline, commandes |
|
|
| `data-layer` | Persistance via le SDK `@ng-eventually/client` : entités-documents par scope, shapes SHEX/ORM, modes connected/demo, pièges |
|
|
| `bdd-testing` | Cucumber multi-couches FR, contrat `@ui`/`@data`/`@e2e`, harness broker, cookbook |
|
|
| `app-security` | Isolation déléguée au SDK (pas de contrôle d'accès dans les écrans), auth wallet, matrice d'autorisations cible |
|
|
|
|
Pour **documenter** un fait projet : `/concept document <sujet>` (ne pas écrire en libre dans `.project/`).
|