Single-Deployment Multi-Variant Architecture: How World Monitor Serves Four Dashboards from One Vercel Build

World Monitor implements a single-deployment multi-variant architecture that detects the dashboard flavor at runtime based on hostname or localStorage, eliminating the need for separate builds while maintaining distinct branding and feature sets for each variant.

The koala73/worldmonitor repository demonstrates an advanced code organization strategy that consolidates four specialized dashboards—full, tech, finance, and happy/commodity—into a single deployable unit. This approach leverages runtime variant detection and build-time meta injection to serve differentiated experiences from one unified codebase and CI pipeline.

Runtime Variant Detection Strategy

The architecture centers on dynamic variant identification that occurs client-side or at request time, rather than compiling separate application bundles.

Hostname-Based Routing

In src/config/variant.ts, the application determines which dashboard flavor to render by inspecting the current hostname. The logic checks for subdomain prefixes like tech., finance., happy., or commodity. to set the active variant:

// src/config/variant.ts
export const SITE_VARIANT: string = (() => {
  // Server-side (SSR) fallback to VITE_VARIANT env var
  if (typeof window === 'undefined') return import.meta.env.VITE_VARIANT || 'full';

  // Desktop (Tauri) override via localStorage
  const isTauri = '__TAURI_INTERNALS__' in window || '__TAURI__' in window;
  if (isTauri) {
    const stored = localStorage.getItem('worldmonitor-variant');
    if (stored) return stored;
    return import.meta.env.VITE_VARIANT || 'full';
  }

  // Web: hostname determines variant
  const h = location.hostname;
  if (h.startsWith('tech.')) return 'tech';
  if (h.startsWith('finance.')) return 'finance';
  if (h.startsWith('happy.')) return 'happy';
  if (h.startsWith('commodity.')) return 'commodity';
  if (h === 'localhost' || h === '127.0.0.1') {
    const stored = localStorage.getItem('worldmonitor-variant');
    if (stored) return stored;
    return import.meta.env.VITE_VARIANT || 'full';
  }
  return 'full';
})();

This detection mechanism supports both web deployments (via subdomain) and desktop clients built with Tauri (via localStorage overrides).

Variant Metadata Configuration

Static attributes for each dashboard flavor are centralized in src/config/variant-meta.ts. The VARIANT_META map defines titles, descriptions, favicons, and Open Graph tags for every variant:

// src/config/variant-meta.ts
export const VARIANT_META = {
  full: { title: 'World Monitor – Real-Time Global Intelligence', ... },
  tech: { title: 'Tech Monitor – Real-Time AI & Tech Dashboard', ... },
  finance: { title: 'Finance Monitor – Real-Time Markets & Trading', ... },
  happy: { title: 'Happy Monitor – Good News & Global Progress', ... },
  commodity: { title: 'Commodity Monitor – Real-Time Commodity & Supply-Chain', ... },
};

Build-Time Injection and Runtime Adaptation

The single-deployment strategy relies on Vite plugins to inject variant-specific metadata during the build process, while runtime JavaScript handles dynamic UI switching.

HTML Meta Tag Injection

The htmlVariantPlugin() function in vite.config.ts processes index.html to insert the correct meta tags based on the VITE_VARIANT environment variable. This ensures that SEO-critical elements like titles and descriptions match the targeted dashboard flavor:

// vite.config.ts (excerpt)
function htmlVariantPlugin(): Plugin {
  return {
    name: 'html-variant',
    transformIndexHtml(html) {
      const activeVariant = process.env.VITE_VARIANT || 'full';
      const activeMeta = VARIANT_META[activeVariant] ?? VARIANT_META.full;

      // Replace meta tags & titles with variant-specific strings
      let result = html
        .replace(/<title>.*?<\/title>/, `<title>${activeMeta.title}</title>`)
        .replace(/<meta name="description" content=".*?" \/>/, `<meta name="description" content="${activeMeta.description}" />`)
        // …other replacements omitted for brevity…

      // Insert runtime script that sets data-variant before CSS loads
      if (activeVariant !== 'full') {
        result = result.replace(
          /if\(v\)document\.documentElement\.dataset\.variant=v;/,
          `v='${activeVariant}';document.documentElement.dataset.variant=v;`
        );
      }
      return result;
    },
  };
}

The plugin also writes an inline script that sets document.documentElement.dataset.variant, enabling CSS selectors to react to the active variant immediately on page load.

Theme and Feature Gating

Runtime adaptation extends to visual theming and functional feature gates. In src/utils/theme-manager.ts, the variant influences theme-color meta tags and CSS custom properties. Feature modules throughout the codebase use simple conditional checks to enable variant-specific data sources:

// src/services/prediction/index.ts (excerpt)
import { SITE_VARIANT } from '@/config/variant';
…
const variant = SITE_VARIANT === 'tech' ? hydrated.tech : hydrated.geopolitical;
if (variant && variant.length > 0) {
  return variant.filter(m => !isExpired(m.endDate)).slice(0, 15);
}

Positive-news sources, for example, are only enabled when SITE_VARIANT === 'happy', ensuring that each dashboard receives relevant content without bundling unnecessary data services for other variants.

Benefits of the Single-Deployment Approach

This architecture delivers significant operational and performance advantages compared to maintaining separate repositories or build pipelines for each dashboard flavor.

• Unified CI/CD Pipeline: One GitHub Actions workflow builds, tests, and deploys the application, eliminating configuration drift risks across multiple Vercel projects.
• CDN Cache Efficiency: Since identical HTML, JavaScript, and asset bundles are served for every variant, Vercel’s edge cache achieves approximately 4× higher hit rates compared to distinct deployments.
• Instant Variant Switching: The header’s variant selector updates document.documentElement.dataset.variant (or localStorage for desktop), triggering immediate CSS and layer reordering without requiring a full page reload.
• Simplified Maintenance: All source files compile once, reducing build times and ensuring that shared components remain synchronized across all dashboard flavors.

Summary

The single-deployment multi-variant architecture in koala73/worldmonitor demonstrates how modern SPAs can serve differentiated experiences from a unified codebase:

• Runtime detection in src/config/variant.ts selects the active dashboard flavor based on hostname or localStorage settings.
• Build-time injection via htmlVariantPlugin() in vite.config.ts optimizes SEO metadata for the target variant while keeping the bundle unified.
• CSS and JavaScript adaptation through data-variant attributes and conditional logic enables instant UI switching and feature gating.
• Operational consolidation provides higher cache hit rates, faster deployments, and reduced maintenance overhead compared to multi-repository strategies.

Frequently Asked Questions

How does World Monitor determine which variant to display?

World Monitor detects the variant at runtime by checking the current hostname for subdomain prefixes (such as tech. or finance.) or by reading from localStorage when running as a desktop Tauri application. The detection logic resides in src/config/variant.ts and exports a SITE_VARIANT constant used throughout the application.

Can users switch between variants without reloading the page?

Yes. The application supports instant variant switching by updating document.documentElement.dataset.variant via the header selector or by modifying the localStorage value in the desktop client. This triggers immediate CSS variable updates and layer reordering without requiring a full page refresh.

Why not use separate builds for each dashboard flavor?

Separate builds would fragment the CDN cache, requiring Vercel to store and serve distinct asset bundles for each subdomain. The single-deployment strategy maximizes cache reuse across all variants, improves build performance by compiling once, and maintains a single CI/CD pipeline that prevents deployment drift between dashboard flavors.

Where is the single-deployment architecture documented?

The comprehensive design rationale and implementation details are documented in docs/ARCHITECTURE.md under the "Single-Deployment Variant Consolidation" section. This file explains the trade-offs between runtime and build-time variant selection and provides guidance for extending the architecture to support additional dashboard flavors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}