Entities

Entities are the core building blocks of the Shoehorn service catalog. Every service, library, API, database, and infrastructure component is represented as an entity.

Entity Types

Type	Description	Example
service	A running microservice or application	Payment API, User Service
api	A standalone API	Public REST API, GraphQL Gateway
frontend	A frontend or UI application	Web Dashboard, Mobile App
library	A shared library or SDK	Auth SDK, Common Utils
database	A data store	PostgreSQL, Redis, Elasticsearch
system	A collection of related entities	Payment System, Auth System
domain	A business domain	Finance, Customer Experience
resource	Infrastructure resource	S3 Bucket, Kafka Topic
component	A generic software component	Cron Job, Lambda Function
platform	A platform or runtime	Kubernetes, AWS
team	An engineering team	Platform Team, Payments Team

Entity Sources

Entities can be created from multiple sources:

Source	How	Automatic
Kubernetes	K8s agent discovers workloads	Yes
GitHub Manifests	Crawler reads .shoehorn/manifest.yml from repos	Yes
Backstage Import	Crawler reads catalog-info.yaml files	Yes
Manual	Created via UI or API	No
Terraform	Created via Terraform provider	No

Entity Lifecycle

Each entity has a lifecycle stage indicating its maturity:

Stage	Description
production	Live, serving production traffic
staging	In staging/pre-production
development	Under active development
experimental	Proof of concept or experiment
deprecated	Scheduled for decommission

Entity Attributes

Core Fields

Field	Description
Name	Display name
Service ID	Unique kebab-case identifier (e.g., payment-api)
Type	Entity type (see above)
Owner	Owning team
Lifecycle	Current lifecycle stage
Tier	Service criticality, shown as Impact (critical, high, medium, low)
Description	Human-readable description
Tags	Categorization tags

Extended Metadata

Field	Description
Links	External tool links (Grafana, ArgoCD, Docs, etc.)
Relations	Dependencies and relationships to other entities
Interfaces	API definitions (OpenAPI, gRPC, GraphQL)
Runbooks	Operational runbooks
Licenses	Software license tracking
Scorecard	Maturity score and grade

Managing Entities

Via the UI

1. Navigate to Catalog in the sidebar
2. Browse, search, and filter entities
3. Click an entity to view its detail page
4. Use the Edit button to modify attributes

Via the API

# List entities
curl https://shoehorn.example.com/api/v1/entities \
  -H "Authorization: Bearer <token>"

# Get a single entity
curl https://shoehorn.example.com/api/v1/entities/<id> \
  -H "Authorization: Bearer <token>"

# Create an entity
curl -X POST https://shoehorn.example.com/api/v1/entities \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-service",
    "type": "service",
    "lifecycle": "production",
    "owner": "platform-team"
  }'

Via Manifests

The recommended approach for managing entities at scale. See Manifests.

Entity Detail Page

The entity detail page includes these tabs:

Tab	Content
Overview	Description, owner, tier, tags, links, relations
Operations	Kubernetes workloads, pod status, GitOps sync
Scorecard	Maturity score breakdown by category
Changelog	Repository changelog entries
Activity	Recent changes and events
Governance	Governance actions and compliance status
Documentation	README and embedded docs

Service Tiers

Tier is the service’s declared criticality: how important it is and how badly users are affected if it degrades. It’s set by the author, separate from blast radius (the derived count of what depends on it).

Tier	Description
critical	Mission-critical, highest SLA
high	Important, high SLA
medium	Standard, normal SLA
low	Best-effort, low SLA

The metal words platinum, gold, silver, and bronze still work in manifests as legacy aliases. They map to critical, high, medium, and low.