ADR 031: Project Terminology (Ubiquitous Language)¶

Status: Active Type: Guideline Created: 2025-11-28 Related-ADRs: 020, 022, 030, 036

Context¶

A clear, consistent vocabulary is essential for any software project. Following Domain-Driven Design principles, we define an ubiquitous language - a shared vocabulary between domain experts (DevOps engineers, developers, SREs) and the codebase.

This ADR serves as the definitive reference for terminology used throughout the Hop3 project. It consolidates decisions from multiple discussions and ADRs into a single authoritative source.

Problems Addressed¶

1. Terminology Conflicts: Words like "service" have multiple meanings in different contexts (microservices vs. backing services)
2. Abstraction Level Confusion: Mixing orchestration concepts with language-specific tooling
3. Legacy Naming: Old naming patterns that no longer reflect the architecture
4. Documentation Drift: Inconsistent terminology across code, docs, and discussions

Decision¶

We adopt the following terminology as the standard vocabulary for Hop3.

Core Concepts¶

Applications and Blueprints¶

The Blueprint vocabulary is the candidate naming for the packaged-app installation use case; the open questions it raises are listed under Unresolved Questions.

Hop3 supports two distinct use cases that both result in deployed applications:

Core Terms¶

App Origin¶

An App can originate from: 1. Custom code - Developer pushes their own code (Heroku-style) 2. Blueprint - Operator installs from catalog (App Store-style)

The origin is metadata, not a fundamental type distinction. All apps share the same management commands regardless of origin.

Catalog vs. Marketplace¶

Catalog is the canonical term for the free, self-host collection of installable Blueprints (browse → install → configure on your own server). It carries no commercial connotation — there are no prices, sellers, or payments.

Marketplace is reserved for the future commercial product: a hosted, branded "SaaS marketplace" with premium/paid apps. Do not call the free feature a "marketplace" — keeping the two distinct stops a product feature being conflated with a business model.

Spelling: use the US catalog, not the British "catalogue", to match the codebase's prevailing US-English convention (color, license, behavior).

The web UI carries this name throughout: the server/catalog/ package, the CatalogController/CatalogService/CatalogApp classes, and the /dashboard/catalog route. See Migration Notes.

Additional App Terms¶

Data Model¶

class App:
    """A deployed application instance."""
    name: str                           # Instance name: "acme-blog"

    # Origin tracking (optional)
    blueprint_name: str | None = None   # e.g., "wordpress" or None for custom
    blueprint_version: str | None = None

    @property
    def is_custom(self) -> bool:
        return self.blueprint_name is None

    @property
    def is_from_blueprint(self) -> bool:
        return self.blueprint_name is not None


class Blueprint:
    """A packaged application available in the catalog."""
    name: str           # e.g., "wordpress", "nextcloud"
    version: str        # e.g., "6.4.1"
    description: str
    # ... catalog metadata, deployment instructions

CLI Examples¶

Custom App (Developer workflow):

git push hop3 main              # Deploy from git
hop3 apps list
# NAME        ORIGIN    STATE
# my-api      custom    running

Blueprint App (Operator workflow):

hop3 blueprints list            # Browse catalog
hop3 blueprints install wordpress --name company-blog
hop3 apps list
# NAME          ORIGIN              STATE
# company-blog  wordpress@6.4.1     running
# my-api        custom              running

Deployment Pipeline¶

The deployment process follows a three-stage pipeline: Build → Deploy → Proxy.

Two-Level Build Architecture (from ADR 030)¶

Level 1: Builder (Orchestration) - Defines HOW to build: locally, in Docker, with Nix - Examples: LocalBuilder, DockerBuilder, NixBuilder - Selection: Configuration-driven (hop3.toml) or auto-detection

Level 2: LanguageToolchain (Language-Specific) - Defines WHAT tools to use for a specific language - Examples: PythonToolchain, NodeToolchain, JavaToolchain - Selection: Auto-detection based on project files (requirements.txt, package.json) - Only used by LocalBuilder; other builders encapsulate their own logic

Data Flow Objects¶

Platform Resources¶

Addon vs. Service Distinction¶

This is a critical distinction to avoid confusion:

Rationale: Using "Addon" (Heroku convention) avoids collision with microservices terminology. Platform-managed resources are called "addons"; the user's application components remain "services" in their domain.

Plugin System¶

Complete Terminology Reference¶

A¶

B¶

C¶

D¶

E-H¶

L¶

M¶

N-O¶

P¶

S¶

T¶

U-W¶

Naming Conventions¶

Protocol Names¶

• Use noun form: Builder, Deployer, Addon, Proxy, OS
• Capitalize as proper nouns when referring to the protocol

Class Names¶

Hook Names¶

Field Names¶

Codebase Alignment¶

Two identifiers carry forward names that predate this vocabulary and remain candidates for alignment:

Unresolved Questions¶

The Blueprint vocabulary names a use case whose terminology is not yet final. The following questions remain open.

Blueprint Terminology¶

1. Is "Blueprint" the right term?
2. Alternatives considered: Package, Template, Recipe, Offering

3. "Blueprint" is preferred for its clear metaphor (blueprint → building)

4. Should blueprints be versioned independently?

5. Can users upgrade a deployed app to a newer blueprint version?

6. How do we handle breaking changes in blueprints?

7. Blueprint sources?

8. Official catalog only?
9. Community-contributed blueprints?

10. Self-hosted blueprint repositories?

11. Relationship to Nix

12. If pursuing Nix integration (ADRs 007-009), should Blueprints map to Nix flakes?

13. Or keep them as a higher-level abstraction?

14. CLI command naming

15. hop3 blueprints install vs hop3 install vs hop3 apps create --from-blueprint
16. Should blueprint commands be under apps or separate?

Migration Notes¶

From Previous Terminology¶

Deprecated Terms (Do Not Use)¶

• Service for platform resources (use Addon)
• Platform for OS (use OS)
• Runtime for deployers (use Deployer - covers systemd, static, etc.)
• Strategy as suffix (use specific protocol names)

Rationale¶

Why Heroku-Inspired Naming?¶

1. Industry Recognition: Heroku terminology is widely understood in the PaaS space
2. Clear Semantics: Terms like "addon" have specific, unambiguous meanings
3. User Familiarity: Developers migrating from Heroku find familiar concepts
4. Avoids Conflicts: "Addon" doesn't conflict with microservices terminology

Why Two-Level Build Architecture?¶

1. Separation of Concerns: Build orchestration vs. language-specific logic
2. Multi-Language Support: One builder can use multiple toolchains
3. Extensibility: Easy to add new builders or toolchains independently
4. Type Safety: Clear protocol boundaries enable proper type checking

See ADR 030 for detailed rationale.

Why "Deployer" Not "Runtime"?¶

"Runtime" implies execution environment, but deployers also: - Manage static file serving (no runtime) - Configure systemd services (process manager, not runtime) - Handle lifecycle management (start, stop, scale)

"Deployer" accurately describes deployment + lifecycle management for all implementations.

Why "OS" Not "Platform"?¶

"Platform" is ambiguous: - Could mean the PaaS platform (Hop3) - Could mean infrastructure (AWS, bare metal) - Could mean OS (Debian, Ubuntu)

"OS" is clear and specific.

Success Criteria¶

This terminology is successful when:

1. New developers understand concepts without explanation
2. Documentation uses consistent vocabulary
3. Code identifiers match domain language
4. No terminology conflicts in discussions
5. Plugin authors know which protocol to implement

References¶

• Domain-Driven Design (Eric Evans) - Ubiquitous Language concept
• Heroku Platform - Addon terminology
• 12-Factor Apps - Backing services concept
• ADR 020: Pluggable Architecture
• ADR 022: Build/Deploy Plugin System
• ADR 030: Two-Level Build Architecture

Related ADRs: ADR 020: Pluggable Architecture for Core Deployment Workflow, ADR 022: Build and Deployment Plugin System, ADR 030: Two-Level Build Architecture, ADR 036: CLI Ergonomics and Command Surface