---
title: Execution Workflows & Sequence Traces
description: Step-by-step sequence diagrams tracing routing, resource fetching, pipeline middleware, and search indexing.
tags: [vertiwiki, workflows, sequence-diagram, routing, pipeline, execution]
---

# Execution Workflows

> For the complete documentation index and agent navigation, see [llms.txt](/llms.txt).

This document traces the internal execution paths of VertiWiki as Mermaid `sequenceDiagram`s, mapped directly to the underlying TypeScript modules.

---

## 🌊 Flow 1: Document Request & Render Pipeline

This sequence details how a hash route change (`window.location.hash = '#/concepts/architecture.md'`) is translated into a rendered article on screen:

```mermaid
sequenceDiagram
    autonumber
    actor User as User / Browser
    participant Router as Router (src/core/router.ts)
    participant Fetcher as Fetch Engine (src/main.ts)
    participant Cache as Memory Cache (Map)
    participant Pipeline as Pipeline (src/core/pipeline.ts)
    participant Parser as MarkdownParser (src/core/parser.ts)
    participant DOMPurify as DOMPurify Sanitizer
    participant Layout as LayoutManager (src/ui/layout.ts)
    participant Plugins as Post-Render Plugins

    User->>Router: Navigate to #/concepts/architecture.md
    Router->>Router: parseHash(window.location.hash)
    Router->>Fetcher: loadPage('concepts/architecture.md')
    
    alt Content in Memory Cache
        Fetcher->>Cache: get('concepts/architecture.md')
        Cache-->>Fetcher: Return raw Markdown
    else Content Not Cached
        Fetcher->>User: HTTP GET /docs/concepts/architecture.md
        User-->>Fetcher: 200 OK (Markdown text)
        Fetcher->>Cache: set('concepts/architecture.md', rawMarkdown)
    end

    Fetcher->>Pipeline: runBeforeParse(rawMarkdown, context)
    Pipeline-->>Fetcher: Transformed Markdown (wikilinks, tabs)

    Fetcher->>Parser: parse(transformedMarkdown)
    Parser->>Parser: Extract YAML frontmatter & autoCloseFences
    Parser->>Parser: marked.parse(body)
    Parser->>DOMPurify: sanitize(html, allowedTags)
    DOMPurify-->>Parser: Clean, safe HTML string
    Parser-->>Fetcher: ParsedMarkdown object

    Fetcher->>Pipeline: runAfterParse(cleanHtml, context)
    Pipeline-->>Fetcher: Final HTML string

    Fetcher->>Layout: renderArticle(finalHtml, frontmatter)
    Layout->>Layout: Mount into DOM (.verti-article)
    Layout->>Layout: Generate TOC & update active navigation link

    Fetcher->>Pipeline: runAfterRender(context)
    Pipeline->>Plugins: Execute Prism, Mermaid, KaTeX
    Plugins-->>User: Fully rendered interactive article
```

---

## 🌐 Flow 2: Multi-Language Switcher & Prefix Resolution

When a user switches from English to Romanian or French, VertiWiki recalculates the active path without reloading the page:

```mermaid
sequenceDiagram
    autonumber
    actor User as Reader
    participant LangChooser as LanguageChooser (src/ui/language-chooser.ts)
    participant Router as Router (src/core/router.ts)
    participant NavManager as NavigationTree (src/core/crawl-tree.ts)
    participant Fetcher as Fetch Engine (src/main.ts)

    User->>LangChooser: Select "Română (ro)" from dropdown
    LangChooser->>Router: switchLocale('ro')
    Router->>Router: Strip current locale prefix ('')
    Router->>Router: Prepend target prefix ('ro/concepts/architecture.md')
    Router->>Router: Update window.location.hash = '#/ro/concepts/architecture.md'

    Router->>Fetcher: Trigger route reload
    par Concurrently Fetch Localized Assets
        Fetcher->>NavManager: Fetch ro/navigation.md
        NavManager-->>Fetcher: Localized Navigation Tree
    and Fetch Localized Document
        Fetcher->>User: HTTP GET /docs/ro/concepts/architecture.md
        User-->>Fetcher: Localized Markdown text
    end

    Fetcher->>NavManager: Rebuild sidebar with Romanian hierarchy
    Fetcher->>Fetcher: Execute render pipeline on Romanian content
```

---

## 🔍 Flow 3: Full-Text Search Ingestion & Querying

VertiWiki indexes all documents client-side using MiniSearch:

```mermaid
sequenceDiagram
    autonumber
    actor User as Reader
    participant Modal as SearchModal (src/ui/search-modal.ts)
    participant Search as SearchEngine (src/plugins/search.ts)
    participant MiniSearch as MiniSearch Index
    participant Router as Router (src/core/router.ts)

    Note over Search,MiniSearch: Asynchronous Background Crawl at Startup
    Search->>MiniSearch: Add document {id, title, path, content, locale}

    User->>Modal: Press ⌘K or /
    Modal->>Modal: Open modal dialog & focus input
    User->>Modal: Type query "sanitizer"
    
    Modal->>Search: search("sanitizer", {locale: "en"})
    Search->>MiniSearch: Query index with fuzzy matching
    MiniSearch-->>Search: Return scored results
    Search->>Search: Extract highlighted preview snippets
    Search-->>Modal: Array of SearchResultItem
    Modal->>Modal: Render result list

    User->>Modal: Click on result item
    Modal->>Modal: Close modal
    Modal->>Router: navigateTo(result.path)
```

---

## 🔗 Next Steps

- Explore the building blocks in [Core Architecture](core-architecture.md).
- Learn how the UI shell and themes adapt in [UI & Theming Engine](ui-and-theming.md).
- Understand plugin interfaces in [Plugins & Extensions](plugins-and-extensions.md).