Skip to content
Componecat Docs

Entities and kinds

The catalog is made of entities. An entity is anything worth tracking: a system, a service, a shared library, a datastore, a tool, a knowledge base. Every entity has a kind that decides what it can hold, a set of fields that describe it, and an owner responsible for it.

Kinds

Section titled “Kinds”

A kind is a reusable template. It controls which features an entity has — whether it links to a repository, hosts documentation, exposes interfaces, keeps an activity log, or can have children — and which fields appear on it.

Every new organization starts with two ready-to-use kinds:

Kind Typical use
System A top-level grouping of related components.
Component A service or library, usually backed by a source repository.

More kinds ship as starter templates — add the ones you need with a click:

Kind Typical use
Resource A datastore, queue, bucket, or piece of infrastructure.
Knowledge Base A collection of documentation with no interfaces or children.
Tool An internal tool or utility.
AI Skillset A capability made available to AI agents.
Template A starting point other entities are created from.
Data Pipeline, Product Further ready-made starting points.

Nothing is locked. You can customize any kind’s display (name, icon, color, order), toggle its features, and change which fields it carries — and you can delete a kind once no entities are using it. Even the two you start with are yours to reshape.

Custom kinds

Section titled “Custom kinds”

Organizations can define their own kinds — microservice, data-pipeline, golden-path, whatever fits your taxonomy — from Settings → Entity Kinds, or through the APIs. Each kind defines:

  • Display — name, description, icon, color, and sort order.
  • Features — which of repository, documentation, interfaces, activity log, and children are enabled.
  • Constraints — which kinds are allowed as children, and which interface kinds are allowed, so the catalog stays well-formed.
  • Fields — the set of fields entities of this kind carry, each optionally required.

Starter templates (like resource or data-pipeline) let an administrator bootstrap a new kind with a curated field set instead of building it from scratch.

Built-in fields

Section titled “Built-in fields”

Every entity, regardless of kind, has a fixed set of fields:

Field Notes
Display name The human-readable name shown throughout the UI.
Name A URL-friendly slug; the addressable part of the entity’s reference.
Namespace An optional grouping segment in the reference.
Owner The team responsible for the entity.
Lifecycle Experimental, Development, Production, Deprecated, or Retired.
Description A short summary shown in cards and search results.
Tags Free-form labels for filtering and grouping.
Repository The source repository URL (on kinds that link to code).

Componecat also tracks repository metadata automatically for linked entities — the default branch, detected languages, and README content — and keeps lifecycle timestamps.

Custom fields

Section titled “Custom fields”

Beyond the built-ins, you can define your own fields and attach them to one kind, several kinds, or every kind. Fields are typed — text, number, boolean, date, URL, single- and multi-select, user or team references, labels, and structured JSON — and validated on save. Define them under Settings → Field Definitions.

Entity references

Section titled “Entity references”

Every entity is addressable by a reference URI of the form kind://namespace/name (or kind://name when it has no namespace) — for example component://payments/payment-gateway. References are unique within an organization and are how descriptors, relationships, and API calls point at entities.

Section titled “Related”