Template Naming Migration Plan (Game* -> Template*)

Status (February 25, 2026): Implemented directly (no backward-compat alias/deprecation phase). This document is now historical context and parts of the staged strategy below are superseded.

Context

The product now supports a broader set of workload templates (gaming, web apps, databases, DevOps). At the time this plan was written, core planner APIs and internal types still used Game* naming (GameSpec, /planner/games, /game-config/...).

This plan defines a gradual, backward-compatible migration toward template-oriented naming.

Goals

• Introduce template-oriented names in API and code without breaking existing clients.
• Allow frontend and docs to adopt new terminology incrementally.
• Preserve stable JSON schema/behavior during the transition.

Non-Goals (for this phase)

• Removing existing Game* routes/types.
• Refactoring all internal variables/state names immediately.
• Breaking changes in public or authenticated planner APIs.

Hotspots (confirmed)

• Backend planner model/types:
  • internal/controlplane/planner/game_specs.go
  • internal/controlplane/planner/game_config.go
• Backend planner API routes/handlers:
  • internal/controlplane/api/planner_handler.go
  • internal/controlplane/api/public_catalog_handler.go
  • internal/controlplane/api/router.go
• Web API client/types:
  • web/src/api/types.ts
  • web/src/api/planner.ts
  • web/src/api/client.ts
• UI flows with game-centric state names:
  • web/src/components/ProvisionCloudFlow.tsx
  • web/src/components/GameConfigStep.tsx

Migration Strategy

Phase 1: Alias Layer (non-breaking) [in progress]

Introduce aliases so new code can use template terminology immediately:

• Backend type aliases:
  • TemplateSpec = GameSpec
  • TemplateConfigVariable = GameConfigVariable
  • TemplateConfigSpec = GameConfigSpec
• Backend route aliases:
  • GET /v1/planner/templates -> same behavior as /v1/planner/games
  • GET /v1/planner/template-config/{templateID} -> same behavior as /v1/planner/game-config/{gameID}
  • GET /v1/public/planner/templates -> same behavior as /v1/public/planner/games
• Frontend API aliases:
  • TemplateSpec, TemplateConfigVariable, TemplateConfigSpec
  • plannerApi.getTemplates(), plannerApi.getPublicTemplates(), plannerApi.getTemplateConfig()

Phase 2: New Call Sites Prefer Template Naming

Switch new/edited frontend code to aliases first:

• Prefer TemplateSpec in new UI components and hooks.
• Prefer getTemplates / getTemplateConfig in new integrations.
• Keep legacy getGames / getGameConfig for existing paths until churn is worth it.

This reduces semantic drift without forcing a large refactor.

Phase 3: UI Internal State and Component Naming

Refactor UI internals gradually (file-by-file), maintaining behavior:

• ProvisionCloudFlow
  • step: 'game' -> step: 'template' (with local alias map if needed)
  • gameConfig -> templateConfig
• GameConfigStep.tsx
  • eventual rename to TemplateConfigStep.tsx
  • export compatibility alias during transition

Rule: avoid mixing API renames and visual/UX changes in the same PR when possible.

Phase 4: Documentation and Deprecation Messaging

• Update docs/api.md and docs/openapi.yaml to document both route families (games and templates).
• Mark games and game-config routes as backward-compatible legacy aliases.
• Optionally add deprecation logging/metrics for legacy route usage.

Phase 5: Retirement (future major/minor decision)

Only after telemetry confirms no important usage:

• Deprecate and eventually remove legacy route names.
• Remove Game* aliases if no longer used internally.

Compatibility Rules

• JSON payload field names remain unchanged in early phases (game_id, etc.) unless an explicit migration is planned.
• Route aliases must return identical payloads and status codes.
• New aliases should not duplicate logic; they should delegate to existing handlers/functions.

Suggested Execution Order (small PRs)

1. Alias types + alias routes (done / current PR scope)
2. Frontend API aliases and new call sites on touched files
3. ProvisionCloudFlow local state rename (UI internals only)
4. GameConfigStep rename/export alias
5. Docs/OpenAPI dual-route documentation + deprecation notes

Risks / Trade-offs

• Short-term duplication (Game* + Template*) increases surface area.
• Mixed naming in codebase persists temporarily.
• This is intentional to avoid breaking clients and to ship the repositioning safely.