Skip to main content

Registry Schema Guide

Purpose​

Provide a concise reference for the project registry schema, validation rules, and examples so contributors can add or review projects without breaking builds.

Scope​

  • Registry structure in src/data/projects.yml
  • Validation rules enforced by src/lib/registry.ts (Zod)
  • Environment-aware URL interpolation rules
  • Examples for common cases (minimal, gold standard, evidence-light)

Prereqs / Inputs​

  • Portfolio App registry implementation (Stage 3.1)
  • Environment variables: NEXT_PUBLIC_DOCS_BASE_URL, NEXT_PUBLIC_GITHUB_URL, NEXT_PUBLIC_DOCS_GITHUB_URL, NEXT_PUBLIC_SITE_URL
  • Validation scripts: pnpm registry:validate, pnpm registry:list

Procedure / Content​

Registry Shape​

Top-level object:

  • metadata (optional):
    • version (number, int, >0)
    • lastUpdated (string)
  • projects (array of project entries)

Project Fields​

  • slug (required): lowercase, hyphenated, regex ^[a-z0-9]+(?:-[a-z0-9]+)*$
  • title (required)
  • summary (required, >= 10 chars)
  • category (enum): fullstack | frontend | backend | devops | data | mobile | other
  • tags (array, min 1)
  • startDate (YYYY-MM, optional)
  • endDate (YYYY-MM, optional)
  • ongoing (boolean, optional)
  • status (enum): featured | active | archived | planned
  • techStack (array, min 1, optional):
    • name (required)
    • category (enum): language | framework | library | tool | platform
    • rationale (optional)
  • keyProofs (array, min 1, optional): statements of capability proof
  • repoUrl (optional, URL; supports {GITHUB_URL} placeholder)
  • demoUrl (optional, URL; supports {SITE_URL} or {DOCS_BASE_URL} placeholders)
  • evidence (object, optional):
    • dossierPath (string, path relative to docs base, e.g., projects/portfolio-app/)
    • threatModelPath (string, includes threat-model)
    • adrIndexPath (string, ADR index path)
    • runbooksPath (string)
    • adr (array): { title, url } — URLs may be docs-relative
    • runbooks (array): { title, url } — URLs may be docs-relative
    • github (URL; supports {GITHUB_URL} or {DOCS_GITHUB_URL} placeholders)
  • isGoldStandard (boolean, optional)
  • goldStandardReason (string, optional, >= 10 chars)

Validation Rules (enforced by Zod)​

  • Slug format and uniqueness across all projects
  • Required fields: title, summary, tags, status, slug
  • URL validation on repoUrl, demoUrl, evidence.github
  • Evidence link pattern warnings (non-blocking):
    • dossierPath should start with projects/ or docs/60-projects/
    • threatModelPath should include threat-model
    • adr / runbooks URLs should start with docs/ or be absolute

Environment-Aware Placeholders​

The loader interpolates placeholders before validation:

  • {GITHUB_URL} → NEXT_PUBLIC_GITHUB_URL
  • {DOCS_GITHUB_URL} → NEXT_PUBLIC_DOCS_GITHUB_URL
  • {DOCS_BASE_URL} → NEXT_PUBLIC_DOCS_BASE_URL
  • {SITE_URL} → NEXT_PUBLIC_SITE_URL

Unresolved or empty placeholders become null and will fail validation if the field is required.

Examples​

Minimal project (evidence-light)

- slug: sample-project
  title: Sample Project
  summary: 'Short summary (10+ chars).'
  category: frontend
  tags: [Next.js]
  status: active
  repoUrl: '{GITHUB_URL}'

Gold standard project (portfolio-app excerpt)

- slug: portfolio-app
  title: 'Portfolio App (Next.js + TypeScript)'
  summary: 'Production-quality portfolio application designed to be reviewed like a real service.'
  category: fullstack
  tags: ['TypeScript', 'Next.js', 'Vercel', 'CI/CD', 'Security', 'Docs-as-code']
  startDate: '2026-01'
  ongoing: true
  status: featured
  techStack:
    - name: 'Next.js 15+'
      category: framework
    - name: 'TypeScript 5'
      category: language
  keyProofs:
    - 'CI quality gates (lint, format, typecheck, secrets scan)'
    - 'Build-time validated registry'
  repoUrl: '{GITHUB_URL}'
  evidence:
    dossierPath: 'projects/portfolio-app/'
    threatModelPath: 'security/threat-models/portfolio-app-threat-model'
    adrIndexPath: 'architecture/adr/'
    runbooksPath: 'operations/runbooks/'
    github: '{GITHUB_URL}'

Multi-ADR project

- slug: docs-platform
  title: 'Documentation Platform'
  summary: 'Docusaurus-based evidence engine for portfolio projects.'
  category: fullstack
  tags: ['Docusaurus', 'TypeScript', 'Docs-as-code']
  status: active
  keyProofs:
    - 'Autogenerated sidebars with category governance'
    - 'ADR, runbook, and threat model coverage'
  evidence:
    dossierPath: 'projects/portfolio-docs-app/'
    adr:
      - title: 'ADR-0005: Stack Choice'
        url: 'architecture/adr/adr-0005-portfolio-app-stack-nextjs-ts'
      - title: 'ADR-0011: Data-Driven Project Registry'
        url: 'architecture/adr/adr-0011-data-driven-project-registry'

Evidence-free (early stage) project

- slug: sandbox-prototype
  title: 'Sandbox Prototype'
  summary: 'Exploratory prototype; evidence will be added when stabilized.'
  category: other
  tags: ['Prototype']
  status: planned
  repoUrl: '{GITHUB_URL}'

Validation / Expected Outcomes​

  • pnpm registry:validate passes (no errors; warnings allowed for advisory checks)
  • pnpm build passes (registry validated during build)
  • New projects appear in pnpm registry:list

Failure Modes / Troubleshooting​

  • Invalid URL: Ensure placeholders resolve (check .env.local) or use absolute URLs.
  • Slug regex failure: Use lowercase, hyphenated slugs only.
  • Duplicate slug: Rename; slugs must be unique.
  • Evidence path warning: Prefix dossiers with projects/ or docs/60-projects/; include threat-model in threat model paths.

Best Practices​

  • Prefer short, stable slugs; avoid renames (renames are breaking).
  • Keep summary reviewer-friendly and factual (≥10 chars).
  • Populate keyProofs with concise capability claims tied to evidence.
  • Use placeholders for URLs so previews/prod stay aligned; avoid hardcoding hostnames.
  • When evidence is missing, set status to planned/active and add evidence paths as they become available.

Common Patterns​

  • Gold standard: isGoldStandard: true, rich evidence object, multiple ADR/runbook links, detailed techStack rationale.
  • Ongoing project: ongoing: true, missing endDate, status active or featured.
  • Evidence-light: minimal fields, status planned or active, repo placeholder + future evidence TODOs in dossier.

References​

  • ADR: ADR-0011: Data-Driven Project Registry
  • Implementation: Portfolio App src/lib/registry.ts, src/data/projects.yml, src/data/projects.ts
  • Scripts: pnpm registry:validate, pnpm registry:list