Theme App Runtime Architecture

This document describes the Theme App runtime that exists in the current core codebase. It intentionally documents the current support boundary, not a future Kubernetes controller design.

Runtime Model

Theme Apps are executable storefront packages that the API service starts as local child processes.

Current behavior:

1. Admin activates a theme whose type is app
2. API reads extensions/themes-app/{target}/{slug}/{version}/theme-app.json
3. API allocates a local port
4. API spawns node <runtime.entry> inside the installed Theme App directory
5. API performs health checks against the spawned app
6. Shop/Admin traffic is proxied through /theme-app/{target}/{slug}/*

Runtime Policy Flags

The API service exposes three runtime policy environment variables:

Core implementation:

• apps/api/src/core/admin/theme-app-runtime/contract.ts
• apps/api/src/core/admin/theme-app-runtime/manager.ts
• apps/api/src/core/admin/theme-app-runtime/gateway.ts
• apps/api/src/core/admin/theme-management/service.ts

Supported Contract

Theme Apps must use theme-app.json as the manifest filename.

{
  "schemaVersion": 1,
  "type": "theme-app",
  "slug": "yevbi",
  "name": "Yevbi",
  "version": "1.0.0",
  "target": "shop",
  "runtime": {
    "kind": "next-standalone",
    "entry": "server.js",
    "healthPath": "/api/health"
  },
  "port": {
    "preferred": 3100,
    "range": { "min": 3100, "max": 3199 }
  },
  "healthCheck": {
    "timeout": 5000,
    "retries": 3,
    "retryInterval": 2000
  },
  "env": {
    "LOG_LEVEL": "info"
  }
}

Authoritative Rules

• theme-app.json is the only supported Theme App manifest filename
• runtime.kind must be next-standalone
• runtime.entry is required
• Theme App packages must include built artifacts such as .next/static and/or public
• Source files such as .ts, .tsx, .jsx, shell scripts, binaries, and source maps are rejected at install time

Health Check Resolution

The runtime resolves health checks in this order:

1. healthCheck.path if present
2. runtime.healthPath if present
3. default path /api/health

The following defaults apply when the manifest does not override them:

• timeout: 5000
• retries: 3
• retry interval: 2000

Runtime State

Theme App runtime state is process-local and in-memory:

• running instances are stored in an in-memory map
• allocated ports are stored in an in-memory set
• proxy routing resolves only instances known to the current API process

That means the current runtime is suitable for:

• local development
• single-process deployments
• controlled internal environments where this constraint is acceptable

For Kubernetes deployments, the supported shape is:

• services.api.replicaCount = 1, or
• an explicit unsafe override via THEME_APP_RUNTIME_ALLOW_UNSAFE_MULTI_POD=true

It is not a cluster-aware scheduler.

Operational Limitation

The current implementation does not:

• create Kubernetes Deployments or Services
• start external microservice Theme Apps
• coordinate runtime state across multiple API Pods

If you run multiple API replicas, Theme App activation and proxying are still pod-local. Treat Theme Apps as an advanced, restricted capability until a dedicated runtime controller exists.

Installation and Activation

Installation

Theme App ZIP installation validates:

• theme-app.json
• manifest schema
• target compatibility
• build artifacts
• prohibited file types
• optional package signature

Installer implementation:

• apps/api/src/core/admin/extension-installer/theme-app-installer.ts

Activation

Activation is fail-safe:

1. current active theme is read
2. Theme App is started
3. health check must pass
4. only then is the active theme record switched

If start or health check fails, the active theme stays unchanged.

Recommended Usage

Use Theme Apps only when you truly need a standalone storefront runtime. For most theme customization, prefer Theme Packs plus plugin app block and app embed extensions.

Related docs:

• Theme Development Guide