Registry Architecture¶
Alongside the narrative Markdown documentation, this repository maintains a small set of machine-readable registries under portfolio/. This document explains their intended purpose and structure. The registries themselves, and the JSON Schema files that validate them, are created and maintained by tooling and by whichever party owns portfolio/ and schemas/ — this document only describes the architecture, it does not itself define the schemas.
The registries¶
portfolio/venture-registry.json¶
An index of every venture, keyed by a stable venture ID and slug (e.g., shelfery, digital-products). Expected to carry, at minimum: venture ID, slug, display name, status (e.g., active, dormant, sunset), and a pointer to the venture's directory and top-level documentation.
portfolio/product-registry.json¶
An index of every product across all ventures, keyed by a stable product ID. Expected to carry, at minimum: product ID, owning venture ID, slug, lifecycle status (see artifact-lifecycle.md), and a pointer to the product's specification document.
portfolio/repository-registry.json¶
An index of repositories related to Devonshire Digital's work — this repository itself, and any separate implementation repositories that may exist now or in the future (see future-repository-strategy.md). Expected to carry, at minimum: repository ID, name, purpose/role (e.g., "governance and specification," "Shelfery app implementation"), and its relationship to ventures/products in the other two registries.
Stable IDs¶
Every entry in a registry is expected to carry a stable identifier that, once assigned, does not change even if the entry's name, slug, or status changes later. Stable IDs let other documents and tooling reference an entry reliably (e.g., in cross-links or automated checks) without breaking if a display name is updated. See docs/standards/naming-standard.md for slug and ID conventions.
Relationship to Markdown documentation¶
Registries are indexes and metadata, not narrative content. A registry entry might tell you that a product exists, what venture owns it, and what lifecycle stage it is in — it does not tell you why the product exists, what problem it solves, or what its acceptance criteria are. That narrative content lives exclusively in the corresponding Markdown documents (venture pages, product specifications, ADRs).
In case of any apparent disagreement between a registry entry and its corresponding Markdown document (for example, a registry says a product is "active" but its specification says status: deprecated), the Markdown document is authoritative and the registry entry should be treated as stale and corrected.
Validation¶
Each registry is expected to be validated against a corresponding JSON Schema file under schemas/ (e.g., schemas/venture.schema.json, schemas/product.schema.json, schemas/repository.schema.json). Schema validation checks structural correctness (required fields, allowed values, ID format) — it cannot check narrative accuracy or whether the Markdown and registry agree. That check, where automated, belongs to tooling under scripts/ and tests/.
Why this split exists¶
Machine-readable registries make it possible to answer structural questions programmatically — "how many active products does Shelfery have," "which repositories implement Digital Products" — without parsing prose. Keeping the narrative content in Markdown, rather than trying to encode it as structured data, keeps specifications and decisions readable and writable by humans and avoids forcing nuanced reasoning into rigid fields.