Architecture, Vue d'ensemble
Conceptualisation backend, modélisation et architecture du projet Reciprok
Le point de référence pour penser le système avant d'écrire une ligne de code métier.
Vision
Reciprok est une plateforme interne de mise en relation entre organisateurs d'événements et membres (établissements, lieux événementiels, prestataires).
Trois piliers :
- Centraliser tout le flow, de la demande à la commission, sans rien perdre en route.
- L'IA est un acteur, pas un gadget, Claude intervient à chaque étape, agit (pas juste répond), apprend des corrections.
- Édition en contexte, l'utilisateur ne quitte jamais la demande en cours pour corriger une fiche, ajouter une photo, mettre à jour un tag.
Stack retenue
| Couche | Choix |
|---|---|
| Runtime | Bun |
| Backend | Elysia + Eden Treaty (cf. ADR-04) |
| Frontend | Next.js 16 (App Router) |
| ORM | Drizzle |
| Base | PostgreSQL 18 + pgvector, self-host Dokploy (cf. ADR-01, ADR-06) |
| LLM | Claude (Anthropic, Sonnet 4.6), cf. ADR-02 |
| Embeddings | OpenAI text-embedding-3-small |
| Audio | Whisper API |
| Resend (cf. ADR-05) | |
| API Meta Cloud | |
| Storage | Cloudflare R2 |
| Auth équipe | Better Auth |
| Auth membres / organisateurs | Magic tokens custom |
| Hébergement | Hostinger VPS + Dokploy |
| Monitoring | Grafana + Loki + Prometheus + GlitchTip + Uptime Kuma (self-host) |
Principes architecturaux
-
Une seule entité
Member, pas de séparation Restaurant/Lieu/Prestataire. Le profil métier est porté par lestagset lesRoomCapacity. -
Event sourcing pour la timeline, chaque action sur une demande génère un
TimelineEventimmuable, typé via les domain events (cf. Intelligence). La timeline n'est pas un memo texte, c'est un append-only log structuré. -
L'IA est un client de l'API comme un autre, Claude appelle des outils (tools) qui sont les mêmes endpoints que l'utilisateur. Pas de "couche IA" séparée. Garantit auditabilité et traçabilité.
-
Recherche en 3 étapes, filtrage SQL dur → recherche vectorielle → ranking LLM. L'IA ne lit JAMAIS 70k fiches. Cf. ADR-03 et la page Search Strategy.
-
Knowledge base sourcée, chaque entrée porte sa source (audio transcrit, saisie manuelle, audit, structuré par l'IA).
-
Édition en contexte = mutations latérales, depuis une demande, on peut modifier le membre #102, ajouter une photo, mettre à jour un tag.
-
Pas de "v2", c'est le projet from scratch. Pas de migration depuis une ancienne base. Liberté totale sur les schémas.
-
Self-host first, chaque fois qu'une solution open source tient la route, on l'auto-héberge sur Dokploy. Le budget va vers les services à valeur ajoutée IA, pas vers du SaaS de support.
Comment lire cette section
Cette section "Architecture" couvre la conceptualisation du système. Elle est organisée en 5 chapitres :
| Chapitre | Sujet |
|---|---|
| Overview | Acteurs, flows métier, spec fonctionnelle |
| Data | Entités, schéma Drizzle, timeline events |
| API | Design d'API Eden Treaty + best practices Elysia |
| Intelligence | Architecture IA, recherche sémantique, KB, domain events |
| Infra | Intégrations externes (Resend, Meta, Whisper, R2…) |
Les autres sections du site (sélectionnables dans le menu en haut de la sidebar) sont :
- Décisions, les ADRs (Architecture Decision Records)
- Opérations, auth, environnements, monitoring, coûts, RGPD, concurrence
- Conventions, nommage, modules, seuils de fichiers, factorisation, code style, git workflow
Hors-scope (pour l'instant)
- Application mobile native (PWA suffit)
- Multi-tenancy / SaaS
- Marketplace publique
- Système de paiement intégré
- Système de réservation direct