Iris Operator
→ ton clone en multi-plateforme

# Mission Construis un dashboard e-commerce DTC nommé "OPERATOR" calqué sur "Iris Operator". C'est un cockpit BI pour un fondateur solo qui pilote une boutique Shopify avec spend pub multi-régies. Pas multi-tenant, pas SaaS — un seul user (moi), une seule marque. ## Stack imposée - Next.js 16 (App Router) + React 19 + TypeScript - Tailwind CSS v4 (pas de lib UI, composants maison) - Recharts pour les charts - API routes Next pour tout le backend (pas de serveur séparé) - Firestore pour le cache des appels API + events Snooper - Supabase pour l'auth admin + table "journal_events" - Déployable Vercel ou Cloud Run, Dockerfile multi-stage - Variables d'env via .env.local (pas de Doppler / Infisical au début) ## Intégrations à brancher # Shopify Admin API (OAuth client_credentials, version 2025-10) - SHOPIFY_STORE, SHOPIFY_CLIENT_ID, SHOPIFY_CLIENT_SECRET - Récupère orders, products, variants, customers - Module wrapper lib/shopify.ts avec cache token 1h # Meta Marketing API (v19+, scope ads_management + ads_read) - META_ACCESS_TOKEN, META_AD_ACCOUNT_ID - Récupère insights campaigns + adsets + ads avec spend, revenue, purchases, ROAS - Mutation pour pause campaign / adset - Module lib/meta-ads.ts # Google Ads API (developer token + OAuth refresh token) - GOOGLE_ADS_CUSTOMER_ID, GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET - Récupère insights campaigns + ad groups (cost, conversions, conv_value, ctr) - Mutation pour pause campaign - Module lib/google-ads.ts # Microsoft Advertising API (OAuth + dev token) - MICROSOFT_ADS_CUSTOMER_ID, MICROSOFT_ADS_ACCOUNT_ID, MICROSOFT_ADS_DEV_TOKEN, MICROSOFT_ADS_REFRESH_TOKEN, MICROSOFT_ADS_CLIENT_ID - Récupère campaigns performance report + ad groups - Module lib/microsoft-ads.ts # Pinterest Ads API (v5) - PINTEREST_ACCESS_TOKEN, PINTEREST_AD_ACCOUNT_ID - Récupère analytics campaigns + ad groups (spend, conversions, ROAS) - Module lib/pinterest-ads.ts # Klaviyo API (revision 2024-10) - KLAVIYO_API_KEY - Récupère campaign + flow performance metrics - Sync nightly + snapshot Firestore # Notifs (optionnel mais recommandé) - TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID pour alertes Snooper / Kill List - MAILGUN_API_KEY pour digest email quotidien ## Architecture & règles 1. Toutes les pages sont en /app/<module>/page.tsx, toutes les routes en /app/api/<module>/route.ts 2. Chaque API route DOIT être cachée via un helper cached(key, fn, ttlMs) : - 5 min sur les données du jour en cours - 1h sur les données passées - 24h sur les snapshots Klaviyo 3. Hook client useStaleData<T>(url) qui retourne { data, loading, refreshing } et fait du stale-while-revalidate via localStorage 4. Aggrégateur lib/ads-multi.ts qui unifie Meta + Google + MS + Pinterest derrière une interface commune AdsPlatform avec getDailySpend, getCampaignInsights, pauseCampaign 5. COGS calculé par produit avec formule shipping par pays (config dans Firestore, pas hardcodé) 6. Frais Stripe = 1.5% + 0.25€ par order, frais Shopify = 0.6% du revenue (configurable) ## Modules à livrer Sidebar groupée par intention : Pilotage - /daily — KPIs du jour vs J-1, top 15 produits, top 10 campaigns toutes régies, 5 dernières commandes avec profit ligne par ligne - /journal — Logger des events business + analyse before/after auto sur conversion rate + AOV (fenêtre 7/14/30j) Action - /ads — "Coupe-feu" : toutes les campagnes triées par perte cumulée (3/7/15/30j), bouton Pause par régie - /media-buying — Reporting weekly/monthly + leaderboard top ROAS / worst loss + pivot mois × campagne 12 mois glissants - /kill-list — Verdict auto par campaign + adset (kill / critical / watch / ok) avec seuils ajustables (minSpend, minRoas) et "wasted spend" Produits - /new-collection — Tracking spécifique des produits sortis < 60j - /products — Rentabilité unitaire de tout le catalogue avec COGS, shipping, profit, marge Finance - /reports — P&L daily / weekly / monthly avec ad spend décomposé par régie (FB / Google / MS / Pinterest), bROAS, MER, marge brute, profit net Email - /klaviyo — Campaigns + flows par mois avec open rate, click rate, revenue Clients - /feedback — Aggregateur feedback post-achat (fit, comfort, quality, visual) avec health score 0-100 par produit Veille - /snooper — Detection nouveaux produits / ruptures / retours stock / changements prix sur concurrents Shopify, polling toutes les 5 min en service séparé, notif Telegram ## Composants partagés - PageHeader (titre, sous-titre, slot actions) - KpiCard (label, valeur, delta vs J-1, mini sparkline optionnel) - RefreshIndicator (point vert qui pulse pendant le refresh background) - PeriodSelector (boutons 7/30/90j) - DataTable (tri par colonne, pagination simple) - Chart wrapper Recharts avec theming maison ## Design - Dark theme, accent bordeaux #6b1120 (change-le pour la marque de ton pote) - Sidebar 224px fixe à gauche, contenu fluide à droite - Pas d'icon library : SVG inline dans la sidebar - Tout en français (UI labels, dates, devises) - Devise = € par défaut, formats fr-FR (1 234,56 €) - Timezone Europe/Paris pour les bornes de jour - Police système, pas de Google Fonts ## Anti-patterns à éviter - NE PAS faire du multi-tenant — c'est un dashboard solo - NE PAS mettre de loader spinner au-delà du 1er chargement (stale-while-revalidate gère ça) - NE PAS stocker de credentials en dur — tout en .env.local - NE PAS appeler les API en client-side direct — toujours via /api/* (CORS, secrets, cache) - NE PAS agréger les régies "intelligemment" sans les exposer séparément aussi (toujours pouvoir voir Meta vs Google vs MS séparément) ## Order de livraison 1. Setup Next.js 16 + Tailwind + Sidebar + layout 2. /daily avec Shopify + Meta seulement (MVP minimum) 3. /products + COGS engine 4. /ads + /kill-list avec Meta 5. Brancher Google Ads, MS Ads, Pinterest derrière la même interface AdsPlatform 6. /media-buying, /reports (P&L) 7. /klaviyo, /journal, /feedback 8. /snooper (le plus complexe, à faire en dernier ou en service séparé) Pose-moi les questions sur les credentials manquants AVANT de commencer, pas pendant. Commence par scaffolder le projet et me confirmer la liste des intégrations qu'on a en main.