Architecture Decision Records
Single Source of Truth
This page is automatically copied from docs/adr/README.md in the repository.
Edit the source file to update this page.
Architecture Decision Records (ADR)
This ADR overview describes the main architectural decisions for the remark-kroki-a11y codebase. Each ADR documents a choice, context, alternatives, and consequences, following the format by Michael Nygard (2011) with some additions.
Format used
Each ADR contains the following sections:
- Status
- Context
- Options (our addition)
- Decision
- Consequences
- Actions (if applicable)
- References (our addition, APA style per HAN)
Deviations from Nygard's original format:
- Options: We explicitly add an 'Options' section to list and motivate alternatives considered, for clarity and traceability.
- References: We use a 'References' section at the end, formatted in APA style as prescribed by HAN guidelines (HAN APA reference guide).
See: Nygard, M. (2011). Documenting architecture decisions.
ADR overview
| ADR | Title | Status |
|---|---|---|
| 0000 | Deterministic parsing vs live LLM | Accepted |
| 0001 | Relation direction and bijectivity | Accepted |
| 0002 | Plugin architecture | Accepted |
| 0003 | Project language (English) | Accepted |
| 0004 | Integrated test Docusaurus site | Accepted |
| 0005 | Navigable a11y descriptions | Accepted |
| 0006 | PlantUML as internal standard | Accepted |
| 0007 | Single source of truth for documentation | Accepted |
| 0008 | Test strategie met Storybook en Playwright | Accepted |
| 0009 | No automatic step numbering in activity diagram descriptions | Accepted |
| 0010 | Screenreader prosody and visual hierarchy | Pending |
| 0011 | Faithful representation of diagram source | Accepted |
| 0012 | Replace archived remark-kroki-plugin dependency | Pending |
| 0013 | Internationalization (i18n) framework | Pending |
Last update: 2026-02-09