--- title: Architecture Système description: Étude approfondie de l'architecture VertiWiki côté client sans backend, du cycle de vie et de la topologie C4. tags: [vertiwiki, architecture, diagramme-c4, conception, interne, francais] --- # Architecture Système > For the complete documentation index and agent navigation, see [llms.txt](/llms.txt). VertiWiki rompt avec les générateurs de sites statiques (SSG) et systèmes de gestion de contenu (CMS) traditionnels. Au lieu de compiler les documents Markdown en centaines de fichiers HTML sur un serveur de build, VertiWiki fonctionne comme une application SPA autonome en un seul fichier, gérant le routage, le chargement, l'analyse, l'assainissement et le rendu directement dans le navigateur du lecteur. --- ## 🏛️ Architecture des Conteneurs C4 Le schéma ci-dessous présente le contexte système et les conteneurs d'exécution de VertiWiki : ```mermaid C4Container title Diagramme de Conteneurs pour le Runtime Client VertiWiki Person(user, "Lecteur Humain / Agent IA", "Consulte la documentation et effectue des recherches.") Container_Boundary(c1, "Runtime Client dans le Navigateur") { Component(router, "Routeur", "TypeScript (src/core/router.ts)", "Intercepte les hashes d'URL, résout les langues, normalise les chemins.") Component(pipeline, "Pipeline", "TypeScript (src/core/pipeline.ts)", "Exécute les middlewares de plugins beforeParse, afterParse et afterRender.") Component(parser, "MarkdownParser", "TypeScript (src/core/parser.ts)", "Analyse le frontmatter YAML, compile l'AST marked et assainit via DOMPurify.") Component(layout, "LayoutManager", "TypeScript (src/ui/layout.ts)", "Construit le DOM, le sommaire (TOC), la barre latérale et les modes de mise en page.") Component(theme, "ThemeManager", "TypeScript (src/ui/theme.ts)", "Applique les presets de thèmes et les variables CSS personnalisées.") Component(search, "SearchEngine", "TypeScript (src/plugins/search.ts)", "Construit l'index MiniSearch en mémoire pour la recherche plein texte.") } Container_Boundary(c2, "Stockage Statique / CDN Edge") { ComponentDb(markdown, "Fichiers Markdown", "Fichiers standard .md", "Source de la documentation et navigation.md.") ComponentDb(config, "config.json", "Configuration JSON", "Paramètres d'exécution et thèmes.") ComponentDb(assets, "Actifs Statiques", "SVG/PNG/CSS", "Logos, favicons et thèmes modulaires.") } Rel(user, router, "Navigue vers l'URL", "HTTPS / Hash Route") Rel(router, markdown, "Récupère le document", "HTTP GET (API fetch)") Rel(router, config, "Charge la configuration", "HTTP GET (API fetch)") Rel(router, pipeline, "Transmet le Markdown brut", "Appel Interne Pipeline") Rel(pipeline, parser, "Invoque marked & DOMPurify", "AST Synchrone") Rel(pipeline, layout, "Monte le HTML assaini", "Injection DOM") Rel(layout, theme, "Applique les jetons graphiques", "Variables CSS") Rel(pipeline, search, "Alimente le texte de page", "Indexation MiniSearch") ``` --- ## 🔄 Cycle de Vie Zéro-Backend L'exécution s'articule autour de six étapes clés : ```mermaid stateDiagram-v2 [*] --> Bootstrap: Chargement du fichier HTML unique Bootstrap --> ConfigLoading: Récupération de config.json ConfigLoading --> ThemeInitialization: Application du thème ThemeInitialization --> NavigationParsing: Récupération et analyse de navigation.md NavigationParsing --> RouteDispatch: Évaluation de window.location.hash RouteDispatch --> MarkdownFetch: Récupération du fichier .md demandé MarkdownFetch --> PipelineExecution: Exécution des hooks beforeParse PipelineExecution --> DOMPurifySanitization: Analyse Markdown et assainissement HTML DOMPurifySanitization --> DOMMounting: Montage HTML dans #verti-app DOMMounting --> PostRenderHooks: Exécution afterRender (Prism, KaTeX, Mermaid) PostRenderHooks --> Idle: En attente d'interaction utilisateur Idle --> RouteDispatch: Événement hashchange déclenché ``` --- ## 💾 Modèle de Mémoire & Cache Client Pour garantir une réactivité instantanée, VertiWiki dispose d'un cache mémoire (`Map`) dans `src/main.ts` : - Les documents Markdown visités sont conservés en mémoire vive. - L'arborescence de navigation est mémorisée. - La réouverture d'une page déjà visitée contourne toute requête réseau (latence 0 ms). - Les boutons Précédent/Suivant du navigateur répondent immédiatement. --- ## ⚖️ Invariants d'Architecture & Justification Technique VertiWiki a été conçu autour d'invariants architecturaux stricts visant à éliminer la complexité opérationnelle des plateformes traditionnelles de documentation : ### 1. L'Invariant Zéro-Backend Aucun runtime côté serveur (Node.js, Python, PHP) ni base de données (PostgreSQL, MySQL, SQLite) n'est requis en production : - **Zéro Infrastructure Serveur** : L'application est servie sous forme de fichiers purement statiques (HTML, JS, CSS et Markdown). - **Surface d'Attaque Réduite** : L'élimination des runtimes applicatifs et des bases de données supprime les risques d'injections SQL, d'exécution de code distant et la gestion des correctifs de serveur. - **Sauvegarde et Restauration Triviales** : La documentation est constituée de fichiers Markdown versionnés dans Git ; aucune procédure de sauvegarde de base de données n'est requise. ### 2. L'Invariant Zéro-Build à l'Édition Contrairement aux générateurs de sites statiques (SSG) classiques tels que Docusaurus, VitePress ou Hugo, VertiWiki n'exige aucune étape de compilation lors des modifications de contenu : - **Cycle de Rédaction Instantané** : Rédiger ou modifier une page consiste simplement à enregistrer un fichier `.md`. Un simple rechargement du navigateur affiche immédiatement les mises à jour. - **Élimination des Verrous CI** : Lorsque les dépôts contiennent des centaines de pages, les temps de compilation des SSG augmentent considérablement. Avec VertiWiki, le moteur n'est compilé qu'une seule fois ; l'ajout de contenu ne ralentit pas les déploiements. ### 3. Invariant de Sécurité et de Nettoyage Côté Client Le traitement du Markdown s'effectuant dans le navigateur du client, la sécurité repose sur un pipeline de désinfection rigoureux : - **Filtrage DOMPurify** : Tout HTML généré à partir de Markdown est désinfecté par DOMPurify, neutralisant les vecteurs d'attaque XSS issus de contributions externes. - **Préservation Sélective** : Seuls les éléments graphiques sûrs (conteneurs SVG pour diagrammes Mermaid et MathML pour KaTeX) franchissent la barrière de désinfection. ### 4. Invariant de Portabilité Universelle L'ensemble applicatif est indépendant du système d'hébergement : - **Portabilité des Chemins** : Fonctionne de manière identique à la racine d'un domaine (`/`), dans un sous-dossier (`/docs/`) ou sur des réseaux edge CDN (Cloudflare Pages, Vercel, GitHub Pages, AWS S3). - **Fonctionnement Hors Ligne** : Utilisable hors ligne via n'importe quel serveur web statique (`npx serve`, `python -m http.server`) sans accès internet. ### 5. Compromis d'Architecture & Atténuations | Enjeu | Compromis Technique | Atténuation Intégrée | | :--- | :--- | :--- | | **Exploration SEO & Robots** | Les SPA côté client ne fournissent pas de HTML pré-rendu par défaut. | VertiWiki génère un arbre sémantique `