rubis/CLAUDE.md

Rubis Sur l'Ongle

Le SaaS de relance de factures impayées pour TPE-PME françaises. Drag-and-drop, OCR, plans de relance automatiques. 1 rubis = 10 minutes libérées.

Ce fichier est le contexte top-level. Il est court, dense, scannable. Pour les détails, voir /docs/.

---

En une phrase

Vos factures se relancent toutes seules pendant que vous travaillez.

Cible

TPE-PME françaises, 5 à 50 salariés, qui émettent 10 à 200 factures par mois, sans crédit manager dédié. Le décideur teste lui-même le produit (pas de cycle de vente long).

Promesse de valeur

• 5 heures par semaine récupérées (benchmark : 8h → <3h après automatisation).
• Tonalité émotionnelle : on vend du temps libéré, pas de la trésorerie. Le rubis gagné est la métrique-héros, pas le DSO.
• 2 à 3 clics maximum pour lancer une relance sur une nouvelle facture.

Principes produit (toujours valides)

1. 3 clics maximum pour lancer une relance sur une facture neuve. Idéalement 2 si bien configuré.
2. Mobile et desktop — la photo de facture depuis le téléphone est un usage clé.
3. La relance reste l'âme du produit — c'est notre cœur de promesse. L'édition native de factures, ajoutée en V1.1 (cf. ADR-025), est une extension douce pour les utilisateurs sans outil de facturation existant. On reste sous-positionnés vs les vrais outils (Pennylane, Sellsy), pas concurrents frontaux. On ne fait toujours pas CRM ni comptabilité.
4. Respectueux du client final — le ton monte avec le retard, jamais avant. Pas d'agressivité par défaut.
5. Le rubis est une vraie devise produit — 1 rubis = 10 min libérées. La gamification doit être tangible et défendable.

Identité de marque (TLDR)

Logo	Direction A — gem facetté géométrique. Le ◆ est un symbole produit autant qu'un logo.
Couleur primaire	#9F1239 — rubis profond légèrement violacé. Anti-Coca-Cola.
Couleur secondaires	#771328 (deep), #C9415C (light), #FBE4EA (glow)
Neutres	Crème #FAF7F2, encre chaude #1A1410. Jamais de blanc pur, jamais de noir pur.
Typo display	Bricolage Grotesque (500–800), self-hosted via @fontsource-variable/bricolage-grotesque
Typo body	Inter (400–700), self-hosted via @fontsource-variable/inter
Icônes	Lucide (regular weight)
Pas de	or, bleu, vert, violet, emojis joaillerie 💎💰, mot "recouvrement" en com publique

Voir /docs/marque.md pour la référence complète et /docs/brand-identity.html pour la présentation visuelle.

Voix

Direct, concret, chaleureux, précis, empathique. On parle comme un bon associé, pas comme une DAF.

• ✓ "Vos factures relancées toutes seules."
• ✗ "Optimisez votre processus de recouvrement amiable."

Glossaire

• Rubis : unité de gamification. 1 rubis = 10 minutes libérées = 1 relance qu'on n'a pas eu à faire à la main.
• Plan de relance : cadence d'emails automatisés (ex. J+3, J+10, J+20). Chaque facture est associée à un plan.
• Étape : un email programmé dans un plan (ex. "J+10 — relance ferme").
• Confirmation (anciennement « check-in ») : email envoyé à l'utilisateur (pas au client) pour confirmer si une facture a été payée avant l'envoi de la prochaine relance. Remplace l'intégration banking en V1.
• Mise en demeure : étape ferme du plan. Toujours sous validation manuelle via modale de confirmation, jamais auto.
• Facture native : facture créée dans Rubis via l'éditeur /factures/nouvelle (vs. facture importée par OCR/saisie manuelle). PDF généré côté serveur via @react-pdf/renderer, snapshots client + émetteur immuables figés à l'émission. Drapeau invoices.is_native = true.
• Numéro de séquence : compteur strict séquentiel par organisation (invoices.sequence_number), alloué à l'émission d'une facture native via verrou row-level. Conforme art. 242 nonies A du CGI (chronologie continue). Le numéro affiché est <prefix><seq padé> (ex. FAC-2026-0042). Brouillons exclus du compteur.
• Snapshot : copie figée des données du client (client_snapshot) et de l'émetteur (issuer_snapshot) au moment de l'émission d'une facture native. Garantit l'immutabilité légale : la facture reste intacte même si le client change d'adresse ou si l'org modifie ses settings.
• Factur-X : format de facturation électronique mixte PDF/A-3 + XML CII embarqué, conforme à la réforme française B2B (obligation d'émission au 1er septembre 2027 pour TPE-PME). Roadmap V1.5 — pas en V1.
• DSO : Days Sales Outstanding. Métrique secondaire dans l'app, jamais dans la com publique.
• LME : loi de modernisation de l'économie (2008). Plafonne les délais de paiement à 60 jours (ou 45 jours fin de mois). Sanctions DGCCRF jusqu'à 2 M€.

Périmètre V1

IN

• Auth email/password + Google SSO + Microsoft SSO
• Onboarding 3 étapes (compte, entreprise, signature email)
• Upload drag-and-drop + OCR factures (PDF, PNG, JPG)
• Saisie manuelle (fallback)
• Édition native de factures (V1.1) — éditeur /factures/nouvelle avec lignes structurées, 4 thèmes pré-faits (Classique, Moderne, Minimal, Élégant), couleur d'accent paramétrable, génération PDF côté serveur via @react-pdf/renderer. Settings de facturation sur /parametres/facturation (identité émetteur, RIB, mentions légales, numérotation strict séquentielle). PDF classique en V1, Factur-X visé en V1.5 (Q3-Q4 2026), avant l'échéance d'émission TPE-PME au 1er sept 2027. Détails dans /docs/produit.md et ADR-025.
• Bibliothèque de plans (4 plans fournis par défaut : Standard B2B, Rapide, Patient, Ferme)
• Éditeur de plan (cadence + templates email avec variables)
• Confirmation par email à l'utilisateur (cadence configurable) → confirme si payé → relance ou stop. Anciennement « check-in ».
• Dashboard avec compteur rubis + KPIs (à relancer, encaissé, DSO)
• Liste filtrable des factures
• Détail facture avec timeline des relances
• Stripe billing (checkout, portal, webhook) + période de grâce post-signup
• Mode démo (sandbox in-app sans engagement)
• App mobile (web responsive)
• Blog rubis.pro/blog — SSR par apps/landing (Astro 6), contenu en DB (posts) servi par apps/api via /api/v1/posts/*, admin de validation côté app.rubis.pro/admin/blog, génération hebdomadaire IA via cron (Sonnet 4.6) avec review humaine obligatoire. Détails dans /docs/tech/architecture.md.
• Changelog rubis.pro/changelog — SSG par apps/landing, contenu en MD versionné dans apps/landing/src/content/changelog/<version>.md (Astro content collections, schéma Zod), RSS à /changelog/rss.xml. Toast SPA "Nouvelle version" déclenché par apps/web/src/components/version-toast.tsx quand APP_VERSION (apps/web/src/version.ts) diffère de localStorage["rubis:last-seen-version"]. Workflow release : /push (cf. .claude/skills/push/SKILL.md) bump la version + crée le .md + commit + push.

OUT (V2 ou plus tard)

• SMS — uniquement plan le plus cher en V2
• Multi-utilisateurs — uniquement plans payants en V2
• Intégration banking / réconciliation auto — l'architecture V1 doit l'anticiper, mais l'implémentation est V2+
• Multi-langues, multi-devises (FR/EUR only en V1)
• Intégration ERP/comptable (Sage, Pennylane, Quickbooks)

Pricing (esquisse, à valider)

Plan	Prix	Limite
Free	0 €	5 factures actives en relance, 1 utilisateur
Pro	19 €/mois	Factures illimitées, OCR illimité, 1 utilisateur
Business	49 €/mois	+ multi-utilisateurs, + branding email, + SMS (V2)

Argument de vente : "moins cher qu'une heure de votre temps mensuel".

Décisions clés validées (résumé)

Voir /docs/decisions.md pour le log complet avec rationale.

• 1 rubis = 10 minutes libérées
• Logo direction A (gem facetté), wordmark à monter en parallèle plus tard
• Palette rubis chaude, sans or, sans bleu
• Typo Bricolage Grotesque + Inter
• Iconographie Lucide
• Mise en demeure : validation manuelle obligatoire (modale)
• SMS et multi-users : V2 + plans payants seulement
• Banking intégration : pas en V1, remplacée par check-in emails
• Édition native de factures : extension douce (V1.1), pas pivot vers facturation complète. Conformité Factur-X visée en V1.5, PDP partenaire évaluée en V2 si demandes clients (cf. ADR-025).
• Numérotation strict séquentielle : compteur par org alloué en transaction (verrou row-level), brouillons exclus du compteur — choix vs flexible motivé par art. 242 nonies A du CGI.

Stack technique

Couche	Choix	Source
Backend (API)	AdonisJS v7 (TS, MVC, Lucid ORM, auth & jobs intégrés)	ADR-014
App SPA (app.rubis.pro)	React 19 + Vite + TanStack Router/Query	ADR-014
Landing + blog (rubis.pro)	Astro 6 SSR (pages statiques prerenderées + blog en SSR)	—
Design system	@rubis/ui — Tailwind v4 tokens + composants TSX	—
Base de données	PostgreSQL	ADR-014
Hosting	Proxmox + K3s (perso)	ADR-014
OCR provider	à benchmarker	ADR-020 (en attente)
Email outbound	à benchmarker	ADR-021 (en attente)
Génération PDF (factures natives)	@react-pdf/renderer côté API (Node), 4 templates dans apps/api/app/pdf-templates/	ADR-025

Architecture : monorepo Turborepo (apps/api AdonisJS, apps/web React SaaS, apps/landing Astro public, packages/shared types/schemas, packages/ui design system). API REST Bearer-auth, deux frontends qui consomment @rubis/ui pour un brand visuel unifié, PG et MinIO existants sur LXC Proxmox. Détails dans /docs/tech/architecture.md.

Décisions cadres : ADR-014 (stack), ADR-015 (monorepo), ADR-016 (PG Proxmox existant), ADR-017 (Bearer tokens), ADR-018 (MinIO existant).

Conventions techniques (cross-cutting)

• Identifiants : UUID partout. Toutes les PK et FK applicatives sont des UUID v4 (PG uuid avec default gen_random_uuid()). Jamais d'increments/serial, même pour les tables internes (auth tokens, sessions, refresh tokens, etc.). Les UUID protègent de l'énumération, simplifient la fédération multi-tenant et évitent les fuites de volumes par incrément. Les transformers exposent les UUID directement en string — pas de cast nécessaire.

Documents associés

Fichier	Rôle
/CLAUDE.md (ce fichier)	Contexte top-level, toujours en tête
/apps/landing/	Landing publique + blog (Astro 6 SSR) — déployée sur rubis.pro
/apps/landing/public/favicon.{svg,ico,png}	Set complet de favicons + apple-touch-icon
/apps/landing/public/site.webmanifest	Manifest PWA (theme #9F1239, background #FAF7F2)
/packages/ui/	Design system partagé (tokens Tailwind v4 + composants TSX)
/docs/produit.md	Spec produit haut niveau (features, IN/OUT V1, pricing). Inclut la section "Édition native des factures".
/docs/flow.md	Comportement produit deep-dive : cycle de vie d'une facture, statuts + transitions, surfaces UI, mécanique de confirmation (check-in), mode démo, edge cases. Flow native = lignes structurées + snapshots immuables.
/apps/api/app/pdf-templates/	4 templates @react-pdf/renderer (Classique, Moderne, Minimal, Élégant) + dispatcher. Génération PDF native côté serveur.
/apps/web/src/routes/_app/parametres_.facturation.tsx	Page de paramétrage de l'éditeur de factures (identité émetteur, RIB, mentions, numérotation, thème par défaut).
/apps/web/src/routes/_app/factures_.nouvelle.tsx	Éditeur split-view : édition à gauche, preview PDF live à droite (debounce 500 ms).
/docs/marque.md	Référence marque écrite (palette, typo, voix, do/don't)
/docs/decisions.md	Log de décisions avec rationale (format ADR-light)
/docs/wireframes-mvp.html	Wireframes low-fi des 13 écrans MVP
/docs/brand-identity.html	Présentation visuelle de la marque (4 logos, applications)
/docs/munitions-marketing.md	Stats marché, concurrents, positionnement, copy
/docs/marketing/playbook.md	Playbook acquisition premiers clients : ICP, Dream 100, channels, templates outreach
/docs/tech/architecture.md	Architecture technique : composants, flux, topologie, conventions
/docs/tech/frontend.md	Guide d'implémentation frontend (deps, Tailwind, TanStack, Tuyau)
/Dockerfile	Build nginx-alpine servant /landing/ sur port 80
/k3s/	Manifests Kubernetes (namespace, deployment, service)
/.claude/deploy-memory.md	Procédure de déploiement (Gitea CI ou manuel)
/.claude/skills/push/SKILL.md	Skill Claude Code /push — release automatisée (bump version + entrée changelog + commit + push)
/apps/landing/src/content/changelog/	Une entrée Markdown par version (source de vérité du changelog public /changelog)
/apps/web/src/version.ts	Constante APP_VERSION — déclenche le toast "Nouvelle version" dans la SPA

Déploiement

• Domaine principal : https://rubis.pro (landing + blog Astro) + https://app.rubis.pro (SaaS React)
• Image landing : git.arthurbarre.fr/ordinarthur/rubis-landing:latest (Astro Node SSR, port 4321)
• Image API : git.arthurbarre.fr/ordinarthur/rubis-api:latest (port 3333)
• Image SPA : git.arthurbarre.fr/ordinarthur/rubis-web:latest (nginx + proxy /api → rubis-api)
• Compat : rubis.arthurbarre.fr / app.rubis.arthurbarre.fr redirigent en 301 vers rubis.pro / app.rubis.pro (config Traefik dans repo proxmox)
• Voir .claude/deploy-memory.md pour la procédure complète.

Email infrastructure (rubis.pro)

Deux flux distincts qui cohabitent sur le même domaine via des sous-domaines DNS séparés :

Flux	Provider	Adresse	DNS clés
Sortant (relances, check-in, auth)	Resend	relances@rubis.pro	send.rubis.pro (MX + SPF), resend._domainkey (DKIM), _dmarc
Entrant (humain)	OVH MX Plan	contact@rubis.pro (général + RGPD), dev@rubis.pro (notifs tech)	MX @ → mx*.mail.ovh.net.

Détails dans /docs/tech/backend.md §12.5.

Questions ouvertes

• Conversion 1 rubis = 10 min validée mais à confirmer en user testing après MVP
• Wordmark "rubis" avec gem-i (direction C) à monter en complément du logo A à un moment
• Provider OCR à benchmarker (Mindee, Document AI, Textract, Tesseract)

---

Dernière mise à jour : 2026-05-09 · Maintenu par Arthur + Claude.