RAD-AI: Rethinking Architecture Documentation for AI-Augmented Ecosystems

RAD-AI: Rethinking Architecture Documentation for AI-Augmented Ecosystems

Motivation and Problem Statement

The paper addresses a critical gap in software architecture documentation frameworks for AI-augmented ecosystems. Existing frameworks such as arc42 and C4 were conceived for deterministic software and systematically fail to accommodate the non-deterministic, data-dependent, and multi-lifecycle attributes of AI-enabled systems. This limitation extends beyond technical misalignment into the domain of regulatory risk, particularly with the enforcement of the EU AI Act (Regulation (EU) 2024/1689), which stipulates structured technical documentation of system architecture (Annex IV) that existing frameworks do not support. The authors identify regulatory compliance, documentation of emergent quality attributes (e.g., fairness, explainability), dual ML/software lifecycles, and data governance as unaddressed needs.

RAD-AI Framework: Extensions to Established Models

RAD-AI is introduced as a backward-compatible set of structured extensions targeting arc42 and C4, the two most widely adopted architecture documentation frameworks. RAD-AI augments arc42 with eight dedicated AI-centric sections and the C4 model with three diagrammatic extensions:

• arc42 Extensions:
  • AI Boundary Delineation for marking deterministic/probabilistic boundaries.
  • Model Registry View for first-class model components with versioning and metadata.
  • Data Pipeline View for end-to-end ML data flows and quality gates.
  • Responsible AI Concepts with structured matrices capturing fairness, explainability, human oversight, privacy, and safety for each AI component.
  • AI Decision Records (AI-ADR) incorporating justifications, alternatives, datasets, bias analysis, retraining triggers, and regulatory classification.
  • AI Quality Scenarios and AI Debt Register for operational and technical debt management.
  • Operational AI View detailing monitoring, retraining policy, deployment strategies, and rollback mechanisms.
• C4 Extensions:
  • Five AI component stereotypes (e.g., <<ML Model>>, <<Feature Store>>, <<Monitor>>).
  • Data Lineage Overlay tracing provenance, transformation, and privacy constraints.
  • Non-Determinism Boundary overlays partitioning the architecture.

Each extension explicitly targets a previously identified gap in the documentation of ML-enabled systems, with direct mapping to EU AI Act Annex IV categories.

Empirical Evaluation and Results

Three evaluation modalities are used:

• Regulatory Coverage Assessment: Six experienced software architects rate the addressability of EU AI Act Annex IV documentation demands under standard and extended frameworks. Standard arc42 and C4 yield mean coverage scores of 36% and 26% respectively. RAD-AI-augmented arc42 attains 93% average coverage; only training methodologies remain partially addressed, requiring supplementary artifacts beyond architecture documentation. Inter-rater reliability (Fleiss' $\kappa \approx 0.68$) confirms substantial agreement.
• Comparative Analysis on Production Platforms: Applying both baseline and extended frameworks to Uber Michelangelo and Netflix Metaflow demonstrates that all standard frameworks fail to capture core AI concerns (model lifecycle, data lineage, drift detection, non-determinism boundaries, experiment tracking), with coverage for 0/10 critical AI-specific concerns. RAD-AI extensions address eight fully and two partially in both systems, demonstrating that documentation gaps are structural, not domain-specific.
• Ecosystem Case Study: Documentation of a smart urban mobility ecosystem with multiple interconnected AI services reveals emergent properties only visible under RAD-AI: cascading drift across operator boundaries, differentiated compliance obligations, and federated AI governance. Responsible AI matrices and AI-ADR facilitate regulatory traceability and cross-component accountability.

Implications and Future Work

The research provides the first regulatory-anchored, backward-compatible extension to mainstream architecture documentation for AI-augmented systems. This directly operationalizes Annex IV requirements, giving practitioners a viable compliance path for the 2026 deadline without replacing current frameworks. The approach enables incremental adoption, allowing organizations to prioritize risk-specific documentation upgrades.

The theoretical implication is that modeling and documentation frameworks for software architecture must evolve to treat AI-specific properties—probabilistic boundaries, independent lifecycles, data/feature provenance, and emergent system-level attributes—as first-class concepts. The notion of 'documentation as code' must be expanded to accept components whose behavior mutates via non-code artefacts (models, data, hyperparameters) and is subject to continuous revalidation due to environmental drift and adversarial risk.

Potential future research includes extending RAD-AI for LLM-centric applications, automating compliance verification, and integrating with machine-readable documentation standards. Larger-scale empirical validation covering broader industrial domains and higher practitioner engagement are also necessary, particularly as harmonized standards (e.g., prEN 18286) emerge.

Conclusion

The inadequacy of deterministic-era architecture documentation frameworks for AI-augmented systems is empirically and regulatorily substantiated. RAD-AI closes the gap through minimal, structured extensions to arc42 and C4, drastically improving the addressability of regulatory and quality requirements. The framework's design is compatible with current industrial practice and addresses both practical (compliance, operational governance) and theoretical (documentation expressivity, epistemic robustness) needs. RAD-AI’s extensibility and evidence-driven mapping position it as a pivotal foundation for architecture documentation in AI-governed, multi-component ecosystems (2603.28735).