ADR-002: Short Canonical Service Names (PLT-2122)¶
Status: Accepted (in progress — some services still deploying under legacy names) Date: 2025-06
Context¶
As services were added to the EVO platform incrementally, each was given a name reflecting its immediate purpose at the time. These names grew inconsistent: some used a platform- prefix, some used a service suffix, and some did neither. The same inconsistency leaked into CQS queue names, because each service registered its queue under its own Cloud Run service name.
The result was a mix of long, verbose, and not uniformly structured names:
| Legacy name | Problem |
|---|---|
platform-designer-service |
platform- prefix + -service suffix — double wrapper |
platform-evaluation-engine |
platform- prefix, inconsistent with others |
image-render-service |
-service suffix, no domain prefix |
link-service |
Short but uses -service suffix unlike the target convention |
transmission-service |
Functional, but not domain-grouped |
dtoflow-file-service |
Internal name exposes implementation detail (file-service) |
platform-dtoflow-server |
Leaks the infrastructure name |
platform-scenario-service |
platform- prefix + -service suffix |
Cloud Run service names and CQS queue names are visible in infrastructure tooling, logs, IAM bindings, and deployment manifests. Inconsistent names increase cognitive load when reading dashboards, tracing requests across services, or granting permissions.
The CQS queue name equals the Cloud Run service name. This is an enforced convention: a service registers its queue under the name it uses for Cloud Run deployment. Canonicalising service names therefore also canonicalises queue names in one step.
Decision¶
All services are renamed to short, domain-grouped canonical names following the pattern {domain}-{role} or {domain}-{noun}. The platform- prefix, -service suffix, and -server suffix are all dropped. The dtoflow- prefix is reserved for infrastructure-level services; the studio- prefix for Studio-side domain services.
Name mapping¶
| Legacy name | Canonical name | Domain group |
|---|---|---|
platform-designer-service |
studio-design-library |
Studio |
platform-evaluation-engine |
studio-link-evaluator |
Studio |
image-render-service |
studio-renderer |
Studio |
link-service |
link-registry |
Core |
transmission-service |
dtoflow-transmission |
DTOflow infrastructure |
dtoflow-file-service |
dtoflow-lfs |
DTOflow infrastructure |
platform-dtoflow-server |
dtoflow-spanner |
DTOflow infrastructure |
platform-scenario-service |
studio-scenario-library |
Studio |
CQS queue name rule¶
The CQS queue name for a service is exactly the canonical Cloud Run service name. There are no separate naming conventions for queues.
Consequences¶
Easier:
- Service names in dashboards, IAM policies, and log queries are shorter and easier to scan.
- Domain grouping is immediately visible: studio-* services are Studio-side; dtoflow-* services are infrastructure.
- CQS queue names align with service names, so a queue name unambiguously identifies the service that owns it.
- New services joining the platform have a clear naming convention to follow.
Harder: - The migration is not atomic. Services are renamed as deployments are updated, which means both old and new names exist simultaneously during the transition. IAM bindings, deployment manifests, and CQS queue registrations must be updated in coordination. - Any external system (monitoring, alerting, log-based metrics) that references legacy service names must be updated. Alerts may silently stop firing if the service name changes and the alert query is not updated. - CQS queues registered under the old service name must be migrated. The old queue must be drained or its configuration re-registered under the new name before the old one is removed.
Tracking: - Each service's rename should be tracked as an explicit deployment task. The rename is not complete until the service runs under the new name in all environments (dev, staging, production) and the legacy name is removed from all IAM bindings and config references.