User Story (IREB)
As a contributor reading the architecture documentation,
I want each arc42 chapter to live in its own folder with a README.md and dedicated sub-pages,
so that I can navigate large chapters without scrolling through monolithic files
and add chapter-specific assets (diagrams, snippets) without polluting the chapter root.
Context
After the docs-conventions cleanup PR, arc42 lives at docs/architecture/ with flat files (01-introduction.md, …, 12-glossary.md). Internal documentation conventions prescribe section folders (01_introduction_and_goals/README.md) to allow chapter-local sub-pages and assets.
Acceptance Criteria
- AC-1: Each chapter (1–12) is migrated from
docs/architecture/NN-name.md to docs/architecture/NN_name/README.md.
- AC-2: Folder names use
snake_case_with_leading_zero per arc42 standard (e.g. 01_introduction_and_goals, 09_architecture_decisions).
- AC-3: ADRs are moved from
docs/decisions/ to docs/architecture/09_architecture_decisions/ (consolidating ADR location with arc42 chapter 9).
- AC-4: All cross-references in
README.md, CLAUDE.md, CHANGELOG.md, source comments, and other arc42 chapters are updated.
- AC-5:
docs/architecture/README.md index reflects the new structure.
- AC-6: No broken markdown links — verified by
grep -r '](docs/architecture/' . returning only valid paths.
Out of Scope
- Splitting chapter content into sub-pages (this issue only restructures, content stays).
- IREB requirements migration (tracked separately).
User Story (IREB)
As a contributor reading the architecture documentation,
I want each arc42 chapter to live in its own folder with a
README.mdand dedicated sub-pages,so that I can navigate large chapters without scrolling through monolithic files
and add chapter-specific assets (diagrams, snippets) without polluting the chapter root.
Context
After the docs-conventions cleanup PR, arc42 lives at
docs/architecture/with flat files (01-introduction.md, …,12-glossary.md). Internal documentation conventions prescribe section folders (01_introduction_and_goals/README.md) to allow chapter-local sub-pages and assets.Acceptance Criteria
docs/architecture/NN-name.mdtodocs/architecture/NN_name/README.md.snake_case_with_leading_zeroper arc42 standard (e.g.01_introduction_and_goals,09_architecture_decisions).docs/decisions/todocs/architecture/09_architecture_decisions/(consolidating ADR location with arc42 chapter 9).README.md,CLAUDE.md,CHANGELOG.md, source comments, and other arc42 chapters are updated.docs/architecture/README.mdindex reflects the new structure.grep -r '](docs/architecture/' .returning only valid paths.Out of Scope