Architecture technique

Vue d'ensemble du code Check Kit : stack, structure du dépôt, schéma de données Convex, routes et tests

Check Kit est construit sur le boilerplate NowStack : TanStack Start (React 19, rendu SSR + prérendu), Convex comme backend unique (base de données, fonctions, crons, HTTP) et Better Auth pour l'authentification et les organisations. L'application est multi-tenant : chaque table métier porte organizationId et tout accès passe par les wrappers d'autorisation de convex/auth/functions.ts.

Stack

Couche	Technologie
Frontend	TanStack Start + TanStack Router (routes fichiers), React 19, TailwindCSS v4, shadcn/base-ui
Backend	Convex uniquement (pas de Prisma/PostgreSQL)
Auth	Better Auth via `@convex-dev/better-auth` (plugins organization, apiKey, emailOTP, admin)
Facturation	Stripe (actions Convex `"use node"` + webhook `httpAction`)
Emails	Resend via composant `@convex-dev/resend`, templates react-email
Fichiers	Cloudflare R2 (`@aws-sdk/client-s3`) pour photos et avatars
PDF	`@react-pdf/renderer` (étiquettes, registre sanitaire, stocks)

Structure du dépôt

convex/           # Backend : schéma, fonctions, crons, routeur HTTP
src/routes/       # Routes TanStack (file-based)
src/features/     # Logique UI transverse (dialogs, formulaires, billing…)
content/docs|posts|changelog/   # Contenu MDX (docs, blog, changelog)
e2e/              # Tests Playwright
mobile-app/       # Projet Expo autonome (app mobile, backend Convex partagé)
scripts/          # Outillage (start-all, deploy Vercel, webhook Stripe…)
.agents/          # Skills et règles pour les agents IA

Schéma de données HACCP

Tout le schéma vit dans convex/schema.ts. Les tables cœur du métier :

Table	Rôle	Champs clés
`sites`	Établissement	`nom`, `offre` (light/premium/premium_pack)
`lieux`	Zone d'un site	`type` (froid/chaud/ambiant/nettoyage/stockage), `seuilMin`/`seuilMax` (consignes de température)
`temperatureReadings`	Relevés de température	`temperature`, `anomalie` (calculée vs seuils du lieu), `userId` (ou `iot:<deviceId>`)
`nettoyages`	Relevés de nettoyage	`taches[{libelle, fait}]`, `debutAt`/`finAt`
`tracabilite`	Réceptions et fabrications	`type` (reception/fabrication), `numLot`, `dlc`, `photoUrls[]` (R2), `ingredients[]`, origine viande bovine, `sortie`
`stockMouvements`	Historique de traçabilité	`type` (entree/mouvement/sortie/retour/modification)
`capteurs`	Sondes IoT	`deviceId` (unique), `token` (secret serveur), `lastTemperature`
`misesEnTemperature`	Refroidissement / remise / cuisson	`tempDebut`/`tempFin`, `anomalie`
`controlesHuile`	Tests d'huile de friture	`friteuse`, `conforme`, `action`
`nettoyagesPlanifies`, `controlesPlanifies`, `tachesPlanifiees`	Récurrences et rappels	`frequenceJours`, `prochaineEcheance`, `statut`
`denrees`, `fournisseurs`, `recettes`, `nettoyageZones`	Référentiels de paramétrage	—
`optionsCheckKit`	Modules optionnels par organisation	`allergenes`, `decongelation`, `origineViande`, `expeditions`…
`alerteParametres`	Seuil d'alerte DLC	`joursAvant` (1–5)

Côté SaaS : subscriptions (abonnements Stripe, overrideLimits, remises admin_free), feedbacks, orgOnboarding, memberWelcome, demoRegistry (purge des données de démo), publicTokens (liens publics 256-bit).

Le dépôt contient aussi des tables héritées du socle « Formation Now » (trainings, sessions, learners, invoices, qualiopi…) : elles ne font pas partie du produit Check Kit mais restent dans le schéma.

Modules Convex

sites/, lieux/, temperatures/, nettoyages/, tracabilite/, misesEnTemperature/, controlesHuile/, capteurs/ — CRUD métier HACCP. Convention : mutations createX/updateX/deleteX, queries listBySite/getById. sites/helpers.ts expose requireSiteAccess.
denrees/, fournisseurs/, recettes/, nettoyageZones/, optionsCheckKit/, controlesPlanifies/, nettoyagesPlanifies/, tachesPlanifiees/ — paramétrage et planification (advancerProgramme, countDueByOrg, listDueBySite).
auth/ — configuration Better Auth (config.ts), wrappers orgQuery/orgMutation/orgAction (functions.ts), rôles et permissions (permissions.ts).
billing/plans.ts — définitions des plans, limites et helpers (voir la page Paramétrage & environnements).
stripe/actions.ts — checkout, portail de facturation, webhook (processWebhook).
email/ — envoi via Resend (sendMarkdownEmail), templates markdown avec logo.
apiKeys/ — résolution clé API → organisation pour l'API publique v1.
export/ — getFullExportData (export complet d'une organisation).
demo/ — jeu de données de démonstration (seedDemoData/removeDemoData).
admin/ — back-office SaaS (organisations, abonnements, feedbacks).

Crons (convex/crons.ts) : auto-complete expired sessions à 03:00 UTC et notify expiring DLC à 07:00 UTC (email quotidien d'alerte péremption aux admins, voir tracabilite/crons.ts).

Routeur HTTP (convex/http.ts) : POST /sensors/reading (ingestion capteurs), POST /stripe/webhook, et les endpoints GET /api/v1/* (API publique par clé API).

Routes frontend

(layout)/ — site public : docs, blog, changelog, contact, pages légales.
auth/ — connexion split-screen (code email + mot de passe + providers), inscription, ban, réinitialisation.
orgs/$orgSlug/(navigation)/ — l'application métier : temperatures/, nettoyages/, tracabilite/, stocks/, alertes/, recherche/ (+ registre PDF), parametres/ (sites, lieux, denrées, fournisseurs, recettes, capteurs, planifications), settings/ (billing, membres, clés API, export, danger), demo/, aide/.
admin/ — back-office SaaS (organisations, utilisateurs, MRR).
(logged-in)/account/ — profil, email, mot de passe, suppression de compte.
Routes spéciales : favicon.ts (pastille d'environnement dev/preview), sitemap.xml.ts, robots.txt.ts, feed.xml.ts, og.png.ts.

Chaque page métier suit le même motif : une route index.tsx avec pendingComponent (skeleton fidèle au layout final), des dialogs open-*-dialog.tsx pilotés par le dialog manager, et des schémas de validation *.schema.ts (zod).

Tests

Vitest (src/__tests__/, happy-dom) : socle NowStack — auth (plans, permissions, sessions, formulaires signin/signup), dialog manager, formulaires, utilitaires (dates françaises, slugs réservés, hooks). Lancer avec pnpm test:ci.
Playwright (e2e/) : parcours compte, admin, organisations (création, slug, membres, invitations), reset mot de passe, connexion en modal. Lancer avec pnpm test:e2e:ci.

Les modules HACCP (températures, traçabilité, capteurs) n'ont pas encore de couverture de test dédiée — les vérifications passent par le typecheck (pnpm ts) et les tests manuels en navigateur.

Équipe et abonnement Configuration & environnements