How nats-io/nats-architecture-and-design works
Project type and purpose
• This is a documentation‐driven, code‐generation utility for the NATS ecosystem’s Architecture Decision Records (ADRs).
• The Go program (main.go) reads a directory of ADR Markdown files, uses a template (adr-template.md), and regenerates the index in README.md. A GitHub Actions workflow validates ADR headers and regenerates the README on changes.
File structure
Top-level:
• .github/workflows/validate.yaml – CI pipeline for validating ADRs and regenerating README
• adr-template.md – template for ADR metadata and header
• adr/ – directory containing dozens of ADR-xx.md files and images
• main.go – Go CLI that reads ADRs + template and writes README.md
• README.md – generated index of all ADRs in categorized tables
• go.mod, go.sum – Go module config
• .readme.templ – possibly an alternate or legacy template
• ADR docs, GOVERNANCE.md, LICENSE, .gitignore
README for additional insights
• The README organizes ADRs by category (Client, JetStream, Server, etc.) with links.
Elements
– Clear labels: GitHub, CI Workflow, ADR Store, Template, Generator, Output.
• Orange for process steps (CI job)