Architecture et inventaire du code existant

Archive de conception. Cette page raconte ce qui etait vise le jour ou elle a ete ecrite, pas l'etat du code aujourd'hui. Ce qui a ete livre depuis est recense dans le README.

← retour au README

2. Architecture cible : panneaux du Workspace

┌──────────────────────────────────────────────────────────────────┐
│ Top du shell (existant) : org / store / iRen                     │
├──────────┬─────────────────────────────────────┬─────────────────┤
│          │ ┌─────────────────────────────────┐ │                 │
│ Left     │ │ Top header du main center       │ │   Right panel   │
│ panel    │ │ • storefront URL bar            │ │                 │
│          │ │ • action buttons                │ │   Chat @Atlas    │
│ Kernel   │ │ • view toggle: Preview/Worktree │ │   (déjà shipped)│
│          │ │ • version timeline badge        │ │                 │
│ • Tasks  │ ├─────────────────────────────────┤ │                 │
│ • Files  │ │ Center main (switchable)        │ │                 │
│ • Branch │ │ ┌───────────────────────────┐   │ │                 │
│ • Reports│ │ │ Live preview (iframe)     │   │ │                 │
│ • Notes  │ │ │ OR                        │   │ │                 │
│          │ │ │ Worktree (file tree+IDE)  │   │ │                 │
│          │ │ └───────────────────────────┘   │ │                 │
│          │ ├─────────────────────────────────┤ │                 │
│          │ │ Bottom footer du main center    │ │                 │
│          │ │ • Terminal / Console            │ │                 │
│          │ └─────────────────────────────────┘ │                 │
└──────────┴─────────────────────────────────────┴─────────────────┘

Responsabilités par panneau

Le Kernel (concept central)

Système collaboratif par boutique (interne, distinct des pages publiques /changelog + /roadmap de la plateforme) qui héberge :

Sandbox uniquement (jamais d'écriture directe sur le live)

Toute modification part dans un thème Shopify draft (sandbox). L'utilisateur ou @Atlas travaille librement. Publier = clic explicite, via la mutation GraphQL themePublish(id). Snapshot du live avant publication → rollback en un clic.

Timeline des versions (badge dans l'en-tête de la zone centrale)

Pattern v0.dev / chat-as-branch :

• Chaque conversation = une branche de thème créée automatiquement
• Chaque message qui modifie le code = un snapshot (à la manière d'un commit)
• Le badge de version de l'en-tête est une timeline navigable
  • Clic sur une version → restauration (les fichiers reprennent cet état en local)
  • Fork possible depuis n'importe quelle version → nouvelle conversation
  • Diff entre 2 versions visible
  • « Publier » = marquer une version comme live (push vers le draft Shopify connecté à la boutique)

Le badge de version n'est pas cosmétique. C'est la traduction, dans l'UI, du système de sandbox.

3. Inventaire du code existant

Zone 1 — Workspace actuel ✅ réutilisable avec adaptations

Fichiers :

• src/app/(dashboard)/[orgSlug]/[storeSlug]/workspace/page.tsx:1-16 : enveloppe PaidGate
• src/app/(dashboard)/[orgSlug]/[storeSlug]/workspace/_components/workspace-content.tsx:1-357 : éditeur Liquid en trois volets (sélecteur de thème | arbre des assets | CodeMirror)

Fonctionnalités actives :

• Disposition en trois volets, récupération du thème en temps réel, regroupement des assets par dossier
• Édition Liquid/JSON/CSS/JS/SVG/TXT/MD
• Enregistrement via PUT /api/stores/[storeId]/theme-assets avec validation
• Warning visuel sur les thèmes LIVE

Action V2 :

• Abstraire WorkspaceContent en <ResourceEditor> générique avec props resourceType, fetchFn, saveFn, contentTransformer : permet la réutilisation pour les pages, blogs, articles, collections.
• Migrer de CodeMirror vers Monaco (cf. Stack Bloc 3).
• Garder : états de chargement, gestion des erreurs, conteneur à trois volets.

Zone 2 — Workflow legacy ⚠️ tri à faire

Fichier route : src/app/(dashboard)/[orgSlug]/[storeSlug]/workflow/page.tsx (shell vide → AgentsMode()).

Nœuds existants (src/features/ai/preview/) :

Patterns workflow (src/components/patterns/workflow/ui/preview/blocks/) : viewer, shopify, vercel, web-preview : vérifier l'usage actuel, archiver ce qui n'est plus utilisé.

Action V2 :

• Supprimer la page de route /workflow (shell vide qui ne sert plus).
• Consolider les deux planificateurs en un seul <TaskPlanner>.
• Préserver les composants de nœuds qui survivront comme briques UI (chatbot, atlas-kernel, orchestrator, subagents-team, codebase-editor).
• Migrer le canvas legacy vers le nouveau modèle de file de tâches (liste à la Linear au lieu d'un graphe de nœuds).

Zone 3 — Shell PlatformShell ✅ fondationnel

Fichiers : src/components/shells/platform/{platform-shell, platform-center, platform-left, platform-right, platform-top}.tsx + src/components/shells/app-shell/shell-client.tsx.

Slots disponibles (PlatformShell props) :

type PlatformShellProps = {
  top, left, leftTitle, leftCount, leftFooter, leftFooterAction,
  right, rightTitle, rightFooter,
  bottom, consoleLogs,
  centerHeader, centerActions,
  settingsDropdown, versionSelector,  // ← cosmétique aujourd'hui
  children,
}

Câblage observé :

• Right (310px) : AiChat rendu ici
• Center : main + centerHeader (top) + bottom ou consoleLogs (tiroir du bas)
• versionSelector slot : déjà défini, non utilisé, opportunité directe pour la timeline V2

Action V2 :

• Brancher le versionSelector slot à un <VersionTimeline> réel (cf. Modèle de données + Stack Bloc 1)
• Étendre le rendu de consoleLogs avec un sélecteur d'onglets (Console | Activity | Metrics)
• Découper shell-client.tsx (> 600 lignes) en sous-composants, pour la clarté
• Garder la souplesse des panneaux gauche et droit masquables (déjà excellente)

Zone 4 — Chat @Atlas ✅ prêt à étendre

Fichier principal : src/features/ai/chat/runtime/ai-chat.tsx

Stack actuelle :

• useChat (AI SDK)
• DefaultChatTransport
• VoiceProvider (Hume)
• <Message>, <MessageResponse>, <PromptInput>, <AttachmentsBar>, <VoiceToolbar>

Agents branchés (depuis src/features/ai/agents/) : @Atlas (orchestrateur) + @Maya / @Marco / @Otis / @Faye / @Sam (5 spécialistes). Chaque agent expose tools[], connectors[], permissions[].

Action V2 :

• Garder l'API actuelle : la surface de chat ne bouge pas
• Étendre les outils Shopify (cf. Zone 5 + section « Outils à encapsuler »)
• Brancher le LiquidEditor comme outil appelable par les agents (au lieu d'être consommé directement par WorkspaceContent → réduit le couplage)

Zone 5 — Outils Shopify / MCP ⚠️ incomplet : bloquant

Fichier registre : src/app/api/mcp/[storeId]/register-tools.ts (cette page citait src/features/shopify/mcp/tools.ts, un fichier qui n'a jamais existe : ce repertoire ne contient qu'un sous-repertoire shopify/ et aucun tools.ts).

Outils actuels : 18 outils, 0 ressource, mesuré le 2026-09-18 par grep -c "server.registerTool(" src/app/api/mcp/[storeId]/register-tools.ts et tenu par l'affirmation mcp.tools de scripts/check-doc-claims.mjs (listProducts, getProduct, listThemes, getTheme, getShopInfo, listPages, listOrders, runAudit, runShopifyQL, introspectSchema, getStoreContext, shopifyAdminGraphQL, getStudioSection, searchDocs, getDoc, searchOperatorDocs, getOperatorDoc, getStoreIntelligence). Les « 16 tools + 3 resources (boostecom_generate, boostecom_get_prompt, boostecom_route) » ecrits ici auparavant ne correspondent a aucun symbole du depot : aucun registerResource n'existe, et aucun de ces trois noms n'apparait dans src/.

Endpoints Shopify confirmés non couverts (manque critique) :

• ❌ Blogs / Articles
• ❌ Collections
• ❌ Menus de navigation
• ❌ Clients
• ❌ Marketing (réductions, automatisations, campagnes)
• ❌ Apps installées
• ❌ Réglages (langues, devises, taxes, livraison)

Confirmés couverts ou partiels (lu dans register-tools.ts le 2026-09-18) : produits (listProducts, getProduct), thèmes (listThemes, getTheme, plus /api/stores/[storeId]/theme-assets), pages (listPages), commandes (listOrders), analytics (runShopifyQL), et le relais generique shopifyAdminGraphQL en lecture seule. Pages et Analytics figuraient dans la liste des manques ci-dessus alors qu'un outil les servait deja.

Pattern existant : schéma zod + handler + platformFetch() avec un timeout de 30 s. Solide.

Action V2 :

• Lot 1 = encapsulation exhaustive de Shopify Admin GraphQL : tous les endpoints ci-dessus, pour que @Atlas ne dise jamais « je ne sais pas »

Zone 6 — Tracking / Scan / Setup ✅ patterns réutilisables

Fichiers : src/app/(minimal)/scan/tracking/, src/features/ tracking/scan/orchestrator.ts:1-80+

Pipeline en 7 phases observé : staticAnalysis → dynamicAnalysis → apiVerification → shopifyInspection → validateDataLayerSchema → calculateScore → analyzeRootCauses

Composants UI réutilisables :

Action V2 :

• Réutiliser ScanApp + ReportViewer + ActivityFeed + ActionPanel pour les nouveaux types de scans (audit SEO, concurrents, perf, sécurité)
• Documenter les limites du pattern orchestrateur (nombre maximal de phases, perf sous N contrôles parallèles)

Suivant : stack.md