Reconnexion/festipod
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(concepts): migrate project docs into 7 concepts + code-grounded audit

Browse Source 
Migrate .project/{knowledge,decisions,briefs} and the always-loaded
AGENTS.md/CLAUDE.md into the in-repo `concept` system (hook-delivered,
typed leaves). Then audit the actual code to verify the migrated doctrine
and capture knowledge that lived only in the source.

Concepts (53 leaves):
- functional-domain — produit : point de rencontre greffé, acteurs, déduplication
- app-architecture — modules, invariant d'imports, routing, écrans, styling-system,
  screen-pattern, cookbook d'ajout d'écran
- tech-stack — Bun-first, APIs, build pipeline, deployment (Dockerfile), commandes
- data-layer — NextGraph mono-store, shapes, modes, règles + caveats (suppression,
  champs non persistés, internals du contexte)
- bdd-testing — Cucumber multi-couches, contrat de couches, harness, cookbook
- app-security — posture actuelle (mono-store, confiance broker), auth wallet,
  brief matrice d'autorisations cible
- nextgraph-platform — NextGraph système externe + briefs (multi-store, shim, fork)

Audit corrections:
- décision SPARQL-delete annulée (superseded) → caveat (le code utilise ngSet.delete,
  persistance possiblement partielle)
- divergences relevées : routing path-based (pas hash), thème moderne sous components/sketchy,
  ConnectScreen hors registre, build:orm au chemin périmé, champs d'event perdus en connecté

Strip migrated sources; AGENTS.md/CLAUDE.md réduits au cœur (but, invariants,
carte des concepts) + pointeurs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Sylvain Duchesne
2026-06-15 14:58:44 +02:00
parent 445a448031
commit 0294e3992f
71 changed files with 2012 additions and 1916 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+23 -70
View File
@@ -1,78 +1,31 @@
# Festipod
Mobile-first web app for discovering and sharing festival/event recommendations through trusted networks.
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é).
## Architecture
## Invariants à toujours garder
Feature-based: code organized by business domain, not technical layer. See [architecture](.project/knowledge/architecture.md).
- **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).
```
src/modules/{event,user,home,auth,workshop,meeting,notification}/
src/shared/ # Components, context, data — importable by all modules
src/app/ # App shell (router, providers, entry point)
src/screens/index.ts # Screen registry (used by Storybook)
```
## Doctrine du projet — concepts (livrée automatiquement)
## Routing
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 :
Path-based routing with History API (custom router in `src/app/router.tsx`).
| Concept | Couvre |
|---|---|
| `functional-domain` | Modèle produit : point de rencontre, acteurs, concepts métier, 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` | NextGraph actuel (mono-store), shapes, modes connected/demo, règles + pièges (suppression, champs perdus, internals) |
| `bdd-testing` | Cucumber multi-couches FR, contrat `@ui`/`@data`/`@e2e`, harness broker, cookbook |
| `app-security` | Posture de sécurité actuelle (mono-store, confiance broker), auth wallet, modèle d'autorisations cible |
| `nextgraph-platform` | NextGraph système externe (stores, inbox, SDK) + briefs prospectifs (multi-store, fork, shim) |
| Path | Screen |
|------|--------|
| `/` | WelcomeScreen |
| `/login` | LoginScreen |
| `/home` | HomeScreen |
| `/events` | EventsScreen |
| `/events/new` | CreateEventScreen |
| `/events/:id` | EventDetailScreen |
| `/events/:id/edit` | UpdateEventScreen |
| `/events/:id/invite` | InviteScreen |
| `/events/:id/participants` | ParticipantsListScreen |
| `/events/:id/meeting-points` | MeetingPointsScreen |
| `/profile` | ProfileScreen |
| `/profile/edit` | UpdateProfileScreen |
| `/profile/friends` | FriendsListScreen |
| `/profile/share` | ShareProfileScreen |
| `/users/:id` | UserProfileScreen |
| `/settings` | SettingsScreen |
Screens use `useNavigate()` and `useParams()` hooks from the router — no prop drilling.
## Data Layer
NextGraph (P2P/local-first) with SHEX shapes and ORM. See [data-layer](.project/knowledge/data-layer.md).
## BDD Testing
Multi-layer Cucumber/Gherkin in French. See [bdd-testing](.project/knowledge/bdd-testing.md) for the setup and [test-layer-contracts](.project/knowledge/test-layer-contracts.md) for what each layer is allowed to test.
`@ui` scenarios render screens in-process (happy-dom + seed data) and assert on the DOM. `@data` scenarios test data operations through the real NextGraph broker. `@e2e` scenarios test the real app UI in the broker iframe. See [data-layer-testing](.project/knowledge/data-layer-testing.md).
## Quick Start
```bash
bun run dev # Dev server with HMR (port 3000)
bun run build # Production build to dist/
bun run storybook # Browse screens and components
bun run test:cucumber # Run all BDD tests
bun run features:parse # Regenerate features.ts from .feature files
bun run steps:extract # Extract step definitions for tooltips
bun run build:orm # Regenerate ORM from SHEX shapes
```
## Documentation
- [Architecture](.project/knowledge/architecture.md) — module structure, import rules, app shell
- [Data Layer](.project/knowledge/data-layer.md) — NextGraph, shapes, context, seed data
- [BDD Testing](.project/knowledge/bdd-testing.md) — Cucumber setup, step layers, feature files
- [Test Layer Contracts](.project/knowledge/test-layer-contracts.md) — what each of `@ui`/`@data`/`@e2e` is allowed to test
- [Screens](.project/knowledge/screens.md) — screen inventory, registry, sketchy components
- [Data-Layer Testing](.project/knowledge/data-layer-testing.md) — real broker testing, wallet setup, Playwright harness, e2e layer
- [Stores NextGraph et droits d'accès](.project/knowledge/nextgraph-stores-permissions.md) — fiche de référence des 5 types de stores et de leurs permissions
- [Modèle d'intégration NextGraph](.project/knowledge/nextgraph-integration-model.md) — paquets JS, modèle iframe, où tourne le verifier, reciblage du broker
## Briefs (work not yet started)
- [Multi-store refactor](.project/briefs/multi-store-refactor.md) — passer du mono-store actuel à une structure de Group stores par communauté/event/RDV (prérequis multi-user)
- [Matrice d'autorisations et requêtes](.project/briefs/authorization-matrix.md) — analyse qui doit guider la structure de stores cible
- [Forker NextGraph pour l'inbox](.project/briefs/fork-nextgraph-inbox.md) — patcher nextgraph-rs pour exposer l'inbox au SDK JS (notification d'inscription)
Pour **documenter** un fait projet : `/concept document <sujet>` (ne pas écrire en libre dans `.project/`).