Add an architectural decision log using MADR

[madurangasiriwardena]

Purpose

ThunderID has no decision log. Design reasoning currently lives in GitHub Discussions, pull request threads, and, for older decisions, internal mail threads that external contributors cannot read at all. The result is that rejected proposals resurface, and a deliberate deviation from a specification is indistinguishable from an oversight.

This PR introduces docs/adrs/ as the decision log, adopting MADR 4.0.0 as the format. It records that choice as the first record, ADR-0000, so the log opens by explaining itself.

Nothing in the runtime changes. This is documentation plus CI wiring.

Approach

The log. docs/adrs/README.md documents when a record is required (wire-visible contracts, deliberate spec deviations, persistence schema or storage strategy, runtime dependencies, cross-cutting patterns), the propose and accept process, the rule that accepted records are immutable and are changed only by superseding them, and flat numbering. adr-template.md is the MADR 4.0 template with status pre-filled so a copied record starts valid. The README deliberately references no specific table, package or subsystem, so it does not need editing as the code around it changes.

Enforcement rather than convention. A partially adopted log is worse than none, because readers infer that an undocumented decision was never deliberately made. Three mechanisms rather than good intentions:

• A CODEOWNERS entry on docs/adrs/, so every record gets architectural review.
• A ### Related ADRs section and a checklist item in the pull request template. The item is phrased as checked whether an ADR is required rather than wrote an ADR, so a contributor whose change needs no record can still tick it truthfully. A box only some contributors can tick is a box everyone learns to ignore.
• .github/workflows/adr-lint.yml, which runs markdownlint over the directory and then checks the NNNN-title-with-dashes.md filename pattern, that status holds a recognized value, that each record has an index row whose Status column agrees with its front matter, and that numbers are unique.

Lint scoping. Records are not docs/content pages and cannot satisfy those conventions, so scripts/docs-lint.sh and .vale.ini exempt the directory. docs/adrs/** is also excluded from the docs paths filter in pr-builder.yml, because the Docusaurus content root is docs/content and an ADR-only change has no site to build.

Two notes for reviewers:

• adr-lint.yml uses pnpm dlx, not npx. The root package.json pins pnpm through devEngines, which makes npm refuse to run npx anywhere in this repository.
• The workflow filters pull_request on docs/adrs/** with an unfiltered merge_group, matching docs-style-check.yml. If it is ever made a required check in branch protection, PRs that do not touch docs/adrs/ will wait on a status that never reports.

Related Issues

• N/A

Related PRs

• N/A

Related ADRs

• ADR-0000: Use MADR for architectural decision records. Introduced by this PR.

Checklist

• Followed the contribution guidelines.
• Checked whether this change requires an ADR; if so, it is linked under Related ADRs.
• Manual test round performed and verified.
• Documentation provided. (Add links if there are any)
  • Ran Vale and fixed all errors and warnings
• Tests provided. (Add links if there are any)
  • Unit Tests
  • Integration Tests
• Breaking changes. (Fill if applicable)
  • Breaking changes section filled.
  • breaking change label added.

Security checks

• Followed secure coding standards in WSO2 Secure Coding Guidelines
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}