# Taxonomia

O catálogo do DeployAlly é organizado em uma hierarquia inspirada na taxonomia biológica. Cada template ocupa um lugar exato na árvore — você acha o que precisa por categoria (família funcional) ou por slug (espécie técnica).

# Hierarquia

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

Os campos relevantes ficam em identity do template:

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

E a variant é declarada em image.variants[]:

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

# Family ≠ Archetype

É comum confundir, mas são eixos diferentes:

• family descreve o que o serviço faz funcionalmente (é um CMS, um banco, uma ferramenta de notas).
• archetype descreve como o serviço se comporta tecnicamente (é uma app, um asset, um worker — ver Ecologia).

Exemplos:

# Organização do Catálogo

No backend, o catálogo é organizado em diretórios por 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
└── …

Cada arquivo <species>.yaml é um template completo. O nome do diretório vira a category exibida no front; o campo identity.family no template confirma essa colocação.

# Categorias Suportadas

O catálogo cobre múltiplas verticais. Exemplos das principais categorias:

A lista evolui — cada release do catálogo adiciona novas species e, ocasionalmente, novas categorias.

# URLs do Catálogo Público

O catálogo é exposto pela API em:

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

O front consome esses endpoints para montar a biblioteca pública (browse por categoria) e a página de cada template.

# Busca via CLI

# Listar species disponíveis
deployally catalog list

# Filtrar por family
deployally catalog list --family database

# Mostrar detalhes de uma species
deployally catalog show wordpress

# Validar localmente um template antes de promover
deployally validate --species wordpress

# Nomenclatura

# Promoção de Templates

Templates passam por três estados internos antes de aparecerem no catálogo público:

Cada published exige deployally validate zerado e — quando aplicável — teste de deploy real no servidor de testes do projeto.

# Próximos Passos

• Templates — A estrutura YAML de cada species.
• Ecologia — Como archetypes diferem de families e como serviços se conectam.
• Definitions e Instances — Como uma species do catálogo vira um container rodando.