# Taxonomy

The DeployAlly catalog is organized into a hierarchy inspired by biological taxonomy. Every template lives at an exact place in the tree — you find what you need by category (functional family) or by slug (technical species).

# Hierarchy

kingdom
  └── family
        └── species
              └── variant

The relevant fields live in the template's identity:

identity:
  slug: wordpress     # species
  name: WordPress
  archetype: application
  family: cms         # family
  app_version: "6.7"

The variant is declared in image.variants[]:

image:
  base: wordpress
  variants:
    - { id: php82-apache, tag: php8.2-apache, default: true }
    - { id: php81-apache, tag: php8.1-apache }

# Family ≠ Archetype

It's a common confusion, but they're different axes:

• family describes what the service does functionally (it's a CMS, a database, a notes tool).
• archetype describes how the service behaves technically (it's an app, an asset, a worker — see Ecology).

Examples:

# Catalog Organization

On the backend, the catalog is organized into directories by family/category:

factory/catalog/
├── _registry.yaml
├── blog/
│   └── wordpress.yaml
├── database/
│   ├── mariadb.yaml
│   ├── mysql.yaml
│   ├── postgresql.yaml
│   └── …
├── notes/
│   ├── memos.yaml
│   ├── joplin.yaml
│   └── …
├── cache/
│   └── redis.yaml
├── workflow/
│   └── n8n.yaml
├── monitoring/
│   └── uptime-kuma.yaml
├── password/
│   └── vaultwarden.yaml
├── email/
│   └── postal.yaml
├── ingress/
│   └── traefik.yaml
└── …

Each <species>.yaml file is a complete template. The directory name becomes the category shown in the front; the template's identity.family field confirms that placement.

# Supported Categories

The catalog covers many verticals. Examples of the main categories:

The list evolves — each catalog release adds new species and, occasionally, new categories.

# Public Catalog URLs

The catalog is exposed by the API at:

GET /api/v1/templates/<species>
GET /api/v1/catalog?family=<family>
GET /api/v1/catalog/categories

The front consumes these endpoints to build the public library (browse by category) and each template's page.

# Searching via CLI

# List available species
deployally catalog list

# Filter by family
deployally catalog list --family database

# Show details for a species
deployally catalog show wordpress

# Validate a template locally before promoting
deployally validate --species wordpress

# Naming

# Template Promotion

Templates go through three internal states before showing up in the public catalog:

Each published requires deployally validate clean and — when applicable — a real deploy test on the project's test server.

# Next Steps

• Templates — The YAML structure of each species.
• Ecology — How archetypes differ from families and how services connect.
• Definitions and Instances — How a catalog species becomes a running container.