Skip to content

6.3 Documentation and Screenshots

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

Documentation and Screenshots

Relevant source files

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

Purpose and Scope

This page covers the technical documentation assets stored in the docs/ directory of VariantScope, including structural blueprints (docs/ARCHITECTURE.md), release records (CHANGELOG.md), publishing notes, and the screenshot gallery (docs/screenshots). It details the contents of these documents, the architectural decisions they capture, and the automation mechanisms used to regenerate visual assets for releases and documentation.

Sources: docs/ARCHITECTURE.md:1-39, CHANGELOG.md:1-5

1. Core Documentation Files in docs/

VariantScope maintains its system documentation alongside the codebase in the docs/ folder docs/ARCHITECTURE.md:37-38. The primary documentation artifacts include:

  • docs/ARCHITECTURE.md: Explains the repository's big-idea philosophy (one codebase shipping as Desktop Electron app, GitHub Pages web version, and local dev server), the directory layout (src/core, src/ui, electron/), the gene search pipeline execution, networking abstractions via src/core/http.js, persistence rules, and desktop security sandboxing docs/ARCHITECTURE.md:5-112.
  • CHANGELOG.md: Tracks all notable changes following a reverse-chronological order, categorized by version (e.g., [0.3.0], [0.2.0], [0.1.0]) detailing new features like hierarchical folders on the desktop app, persistent home page libraries, caching schemas, security configurations, and known limitations CHANGELOG.md:1-65.
  • PUBLISHING.md: Documents release procedures, electron-builder configurations, binary packaging, and GitHub Actions publishing workflows.
graph TD
  DocFolder["docs/"] --> Arch["ARCHITECTURE.md"]
  DocFolder --> Change["CHANGELOG.md"]
  DocFolder --> Publish["PUBLISHING.md"]
  DocFolder --> Gallery["docs/screenshots/"]
  
  Arch --> CoreSpace["src/core/"]
  Arch --> ElectronSpace["electron/"]
  Gallery --> ScreenDesktop["electron-BRCA1.png"]
  Gallery --> ScreenMobile["BRCA1-mobile.png"]
  Gallery --> ScreenDark["TP53-desktop-dark.png"]

  subgraph "Code Entity Space"
    CoreSpace
    ElectronSpace
  end

  subgraph "Natural Language Space"
    DocFolder
    Arch
    Change
    Publish
    Gallery
  end
Loading

Diagram 1: Mapping Natural Language Documentation (docs/) to Code Entity Space.

Sources: docs/ARCHITECTURE.md:1-39, CHANGELOG.md:1-64

2. Architectural Blueprint (docs/ARCHITECTURE.md)

The architecture guide serves as the canonical reference for developers and automated agents to understand how VariantScope bridges multiple runtime environments.

Multi-Target Deployment Strategy

As outlined in docs/ARCHITECTURE.md, VariantScope ships three ways from a single source tree:

  1. Desktop App (Electron): Renders inside a locked-down window where network calls execute in the trusted main process (electron/fetcher.js) docs/ARCHITECTURE.md:9-11, docs/ARCHITECTURE.md:67-69.
  2. Web Version (GitHub Pages): Runs in standard browser tabs executing direct fetch calls docs/ARCHITECTURE.md:10, docs/ARCHITECTURE.md:12, docs/ARCHITECTURE.md:69-70.
  3. Local Development (npm run dev): Serves the identical UI bundle via a local Vite dev server docs/ARCHITECTURE.md:13.

Regardless of the target, UI code invokes a unified network function, getJson(url, options), defined in src/core/http.js, which delegates appropriately based on environment checks docs/ARCHITECTURE.md:15.

Pipeline and Network Abstraction

When a user queries a gene (e.g., loadGene in src/core/pipeline.js), the architecture document details the multi-source aggregation flow:

Sources: docs/ARCHITECTURE.md:5-73

3. Screenshot Gallery and Visual Assets

The repository includes a curated set of reference screenshots under docs/screenshots to verify rendering correctness across form factors, themes, and execution modes:

Screenshot File Target / Context Key Features Captured
docs/screenshots/electron-BRCA1.png Desktop App (Electron) Full layout with AlphaFold 3D structure (3Dmol.js), lollipop chart, variant table, and synchronization docs/screenshots/electron-BRCA1.png:1-39
docs/screenshots/BRCA1-mobile.png Mobile / Responsive Web Adaptive layout collapsing sidebar panels and resizing UI components for smaller viewports docs/screenshots/BRCA1-mobile.png:1-40
docs/screenshots/TP53-desktop-dark.png Desktop Dark Mode tokens.css dark theme variant rendering TP53 structure and analytics panels under high-contrast rules docs/screenshots/TP53-desktop-dark.png:1-21

Sources: docs/screenshots/electron-BRCA1.png:1-39, docs/screenshots/BRCA1-mobile.png:1-40, docs/screenshots/TP53-desktop-dark.png:1-21

4. Screenshot Regeneration and Automation

Screenshots are not merely static mockups; they are generated and validated as part of the end-to-end testing pipeline using Playwright.

graph TD
  PlaywrightRunner["tests/e2e/web.spec.js"] --> LaunchBrowser["Chromium + WebGL SwiftShader"]
  LaunchBrowser --> LoadFixture["Load Mock Gene Data"]
  LoadFixture --> RenderPanels["Render src/ui Components"]
  RenderPanels --> CaptureScreen["page.screenshot()"]
  CaptureScreen --> StoreAsset["docs/screenshots/"]

  subgraph "Code Entity Space"
    PlaywrightRunner
    LaunchBrowser
    LoadFixture
    RenderPanels
    CaptureScreen
  end

  subgraph "Artifact Space"
    StoreAsset
  end
Loading

Diagram 2: Automated Screenshot Generation Pipeline.

Regeneration Mechanism

  1. Headless WebGL Execution: Playwright tests configured in playwright.config.js launch Chromium with software WebGL rendering flags (--use-gl=swiftshader) to ensure deterministic 3D structure rendering across CI runners and local developer machines.
  2. State Stabilization: Test specifications in tests/e2e/web.spec.js navigate to specific gene views (such as BRCA1 and TP53), wait for asynchronous data joins and 3D canvas rendering to complete, and apply specific viewport dimensions (mobile vs desktop) or theme toggles (dark mode).
  3. Artifact Output: Using Playwright's page.screenshot(), visual snapshots are captured and stored directly into docs/screenshots, ensuring documentation remains synchronized with UI updates.

Sources: docs/ARCHITECTURE.md:33-35, docs/screenshots/electron-BRCA1.png:1-39

Content imported from DeepWiki.

VariantScope Wiki

Clone this wiki locally