Seed System

Idempotent, Round-Trippable Seeding

A shared tsx/CSV pipeline scaffold seeds content from version-controlled CSVs via the Payload Local API — idempotent, validated, and round-trippable — and the same scaffold bakes the 400-node graph offline without ever touching the database.

  • Platform
  • Product Engineering
  • Developer Tooling
  • Headless CMS
  • PostgreSQL
  • TypeScript
  • System Design

Overview

  • A portfolio's data has to live somewhere reviewable. Hand-entering keywords in a CMS means they exist only in a database — invisible to git, lost on a reseed, impossible to diff in a PR. So the seed system makes CSVs the source of record: keywords.csv and the graph's nodes.csv / edges.csv are the SSOTs, and small tsx scripts parse, validate, and upsert them through Payload's Local API.

  • The design problem underneath is idempotency and drift. A seed script you can only run once is a liability; this one upserts by an immutable key, so re-running is safe and never duplicates. And because the CMS is also a nice editor, a reverse export keeps the CSV authoritative — edit anywhere, commit the CSV, a wipe-and-reseed can’t lose anything.

  • What ties it together is a single shared scaffold — one RFC-4180 parser, one tsx ESM bootstrap (forced by a Node 24 quirk), one validate-before-write discipline. The mental-graph builder reuses that scaffold functionally while deliberately not reusing the CMS — graph topology is miserable in a form UI, so it stays a committed static artifact.

System Design