Documentation PostCards

Guide complet pour développer et déployer sur la plateforme PostCards.

Guide de démarrage

Prérequis

• Node.js ≥ 18
• npm ≥ 9 ou yarn
• Compte Convex
• Compte Clerk
• Compte Stripe (pour les paiements)

Installation

# Cloner le repo
git clone <repo-url>
cd postcards-apps

# Installer les dépendances
npm install

# Configurer l'environnement
cp apps/web/.env.example apps/web/.env.local
cp apps/native/.env.example apps/native/.env

# Lancer le backend
cd packages/backend && npx convex dev

# Dans un autre terminal, lancer le web
cd apps/web && npm run dev

Architecture

Vue d'ensemble

PostCards est une plateforme SaaS composée de trois applications principales :

• App Native - React Native + Expo pour iOS et Android
• App Web - Next.js 15 pour le dashboard photographe et portail client
• Backend - Convex pour la logique métier et la base de données

Stack technique

Gestion des Rôles (RBAC)

L'accès aux galeries est géré via la tablegallery_members. Chaque membre se voit attribuer un rôle déterminant ses permissions :

API Backend

Le backend est entièrement géré par Convex. Consultez les fichiers danspackages/backend/convex/ pour la référence complète.

Fonctions principales

Stripe Connect

Les photographes peuvent recevoir des paiements via Stripe Connect. Le flux d'escrow garantit que les fonds sont bloqués jusqu'à confirmation.

Flux de paiement

1. Client autorise le paiement (fonds bloqués)
2. Photographe confirme la livraison
3. Fonds libérés vers le compte Stripe du photographe
4. Timeout 14 jours → libération automatique

Fees

Variables d'environnement

Convex Dashboard

CLERK_ISSUER_URL
STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET
STRIPE_CLIENT_ID
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_S3_BUCKET
AWS_CLOUDFRONT_DOMAIN
FIREBASE_PROJECT_ID
FIREBASE_PRIVATE_KEY
FIREBASE_CLIENT_EMAIL

Web (.env.local)

NEXT_PUBLIC_CONVEX_URL
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

Native (.env)

EXPO_PUBLIC_CONVEX_URL
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY

Pipeline images optimisé

Le pipeline d'images utilise une stratégie multi-niveaux pour garantir des temps de chargement rapides et une consommation mémoire stable :

1. Compression côté client — Les images sont redimensionnées à 2048px max (JPEG 70%) et un thumbnail 300px est généré avant upload.
2. Upload parallèle — Original compressé + thumbnail uploadés simultanément sur S3.
3. Affichage optimisé — OptimizedImage choisit automatiquement le thumbnail pour les grilles et le preview pour le viewer.
4. Virtualisation — La galerie publique utilise @tanstack/react-virtual avec pagination (30 items/page) pour ne jamais surcharger le DOM.

Chat B2B

Le chat projet permet la communication photographe-client avec références directes aux photos de la galerie :

• Messagerie temps réel (Convex subscriptions)
• Mentions de médias (sélection visuelle dans la sidebar)
• Historique persistant, avatars colorés, états de lecture
• Interface compacte (panel galerie) ou pleine page (/messages)

Planning Kanban

Le tableau Kanban remplace la page livraisons pour un suivi visuel des projets :

• 4 colonnes : À faire / En cours / Livré / Expiré
• Drag & drop via @dnd-kit
• Publier une galerie = déplace automatiquement en "Livré"
• Export ICS pour intégration calendrier

Ingestion Prospects (Leads)

Le CRM intègre un endpoint public POST /api/leads permettant de brancher n'importe quel formulaire externe (Wix, WordPress, etc.). Les prospects apparaissent ensuite dans le Kanban unifié.

Devis & Contrats (DocuSeal)

Depuis le Kanban, un prospect peut être converti en projet via l'émission d'un devis. Une fois accepté, le contrat est généré légalement via l'intégration DocuSeal.

Facturation & Automatisations (Resend)

PostCards automatise entièrement le cycle financier (Loi Anti-Fraude activée) :

• Acompte (30%) : Généré automatiquement à l'acceptation du devis.
• Solde (70%) : Facturé automatiquement et envoyé par e-mail via Resend lorsque la galerie passe au statut "Livrée".
• Rappels : Un e-mail de rappel est envoyé automatiquement à J-3 de la date de la séance.