Decision Catalog Architecture

A decision catalog is the index that makes individual ADRs discoverable. Without a catalog, ADRs accumulate in a directory and are found only by engineers who know to look. With a catalog, ADRs are searchable by system, by technology, by date, and by status. The catalog is the difference between documentation that exists and documentation that is used.

1. Index Structure Maintain a catalog index — a single file that lists every ADR with its number, title, status, date, and the systems it affects. The index is the entry point. An engineer looking for "why did we choose Kafka?" scans the index, finds ADR-023, and reads the full document. Without the index, they search the directory and hope the filename is descriptive.
2. Cross-References ADRs do not exist in isolation. ADR-023 chose Kafka. ADR-031 chose a specific partitioning strategy because of the Kafka choice. ADR-042 introduced a schema registry because of the partitioning strategy. Cross-reference related ADRs so the reader can follow the decision chain. The chain tells the story of the architecture's evolution.
3. System Tagging Tag every ADR with the systems it affects. ADR-023 affects the order processing system and the inventory system. When an engineer is about to modify the order processing system, they can filter the catalog by that tag and discover every architecture decision that constrains their work. Tags make ADRs proactive — the architect finds the relevant decisions before making changes, not after.