RAD-AI: Rethinking Architecture Documentation for AI-Augmented Ecosystems
Organizations: SDU Software Engineering, University of Southern Denmark, Odense, Denmark
Abstract
AI-augmented ecosystems (interconnected systems where multiple AI components interact through shared data and infrastructure) are becoming the architectural norm for smart cities, autonomous fleets, and intelligent platforms. Yet the architecture documentation frameworks practitioners rely on, arc42 and the C4 model, were designed for deterministic software and cannot capture probabilistic behavior, data-dependent evolution, or dual ML/software lifecycles. This gap carries regulatory consequence: the EU AI Act (Regulation 2024/1689) mandates technical documentation through Annex IV that no existing framework provides structured support for, with enforcement for high-risk systems beginning August 2, 2026. We present RAD-AI, a backward-compatible extension framework that augments arc42 with eight AI-specific sections and C4 with three diagram extensions, complemented by a systematic EU AI Act Annex IV compliance mapping. A regulatory coverage assessment with six experienced software-architecture practitioners provides preliminary evidence that RAD-AI increases Annex IV addressability from approximately 36% to 93% (mean rating) and demonstrates substantial improvement over existing frameworks. Comparative analysis on two production AI platforms (Uber Michelangelo, Netflix Metaflow) captures eight additional AI-specific concerns missed by standard frameworks and demonstrates that documentation deficiencies are structural rather than domain-specific. An illustrative smart mobility ecosystem case study reveals ecosystem-level concerns, including cascading drift and differentiated compliance obligations, that are invisible under standard notation.
Figures & tables
| Work | Contribution | Limitation | Type |
|---|---|---|---|
| Moin et al. [ 10 ] | Expert survey (61); ISO 42010 lacks AI viewpoints | No concrete framework extensions | Survey |
| Nazir et al. [ 9 ] | 35 challenges, 42 best practices for ML arch. | Decision catalogs, not doc. structures | SLR |
| Indykov et al. [ 11 ] | 16 architectural tactics, 85 quality trade-offs | Tactics not mapped to doc. templates | SLR |
| Amou Najafabadi et al. [ 12 ] | 35 MLOps architecture components | System mapping, not doc. framework | SMS |
| Mitchell et al. [ 13 ] | Model Cards for model-level reporting | Standalone; not integrated into arch. docs | Artifact |
| Sidhpurwala et al. [ 38 ] | HASC: system cards with ASH IDs | Standalone governance; no fwk. integration | Artifact |
| Field | Value |
|---|---|
| Title | Use GBT for route optimization |
| Status | Accepted |
| Context | Route optimization requires explainable predictions for public-service accountability |
| Decision | XGBoost (gradient-boosted trees) |
| Consequences | +Explainability, +Fast inference; Lower sequence modeling capacity |
| Model alternatives | XGBoost, LSTM, linear regression |
| Ext. | Name | Extends arc42 Section | Key Artifact | Gap |
|---|---|---|---|---|
| E1 | AI Boundary Delineation | §3 Context & Scope | Annotated context diagram with AI boundaries | G1, G2 |
| E2 | Model Registry View | §5 Building Block View | Model registry table + annotated diagram | G1, G5 |
| E3 | Data Pipeline View | §6 Runtime View | Data pipeline diagram with quality gates | G1, G5 |
| E4 | Responsible AI Concepts | §8 Cross-Cutting Concepts | Responsible AI concern matrix | G1 |
| E5 | AI Decision Records | §9 Architecture Decisions | AI-ADR template (7 AI-specific fields) | G4 |
| E6 | AI Quality Scenarios | §10 Quality Requirements | AI quality scenario table | G1 |
| Ext. | Name | Key Artifact | Gap |
|---|---|---|---|
| C4-E1 | AI Component Stereotypes | 5 new C4 stereotypes | G2 |
| C4-E2 | Data Lineage Overlay | Provenance overlay diagram | G2, G5 |
| C4-E3 | Non-Determinism Boundary | Boundary partition diagram | G2 |
| # | Annex IV Category | RAD-AI Section(s) |
|---|---|---|
| 1 | General description | arc42 §1, §3 + E1 (AI Boundary) |
| 2 | System elements | §5 + E2 (Model Registry) |
| 3 | Design & architecture | §5–7 + C4-E1 (AI Stereotypes) |
| 4 | Data governance | E3 (Data Pipeline) + C4-E2 (Data Lineage) |
| 5 | Training methods | E5 (AI-ADR) + supplementary |
| 6 | Risk management | §11 + E7 (AI Debt Register) |
| Annex IV Requirement Category | arc42 | C4 | RAD-AI arc42 | RAD-AI C4 |
| 1. General system description | 2 | 1 | 2 | 2 |
| 2. System elements & development process | 1 | 1 | 2 | 2 |
| 3. Design specifications & architecture | 1 | 1 | 2 | 2 |
| 4. Data & data governance | 0 | 0 | 2 | 1 |
| 5. Training methodologies & techniques | 0 | 0 | 1 | 1 |
| 6. Risk assessment & management | 1 | 0 | 2 | 1 |
| AI-Specific Architectural Concern | Uber std. | Uber RAD-AI | Netflix std. | Netflix RAD-AI |
| Model versioning & lifecycle management | ✓ | ✓ | ||
| Feature store architecture & sharing | ✓ | ✓ | ||
| Data pipeline with quality gates | ✓ | ✓ | ||
| Drift detection & monitoring | ✓ | ✓ | ||
| Retraining triggers & automation | ✓ | ✓ | ||
| Non-deterministic behavior boundaries | ✓ | ✓ |