Add Architecture Documentation Section

[mgajek-cern]

Problem

Important architectural decisions and design documentation lack formal organization, causing:

• Lost context over time
• Repeated discussions on settled topics
• Difficult onboarding for new contributors
• Scattered architectural information

Solution Options

Option A: ADRs Only

docs/
├── architecture-decisions/
│   ├── 0001-use-adrs.md
│   └── README.md

Option B: Comprehensive Architecture Section

docs/
├── architecture/
│   ├── decisions/           # ADRs
│   │   ├── 0001-use-adrs.md
│   │   └── README.md
│   ├── design/              # System design docs
│   │   ├── data-flow.md
│   │   └── component-overview.md
│   ├── rfcs/                # Request for Comments
│   └── README.md

Recommendation: Option B

A dedicated architecture section provides:

• Centralized location for all architectural content
• Room for growth (RFCs, design docs, patterns)
• Better organization as project scales
• Clear separation from user guides

Initial Content

• ADR template and process
• System architecture overview
• Component interaction diagrams
• Decision history for major choices

Tasks

• Create architecture section structure
• Write initial ADR about this approach
• Update Docusaurus navigation
• Migrate existing architectural content

[rdimaio]

Interesting concept. Found some more info here https://adr.github.io/