Skip to main content

architecture overview

declared-md is five components that work together without a shared database or server.

components​

spec (declared-md/spec)​

the normative source. contains:

  • whoami.md, whois.md, whatis.md -- the human-readable specifications
  • shared.md -- rules that apply to all three
  • schemas/ -- JSON Schema draft-07 for each standard
  • examples/ -- full example files for each standard
  • CHANGELOG.md

no build step. no code. just markdown and JSON.

validator (declared-md/validator)​

a Node.js CLI that implements the spec. provides init, validate, and preview commands. uses AJV to validate frontmatter against the JSON schemas.

published as declared-md on npm. used by authors to validate files before publishing.

indexer (declared-md/index)​

a GitHub Action that crawls public GitHub repositories for declared-md files, validates them, deduplicates them, and writes the results to data/*.json in the same repo.

runs on workflow_dispatch. a daily schedule can be enabled. stores only validated, deduplicated profiles.

directory site (declared-md/site)​

a static Astro site that fetches data/*.json from the indexer repo at build time and generates public directory pages at declared-md.github.io.

no server. no database. rebuilds from the JSON on each deploy.

docs site (declared-md/docs)​

this site. a Docusaurus 3 site with technical documentation. contains mirrors of the spec content, CLI reference, architecture explanations, and FAQ.

key design constraint​

no shared state. no central database. no server. the system is:

  • spec: git-versioned markdown
  • index: git-versioned JSON derived from public repos
  • site: static HTML generated from the JSON at build time
  • docs: static HTML generated from markdown at build time

if any component disappears, the others continue to work. if the indexer stops running, the last indexed data remains available. if the site goes down, the JSON is still in the index repo. if the JSON is deleted, a new crawl rebuilds it.