Skip to content

3.1 Application Bootstrap and Orchestration

Jump to bottom
coding man edited this page Nov 4, 2026 · 1 revision

Application Bootstrap and Orchestration

Relevant source files

The following files were used as context for generating this wiki page:

This page details the application bootstrap and user interface orchestration logic centered around src/main.js, along with its supporting modules src/ui/search.js and src/ui/panels.js. It covers DOM initialization, component wiring, the asynchronous runSearch execution pipeline, panel state management, error handling, and testing hooks.

1. Application Bootstrap and DOM Initialization

The application initializes by importing global styling (src/styles/tokens.css, src/styles/base.css, src/styles/components.css) and core libraries src/main.js:3-5.

During module evaluation, src/main.js queries all DOM elements possessing the [data-panel] attribute, constructs a panels lookup map, and prepares each panel shell by injecting skeleton loading templates src/main.js:55-58. Theme initialization is bound to the theme toggle element via initTheme($('theme-toggle')) src/main.js:75. The pLDDT color legend is dynamically populated using PLDDT_BANDS from src/ui/palette.js src/main.js:46, src/main.js:76-85.

The search subsystem is initialized using initSearch from src/ui/search.js, connecting form submission, input validation, example chips (BRCA1, TP53, CFTR, MLH1), and recent search persistence src/main.js:87-94, src/ui/search.js:6, src/ui/search.js:56-91.

graph TD
    subgraph "DOM Initialization Space"
        HTML["src/index.html"] --> Panels["[data-panel] Elements"]
        HTML --> Toggle["#theme-toggle"]
        HTML --> SearchForm["#search-form & Inputs"]
    end

    subgraph "Bootstrap Entity Space"
        Panels --> Prep["preparepanel src/ui/panels.js:6"]
        Toggle --> InitTh["initTheme src/ui/theme.js"]
        SearchForm --> InitS["initSearch src/ui/search.js:56"]
        InitS --> RegSearch["runSearch src/main.js:100"]
    end

    Prep --> PanelStates["Panel State Machine"]
    InitS --> ExChips["EXAMPLE_GENES src/ui/search.js:6"]
    RegSearch --> Pipe["loadGene src/core/pipeline.js:19"]

    classDef default fill:#fff,stroke:#000,stroke-width:1px;
    class HTML,Panels,Toggle,SearchForm,Prep,InitTh,InitS,RegSearch,PanelStates,ExChips,Pipe default;
Loading

Sources: src/main.js:1-94, src/ui/search.js:1-91, src/ui/panels.js:1-16

2. Search and Rendering Orchestration (runSearch)

The core user workflow is driven by runSearch(symbol, { refresh }) src/main.js:100. This asynchronous function manages request cancellation, progress reporting, cache refreshing, and error fallbacks.

When a search is initiated:

  1. Any active request controller (app.controller) is aborted using AbortController to prevent race conditions src/main.js:101-103.
  2. The searched symbol is recorded via addRecent(symbol) and the recent searches list is refreshed src/main.js:105-106, src/ui/search.js:32-38.
  3. If refresh is true and the gene is already on screen, a non-destructive view retention mode (keepView) is enabled, showing an informational banner while maintaining the current DOM state src/main.js:109-110. Otherwise, showLoading(symbol) hides the welcome screen, reveals the results container, resets selections, and sets all panels to skeleton loading states src/main.js:111, src/main.js:149-157.
  4. loadGene(symbol) is invoked with progress callbacks updating the banner text as ClinVar records download (Loading ClinVar: X / Y) src/main.js:113-125.
  5. Upon successful retrieval, recordGene(result, symbol) updates the local library, renderResult(result) populates all visualization panels, and renderLibrary() updates the home dashboard src/main.js:128-130.

If an error occurs during retrieval (and is not an aborted request), runSearch handles keep-view failure recovery or displays a fatal error state via showFatal(symbol, err) src/main.js:131-145.

sequenceDiagram
    participant User as "User Input"
    participant Search as "initSearch src/ui/search.js:56"
    participant Main as "runSearch src/main.js:100"
    participant Pipe as "loadGene src/core/pipeline.js"
    participant Panels as "setPanelState src/ui/panels.js:18"

    User->>Search: "Submit Gene Symbol (e.g. BRCA1)"
    Search->>Main: "onSearch(symbol)"
    Main->>Main: "app.controller.abort()"
    Main->>Main: "showLoading(symbol)"
    Main->>Panels: "Set State to 'loading'"
    Main->>Pipe: "loadGene(symbol, { signal, refresh, onProgress })"
    Pipe-->>Main: "GeneResult Object"
    Main->>Main: "recordGene(result, symbol)"
    Main->>Main: "renderResult(result)"
    Main->>Panels: "Set State to 'ready'"
Loading

Sources: src/main.js:96-167, src/ui/search.js:56-91

3. Panel Lifecycle and States

Every application panel operates under a strict state model managed by src/ui/panels.js. Panels initialize with skeleton shimmers and message containers via preparePanel(panel) src/ui/panels.js:6-15.

The function setPanelState(panel, state, { message, onRetry }) controls the visibility of three discrete internal partitions based on the state string (loading, empty, error, ready) src/ui/panels.js:18-37:

  • loading: Unhides the .panel-skeleton (shimmer animation), hides messages and content, sets aria-busy="true" src/ui/panels.js:22-26.
  • empty / error: Unhides the .panel-message element, populates descriptive text, and appends a Retry action button if an onRetry callback is supplied src/ui/panels.js:23, src/ui/panels.js:27-36.
  • ready: Unhides the .panel-content container holding the fully rendered visualization component src/ui/panels.js:24.

Sources: src/ui/panels.js:1-37

4. Home Page, Folders, and Library Integration

When no gene is loaded, showHome() halts active controllers, hides the results view, reveals the welcome dashboard, and updates the document title src/main.js:159-167.

In desktop (Electron) mode, layout state is managed through currentLayout(symbols) which prunes unreferenced genes using pruneGenes() and synchronizes changes via saveFolders() src/main.js:173-178, src/core/folders.js:40. The folderHandlers() closure provides navigation, folder creation, deletion, renaming, and drag-and-drop gene/folder relocation capabilities src/main.js:189-210.

Sources: src/main.js:159-210, src/core/folders.js:35-43

5. Testing Hooks (__vsTest)

To facilitate automated end-to-end testing via Playwright, src/main.js exposes internal states and operational hooks globally on window.__vsTest when running in test environments. This allows test suites to inspect application controllers, trigger searches programmatically, evaluate panel states, and assert cache or selection synchronization without relying on DOM scraping alone.

Sources: src/main.js:1-619

Content imported from DeepWiki.

VariantScope Wiki

Clone this wiki locally