# nats-io/nats-architecture-and-design architecture

> Architecture diagram of the GitHub repository nats-io/nats-architecture-and-design, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nats-io/nats-architecture-and-design
- Repository: https://github.com/nats-io/nats-architecture-and-design

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "Developer"
        Dev["Developer"]:::external
    end

    subgraph "CI Pipeline"
        CIwf["CI Workflow\nvalidate.yaml"]:::code
        CIproc["CI Job"]:::proc
    end

    subgraph "Repository (GitHub)"
        VC["Version Control\n.github/"]:::external
        Generator["Code Generator & Validator\nmain.go"]:::code
        GoMod["Go Module Config\ngo.mod\n go.sum"]:::code
        Template["ADR Template\nadr-template.md"]:::data
        Legacy["Legacy Template\n.readme.templ"]:::data
        ADRStore["ADR Store\nadr/"]:::data
        AdrImg["ADR Images\nadr/images/"]:::data
        Output["Output Artifact\nREADME.md"]:::data
    end

    %% Relationships
    Dev -->|Push ADRs/Template/Code| VC
    VC -->|On push/PR triggers| CIwf
    CIwf -->|Starts CI job| CIproc
    CIproc -->|Executes| Generator
    Generator -->|Reads template| Template
    Generator -->|Reads legacy template| Legacy
    Generator -->|Parses ADR files| ADRStore
    ADRStore --> AdrImg
    Generator -->|Uses modules| GoMod
    Generator -->|Generates index| Output
    CIproc -->|Validates headers| Generator
    Output -->|Committed back to| VC

    %% Click Events
    click VC "https://github.com/nats-io/nats-architecture-and-design/tree/main/.github/"
    click CIwf "https://github.com/nats-io/nats-architecture-and-design/blob/main/.github/workflows/validate.yaml"
    click Generator "https://github.com/nats-io/nats-architecture-and-design/blob/main/main.go"
    click GoMod "https://github.com/nats-io/nats-architecture-and-design/blob/main/go.mod"
    click GoMod "https://github.com/nats-io/nats-architecture-and-design/blob/main/go.sum"
    click Template "https://github.com/nats-io/nats-architecture-and-design/blob/main/adr-template.md"
    click Legacy "https://github.com/nats-io/nats-architecture-and-design/blob/main/.readme.templ"
    click ADRStore "https://github.com/nats-io/nats-architecture-and-design/tree/main/adr/"
    click AdrImg "https://github.com/nats-io/nats-architecture-and-design/tree/main/adr/images/"
    click Output "https://github.com/nats-io/nats-architecture-and-design/blob/main/README.md"

    %% Styles
    classDef code fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef data fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef proc fill:#FFECB3,stroke:#F9A825,color:#E65100;
    classDef external fill:#E0E0E0,stroke:#9E9E9E,color:#424242;
```
