--- title: Arhitectura Sistemului description: Analiză aprofundată a arhitecturii VertiWiki fără backend, a etapelor ciclului de viață și a topologiei C4. tags: [vertiwiki, arhitectura, diagrama-c4, sistem, interne, romana] --- # Arhitectura Sistemului > For the complete documentation index and agent navigation, see [llms.txt](/llms.txt). VertiWiki reprezintă o schimbare fundamentală față de generatoarele tradiționale de site-uri statice (SSG) și sistemele de gestiune a conținutului (CMS). În loc să compileze documentele Markdown în sute de fișiere HTML individuale pe un server de build, VertiWiki funcționează ca o aplicație SPA autonomă într-un singur fișier, gestionând rutarea, preluarea, parsarea, igienizarea și randarea direct în browserul clientului. --- ## 🏛️ Arhitectura Containerelor C4 Diagrama de mai jos ilustrează contextul de sistem și containerele de runtime ale VertiWiki: ```mermaid C4Container title Diagrama de Containere pentru Runtime-ul Client VertiWiki Person(user, "Cititor Uman / Agent AI", "Citește documentația și caută conținut.") Container_Boundary(c1, "Runtime Client în Browser") { Component(router, "Router", "TypeScript (src/core/router.ts)", "Interceptează rutele hash, rezolvă localele, normalizează căile.") Component(pipeline, "Pipeline", "TypeScript (src/core/pipeline.ts)", "Execută middleware-urile de plugin beforeParse, afterParse și afterRender.") Component(parser, "MarkdownParser", "TypeScript (src/core/parser.ts)", "Extrage YAML frontmatter, AST marked și igienizare DOMPurify.") Component(layout, "LayoutManager", "TypeScript (src/ui/layout.ts)", "Construiește structura DOM, cuprinsul TOC, bara laterală și modurile de layout.") Component(theme, "ThemeManager", "TypeScript (src/ui/theme.ts)", "Rezolvă preseturile de teme și aplică variabilele CSS custom.") Component(search, "SearchEngine", "TypeScript (src/plugins/search.ts)", "Construiește indexul MiniSearch în memorie pentru căutare full-text.") } Container_Boundary(c2, "Stocare Statică / CDN Edge") { ComponentDb(markdown, "Fișiere Markdown", "Fișiere standard .md", "Sursa documentației și navigation.md.") ComponentDb(config, "config.json", "Configurație JSON", "Setări runtime și definiții de teme.") ComponentDb(assets, "Resurse Statice", "SVG/PNG/CSS", "Logouri, favicon și fișiere modulare de temă.") } Rel(user, router, "Navighează la URL", "HTTPS / Rută Hash") Rel(router, markdown, "Descarcă documentul", "HTTP GET (API fetch)") Rel(router, config, "Încarcă setările", "HTTP GET (API fetch)") Rel(router, pipeline, "Trimite textul Markdown brut", "Apel Intern Pipeline") Rel(pipeline, parser, "Apelează marked & DOMPurify", "AST Sincron") Rel(pipeline, layout, "Montează codul HTML curat", "Injectare în DOM") Rel(layout, theme, "Aplică token-urile de design", "Variabile CSS") Rel(pipeline, search, "Trimite conținutul paginii", "Indexare MiniSearch") ``` --- ## 🔄 Ciclul de Viață Zero-Backend Ciclul de viață al execuției se desfășoară în șase etape bine delimitate: ```mermaid stateDiagram-v2 [*] --> Bootstrap: Încărcare fișier unic HTML Bootstrap --> ConfigLoading: Descărcare config.json ConfigLoading --> ThemeInitialization: Aplicare preset temă ThemeInitialization --> NavigationParsing: Descărcare & parsare navigation.md NavigationParsing --> RouteDispatch: Evaluare window.location.hash RouteDispatch --> MarkdownFetch: Descărcare fișier .md cerut MarkdownFetch --> PipelineExecution: Rulare hook-uri beforeParse PipelineExecution --> DOMPurifySanitization: Parsare Markdown & igienizare HTML DOMPurifySanitization --> DOMMounting: Montare HTML în #verti-app DOMMounting --> PostRenderHooks: Rulare afterRender (Prism, KaTeX, Mermaid) PostRenderHooks --> Idle: În așteptarea interacțiunii utilizatorului Idle --> RouteDispatch: Eveniment hashchange declanșat ``` ### 1. Inițializarea Motorului (Bootstrap) Când `index.html` se încarcă, ecranul schelet critic (`.verti-loading-shell`) apare instantaneu, sincronizat cu tema sistemului de operare (`prefers-color-scheme`). Acest lucru oferă un First Contentful Paint (FCP) de 0 ms și elimină schimbarea cumulativă de layout (CLS). ### 2. Configurare & Teme Funcția `loadConfig()` descarcă `config.json`. Dacă sunt specificate teme externe (`themes/*.json`), acestea sunt preluate asincron. `ThemeManager` calculează proprietățile personalizate CSS și le aplică pe `:root`. ### 3. Rezolvare Paralelă a Meniului & Rutei `Router` inspectează `window.location.hash`. Concomitent, prin `Promise.all`, sunt descărcate: 1. `navigation.md` (sau versiunea localizată `ro/navigation.md`). 2. Documentul Markdown inițial (ex: `index.md`). ### 4. Execuția Pipeline-ului & Middleware Textul brut Markdown este prelucrat de `Pipeline`: - **`beforeParse`**: Plugin-urile transformă sintaxa specială (wikilinks `[[țintă]]`, containere `::: tabs`, alerte `> [!NOTE]`). - **Parsare**: `marked` compilează textul Markdown în HTML. - **Igienizare**: `DOMPurify` elimină tagurile malițioase, permițând nodurile SVG necesare diagramelor Mermaid și MathML pentru KaTeX. - **`afterParse`**: Manipularea arborelui HTML înainte de injectare. ### 5. Montare în DOM `LayoutManager` montează articolul în `.verti-article`. Cuprinsul (`TocManager`), breadcrumbs și paginarea anterioară/următoare sunt calculate și afișate. ### 6. Hidratare Post-Randare - `mermaid.run()` randează diagramele SVG pe loc. - `Prism.highlightAllUnder()` aplică evidențierea sintaxei. - `renderMathInElement()` formatează ecuațiile LaTeX. - `SearchEngine` indexează asincron conținutul paginii. --- ## 💾 Modelul de Memorie & Cache Client Pentru a garanta tranziții instantanee la navigare, VertiWiki utilizează un cache în memorie (`Map`) în `src/main.ts`: - Documentele Markdown vizitate sunt salvate în memorie. - Structurile de navigare sunt reținute. - La navigarea între pagini vizitate anterior, cererile de rețea sunt complet evitate (latență 0 ms). - Butoanele Înapoi/Înainte din browser funcționează instantaneu. --- ## ⚖️ Invarianți de Arhitectură & Raționament Tehnic VertiWiki a fost proiectat pe baza unor invarianți arhitecturali stricți, având ca scop eliminarea complexității operaționale din platformele tradiționale de documentație: ### 1. Invariantul Zero-Backend Nu este necesar niciun mediu de execuție pe server (Node.js, Python, PHP) și nicio bază de date (PostgreSQL, MySQL, SQLite) în producție: - **Zero Infrastructură de Server**: Aplicația este găzduită ca fișiere pur statice (HTML, JS, CSS și Markdown). - **Suprafață Redusă de Atac**: Eliminarea serverelor de aplicație și a bazelor de date elimină vulnerabilitățile de tip SQL injection, execuția de cod de la distanță pe server și mentenanța patch-urilor de securitate. - **Recuperare Simplă în caz de Dezastru**: Conținutul documentației constă în fișiere Markdown stocate direct în Git; nu sunt necesare proceduri de backup sau restaurare a bazelor de date. ### 2. Invariantul Zero-Build la Editare Spre deosebire de generatoarele tradiționale de site-uri statice (SSG) precum Docusaurus, VitePress sau Hugo, VertiWiki nu necesită compilare sau pași de build în CI la modificarea documentelor: - **Feedback Imediat pentru Autori**: Crearea sau actualizarea unei pagini constă exclusiv în modificarea fișierelor `.md`. O simplă reîncărcare a paginii în browser reflectă instantaneu modificările. - **Eliminarea Blocajelor din CI**: Pe măsură ce numărul de pagini crește, timpii de compilare SSG cresc semnificativ. În VertiWiki, compilarea se realizează o singură dată pentru motorul în sine, iar scalarea conținutului este decuplată de timpii de deployment. ### 3. Invariantul de Securitate și Sanitizare Client-Side Deoarece parsarea documentelor are loc în browserul utilizatorului, securitatea este garantată printr-un flux strict de igienizare: - **Filtrare DOMPurify**: Tot conținutul HTML rezultat din Markdown este trecut prin DOMPurify, neutralizând potențialele atacuri XSS provenite din contribuții sau fișiere externe. - **Păstrare Selectivă**: Doar elementele grafice sigure (containere SVG pentru diagrame Mermaid și MathML pentru formule KaTeX) sunt permise dincolo de bariera de sanitizare. ### 4. Invariantul de Portabilitate Universală Pachetul este independent de mediul de găzduire: - **Portabilitate de Rută**: Funcționează identic la rădăcina unui domeniu (`/`), într-un subdirector (`/docs/`) sau pe CDN-uri edge (Cloudflare Pages, Vercel, GitHub Pages, AWS S3). - **Funcționare Offline**: Poate fi rulat local și complet offline prin orice server web static (`npx serve`, `python -m http.server`) fără conexiune la internet. ### 5. Compromisuri Arhitecturale & Atenuări Integrate | Provocare | Compromis Tehnic | Soluție Integrată | | :--- | :--- | :--- | | **Indexare SEO & Roboți** | Aplicațiile client-side SPA nu servesc HTML pre-randat în mod implicit. | VertiWiki generează o structură semantică `