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 tier (platinum, gold, silver, bronze)
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

Tiers indicate the criticality and SLA expectations of an entity:

Tier	Description
platinum	Mission-critical, highest SLA
gold	Important, high SLA
silver	Standard, normal SLA
bronze	Best-effort, low SLA