Abstract

As software systems increase in scale and complexity, architectural decisions must be transparent, traceable, and understandable to diverse stakeholders. However, traditional documentation approaches-such as standard Architectural Decision Records (ADRs)-often lack the structured rationale and contextual detail necessary to support informed analysis and long-term architectural stewardship. This paper presents the Software Architecture Explainability Framework (SAEF), a structured approach for enabling explainable architectural decision-making. Central to the framework is the Explainable Architectural Decision Record (ADR-E), which extends traditional ADRs with explicit rationale, structured stakeholder-oriented explanations, rejected alternatives, and traceability links grounded in explainability principles inspired by AI. SAEF was evaluated through two industrial case studies: the selection of Azure Kubernetes Service for container orchestration and the adoption of an enterprise-grade observability platform. Using a mixed-methods design combining workshops, scenario-based simulations, surveys, interviews, and operational metrics, the study found that ADR-E substantially improved transparency, traceability, and stakeholder alignment. Both cases reported a 30% reduction in mean time to resolution (MTTR) and transparency scores above 4.6/5. Overall, SAEF provides a practical and theoretically grounded foundation for explainable architectural decision-making. Future work will focus on tool support, graphical notations, and longitudinal assessments to enhance adoption and scalability.