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

> Learn how World Monitor uses single deployment multi variant architecture to serve four dashboards from one Vercel build. Optimize your code organization and deployment.

- Repository: [Elie Habib/worldmonitor](https://github.com/koala73/worldmonitor)
- Tags: architecture
- Published: 2026-03-09

---

**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`](https://github.com/koala73/worldmonitor/blob/main/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:

```typescript
// 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`](https://github.com/koala73/worldmonitor/blob/main/src/config/variant-meta.ts). The `VARIANT_META` map defines titles, descriptions, favicons, and Open Graph tags for every variant:

```typescript
// 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`](https://github.com/koala73/worldmonitor/blob/main/vite.config.ts) processes [`index.html`](https://github.com/koala73/worldmonitor/blob/main/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:

```typescript
// 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`](https://github.com/koala73/worldmonitor/blob/main/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:

```typescript
// 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`](https://github.com/koala73/worldmonitor/blob/main/src/config/variant.ts) selects the active dashboard flavor based on hostname or localStorage settings.
- **Build-time injection** via `htmlVariantPlugin()` in [`vite.config.ts`](https://github.com/koala73/worldmonitor/blob/main/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`](https://github.com/koala73/worldmonitor/blob/main/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`](https://github.com/koala73/worldmonitor/blob/main/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.