Skip to content

docs(arc42): migrate to section-folder structure (one folder per chapter) #27

Description

@reneleban

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation onlypriority: mediumImportant but not blocking

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions