Yellow Pages Data Model

Yellow Pages manages three primary entities: Services, Systems, and Owners. All entities use nanoid(8) identifiers and support both file-based and Convex storage backends.

Service

The core entity in the catalog. Represents a registered service with metadata, ownership, and dependency information.

interface Service {
  id: string;           // nanoid(8) unique identifier
  name: string;         // Human-readable name (unique, case-insensitive)
  description: string;  // What this service does
  system?: string;      // System grouping (ID or name)
  owner?: string;       // Owner (ID or name)
  tags: string[];       // Freeform tags for categorization
  metadata: Record<string, string>; // Arbitrary key-value metadata
  dependencies: string[]; // IDs of services this service depends on
  createdAt: string;    // ISO 8601 timestamp
  updatedAt: string;    // ISO 8601 timestamp
}

Notes

• The name field is used for ID-or-name resolution. Commands and API endpoints that accept :id will match against both id and name.
• dependencies stores an array of service IDs representing downstream dependencies (services this service depends on).
• tags and metadata are freeform and can be used to encode any service-specific information.

System

A logical grouping of related services.

interface System {
  id: string;           // nanoid(8) unique identifier
  name: string;         // Human-readable name (unique, case-insensitive)
  description: string;  // What this system represents
}

Owner

A person or team responsible for one or more services.

interface Owner {
  id: string;           // nanoid(8) unique identifier
  name: string;         // Owner name (person or team)
  email: string;        // Contact email
  team?: string;        // Optional team grouping
}

Storage

File-Based (SHIFT_STORAGE=file)

.yellowpages/
  services/
    <id>.json          # One file per service
  systems/
    <id>.json          # One file per system
  owners/
    <id>.json          # One file per owner

Convex (SHIFT_STORAGE=convex)

Tables use the yp_ prefix:

Table	Description
yp_services	Service records
yp_systems	System records
yp_owners	Owner records

Each record includes a sid field (shift ID) that maps to the application-level id. Convex internal _id fields are abstracted away by the ConvexStore layer.