MAAdvisor: Multi-Agent Architecture Advisor
- MAAdvisor is a multi-agent advisory system that automates software architecture design by assigning specialized roles like Analyst, Modeler, Designer, and Evaluator.
- It integrates retrieval-augmented generation to infuse authoritative architectural knowledge into requirement analysis, modeling, and iterative design documentation.
- Empirical findings demonstrate that MAAdvisor delivers comprehensive 4+1 views, detailed documentation, and robust ATAM evaluations while addressing limitations of single-agent approaches.
MAAdvisor is an envisioned multi-agent advisor for software architecture design, distilled from the MAAD line of work on knowledge-driven multi-agent collaboration for requirements interpretation, architecture modeling, design documentation, and evaluation (Li et al., 28 Jul 2025). In this usage, MAAdvisor denotes a role-structured advisory system that mirrors the traditional architecture process through specialized agents, retrieval-augmented architectural knowledge, iterative artifact exchange, and evaluation loops grounded in requirements traceability and ATAM-style assessment.
1. Conceptual basis and scope
The conceptual basis of MAAdvisor lies in the Knowledge-Based Multi-Agent Architecture Design framework, which maps the major activities of software architecture design to specialized roles: requirement analysis, style and technology selection, detailed design, and evaluation (Zhang et al., 26 Mar 2025). The later MAAD framework operationalizes this pattern as a knowledge-driven Multi-Agent System (MAS) with four specialized agents—Analyst, Modeler, Designer, and Evaluator—and provides the main empirical foundation for a software-architecture-oriented MAAdvisor (Li et al., 28 Jul 2025).
This framing responds to a specific problem definition. Architecture design is described as high-abstraction and knowledge-intensive, requiring deep domain expertise, development experience, architectural knowledge, trade-off analysis across quality attributes such as performance, security, and maintainability, and adaptation to evolving requirements. The source material further identifies ambiguity in requirements, cognitive overload, reliance on tacit knowledge, and limited exploration of alternatives as recurring obstacles, especially under agile development pressures. It also notes that single-agent LLM approaches often yield unreliable, inconsistent outcomes and hallucinations on multi-step collaborative reasoning tasks (Li et al., 28 Jul 2025).
Within that context, MAAdvisor is not merely a diagram generator. Its intended scope spans requirement decomposition, multi-view architectural modeling, detailed documentation, executable prototype scaffolding, and post hoc evaluation. A plausible implication is that the advisor is meant to function as a structured architecture workbench rather than as a narrow drafting assistant.
2. Agent organization and artifact flow
The recommended MAAdvisor organization follows a four-agent pattern. Each agent consumes explicit artifacts and emits new ones for downstream use.
| Agent | Inputs | Outputs |
|---|---|---|
| Analyst | SRS | FR, NFR, ASR, DC |
| Modeler | Analyst artifacts, retrieved knowledge | “4+1” architecture views |
| Designer | Analyst artifacts, architecture views, retrieved knowledge | Detailed architecture documentation, prototype skeleton |
| Evaluator | SRS, views, documentation | ATAM Evaluation Report, Mismatch Analysis Report |
The Analyst parses and structures the Software Requirements Specification, identifies and filters Architecturally Significant Requirements, classifies requirements into Functional Requirements and Non-Functional Requirements, and extracts Design Constraints. The Modeler then consumes ASR, FR, NFR, and DC; prioritizes NFRs to facilitate quality-attribute trade-offs; selects technology stacks aligned with constraints; identifies architectural styles and patterns; and produces Kruchten’s “4+1” architecture view models. The Designer interprets those views, bridges modeling and implementation, defines interfaces and protocols, documents decisions and rationale, and generates code skeletons. The Evaluator assesses structural and behavioral diagrams, deployment specifications, and architectural documentation against ASRs and constraints, then performs mismatch analysis through requirements traceability matrices (Li et al., 28 Jul 2025).
The orchestration workflow is a pipeline: SRS to Analyst artifacts; Analyst artifacts to multi-view “4+1” blueprints; blueprints to detailed architecture documentation and prototype scaffolding; then evaluation through ATAM and mismatch analysis. If mismatches are found, the Evaluator collaborates with upstream agents to resolve them and update artifacts before final delivery. The synthesis explicitly recommends that MAAdvisor maintain an artifact pool and a traceability matrix connecting FR, NFR, ASR, and DC to architecture elements and evaluation findings (Li et al., 28 Jul 2025).
This workflow makes traceability a first-class design object. Rather than treating evaluation as a separate audit phase, the Evaluator closes the loop by driving corrective iterations.
3. Knowledge grounding and prompting regime
A defining characteristic of the proposed MAAdvisor is knowledge infusion through Retrieval-Augmented Generation. The cited knowledge sources are authoritative literature, private knowledge bases, architectural styles and patterns, and the ATAM evaluation framework. The source synthesis names Software Architecture in Practice, 3rd and 4th editions, as authoritative literature; layered architecture and component-and-connector style as thematic categories in the vectorized knowledge base; and ATAM, specifically CMU/SEI-2000-TR-004, as the evaluation framework (Li et al., 28 Jul 2025).
The knowledge base is vectorized and thematically segmented. For both the Modeler and the Designer, similarity search retrieves the top three most relevant text segments per task. The rationale given for top-3 retrieval is that it balances relevance with conciseness and reduces verbosity and hallucination risk. The synthesis recommends carrying this pattern into MAAdvisor, while also suggesting adaptive retrieval sizes such as 3–5 based on task complexity. This suggests a retrieval strategy tuned to role-specific context budgets rather than a single global prompt template.
The prompting regime is equally structured. The Analyst’s ASR extraction prompt enforces explicit criteria: architectural significance, critical quality attributes, and cross-component coordination. The Modeler’s Process View prompt requires Activity, Sequence, and Collaboration diagrams in valid PlantUML syntax. The Designer’s architecture documentation prompt requires seven sections: Goals, Detailed Architecture Design, Component Connector Specifications, Key Technologies, Design Decisions, Design Decision Rationale, and Executable Prototype Skeleton. The Evaluator’s mismatch report prompt structures output as repeated Description, Impact, and Recommendation blocks (Li et al., 28 Jul 2025).
PlantUML visualization is integrated in MAAD, and the MAAdvisor guidance recommends requiring PlantUML or C4-like syntax and validating syntax automatically. In practice, this turns diagram production into a constrained code-generation task rather than free-form prose generation.
4. Architectural artifacts and evaluation apparatus
The artifact model is unusually broad. The “4+1” views consist of Logical, Development, Process, Physical, and Scenario views. Within those views, the system generates Class, Object, and State diagrams; Package and Component diagrams; Activity, Sequence, and Collaboration diagrams; Deployment and Container diagrams; and a Use Case diagram. The accompanying architecture documentation includes goals, components, modules, subsystems, interactions, interfaces, protocols, error handling, performance thresholds, reliability constraints, key technologies, design decisions, rationale, trade-offs, alternatives, and an executable prototype skeleton (Li et al., 28 Jul 2025).
The evaluation apparatus has two principal outputs. The ATAM Evaluation Report covers quality-attribute scenario evaluation, strengths, weaknesses, risks, and trade-offs. The Mismatch Analysis Report diagnoses discrepancies between the architecture and the SRS through traceability, categorizes and quantifies mismatches, and provides recommendations. The paper also states that the Evaluator performs completeness and consistency checks and that artifacts are iteratively updated where necessary (Li et al., 28 Jul 2025).
The main case-study example is the Space Fraction System, an interactive web-based educational platform for sixth-grade students featuring gamified fraction arithmetic, immediate feedback, and score tracking. The synthesis reports that, with external knowledge, component diagrams showed interface-driven modularity with contracts such as IUserInteraction, IScoring, IStoryline, and IQuestionManagement, together with clearer separation of concerns. Without external knowledge, the diagrams emphasized functional execution flow and runtime aspects and were less abstracted (Li et al., 28 Jul 2025).
The experimental setup positions MetaGPT as a baseline. In that comparison, MAAD executes the full pipeline from SRS to “4+1” views, architecture document, ATAM evaluation, and mismatch analysis, whereas MetaGPT yields SRS-like artifacts, Mermaid class and sequence diagrams, a brief implementation approach, and a JSON technical solution. PlantUML is used to visualize both systems’ UML outputs (Li et al., 28 Jul 2025).
5. Empirical findings relevant to MAAdvisor
The empirical results most directly relevant to MAAdvisor concern coverage, grounding, and evaluation quality. In requirements analysis, MAAD’s Analyst produced 6 functional requirement categories encompassing 21 detailed requirements, plus 11 non-functional requirements and 8 architecture-related requirements, whereas the MetaGPT baseline prioritized five top requirements and did not categorize requirements. In modeling, MAAD generated complete “4+1” views, while MetaGPT produced only class and sequence diagrams. In documentation, MetaGPT’s JSON technical solution contained null fields in practice, including Required Python Packages and Full API Spec, whereas MAAD produced explicit decisions, rationale, and prototype scaffolding. In evaluation, MAAD provided ATAM and mismatch reports, while MetaGPT lacked an evaluation mechanism (Li et al., 28 Jul 2025).
Knowledge infusion had a more nuanced effect. The source synthesis reports that external knowledge from Software Architecture in Practice produced more modular, interface-driven component diagrams aligning with best practices, but that the mismatch rate in the Space Fraction System remained identical with and without external knowledge, at 0.188. The explanation offered in the source is twofold: the general architectural competence of the base LLMs and the lack of domain-specific educational-software content in the knowledge base (Li et al., 28 Jul 2025).
The LLM selection study is particularly significant for an advisor design. GPT-4o, DeepSeek-R1, and Llama 3.3 all produced functionally plausible architectures, but with different emphases. GPT-4o produced logical component dependencies, detailed interface contracts, and internal structures; DeepSeek-R1 emphasized deployment and runtime detail with explicit client, server, and database artifacts; Llama 3.3 produced streamlined high-level subsystems and data flows. GPT-4o and Llama 3.3 each had 6 mismatches and a mismatch rate of 0.188, while DeepSeek-R1 had 10 mismatches and a mismatch rate of 0.313. The paper notes this as a 66% drop in requirements alignment for DeepSeek-R1 relative to GPT-4o and Llama 3.3 in the Space Fraction System case (Li et al., 28 Jul 2025).
Industrial feedback across 11 requirements specifications reinforces both the promise and the limits of the design. Praises centered on correctness, the value of mismatch reports, and the usefulness of knowledge-driven grounding. Criticisms focused on trustworthiness and explainability, especially in safety-critical domains; questionable NFR-to-quality-attribute associations; omission of detailed UML descriptions and entity relationships; and granularity and complexity below industrial standards. The architects’ recommendations included specialized LLMs per agent role, memory mechanisms, reuse of prior architectures across similar business scenarios, and output-format improvements such as Markdown (Li et al., 28 Jul 2025).
6. Limitations, implementation concerns, and nomenclature
Several limitations define the present boundary of MAAdvisor as described in the source synthesis. No pseudocode for orchestration is provided. No quantitative utility functions for quality-attribute scoring are reported; ATAM outputs remain qualitative. No explicit cost or latency analysis is given, and no orchestration framework details such as LangChain or another agent platform are specified. The knowledge base lacks domain-specific content for the educational-software case study, architecture quality remains inherently subjective, and generalizability to highly complex industrial systems is explicitly treated as limited (Li et al., 28 Jul 2025).
Implementation guidance therefore emphasizes engineering discipline around artifacts and provenance rather than algorithmic novelty alone. The synthesis recommends artifact repositories and traceability matrices from the outset; structured prompts for all agents; a vector database seeded with both general architectural references and domain-specific sources; an Evaluator agent that emits ATAM and mismatch reports and triggers feedback loops; and “human-in-the-loop” validation and sign-off to address subjectivity, tacit knowledge, and trustworthiness concerns. The replication package is reported as available at https://github.com/RuiyinL/MAAD (Li et al., 28 Jul 2025).
A common misconception is that multi-agent automation removes the need for architectural judgment. The practitioner feedback in the source argues the opposite: automation can accelerate decomposition, documentation, and traceable evaluation, but it does not eliminate explainability problems, domain-grounding gaps, or the need for expert review, particularly in safety-critical settings.
The term “MAAdvisor” is also used elsewhere in the literature for a different system: a zero-shot LLM-based index advisor for database management systems that decomposes index recommendation into planning, selection, combination, revision, and reflection (Li et al., 22 Aug 2025). This suggests that the label has evolved into a broader naming pattern for multi-agent advisory systems, but in the software-architecture context its meaning is anchored in the MAAD-derived blueprint for knowledge-driven architecture design and evaluation.