MArc is a multi-agent system for software architecture, designed to facilitate the development of complex software systems through the use of specialized AI agents. It automates the process of creating, reviewing, and documenting software architecture based on a given project description.
MArc employs a team of autonomous agents that collaborate to perform an iterative architecture design process. The system takes a project description as input, analyzes requirements, designs the architecture through an iterative process, and generates comprehensive documentation, including Architecture Decision Records (ADRs) using the arc42 template.
The workflow is coordinated by a Team Leader Agent, which guides the other agents through the process, from understanding the initial requirements to producing the final, approved architecture documentation.
The system is composed of the following agents, each with a specific role:
- Team Leader Agent (TLA): Coordinates the entire process, managing the workflow and communication between all other agents.
- Requirements Analyst Agent (RAA): Analyzes the project description to identify and document Architecturally Significant Requirements (ASRs).
- Architecture Design Agent (ADA): Creates the architecture design based on the ASRs, choosing appropriate patterns and defining components.
- Architecture Review Agent (ARA): Critically reviews the architecture design to ensure it meets requirements and identifies potential risks or weaknesses.
- ADR & Documentation Generation Agent (ADGA): Documents the approved designs and decisions, creating ADRs and filling out the arc42 template.
This project is configured as a devcontainer with all dependencies pre-installed. To get started:
- Create the
APIKEY.envfile (see step 2 below) - Open the project in VS Code
- When prompted, select "Reopen in Container" to load the devcontainer
- All required dependencies are already installed and ready to use
The system requires API keys for the language models it uses. Create a file named APIKEY.env in the root directory and add your API keys in the following format:
GEMINI_API_KEY_1="YOUR_GEMINI_API_KEY"
GEMINI_API_KEY_2="YOUR_GEMINI_API_KEY"
OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
Place your project description file (in Markdown format) in the workspace/projects/ directory. The system will use this file as the primary input. For example: workspace/projects/project-1.md.
To start the multi-agent system, run the following command in your terminal:
langgraph dev --allow-blockingThis will start the LangGraph development server and the agents will begin their work. You can monitor the process in the terminal and see the output files being generated in the workspace/architectures/ directory.
After starting the server, you will be prompted to enter a message. This is where you provide the initial instruction for the agent team.
Example Prompt:
Create an architecture for the project described in the 'projects/project-X.md' file. Work fully autonomously and don't ask any questions.
Make sure to replace project-X.md with the actual name of your project description file.
The runs/ folder contains comprehensive execution results from testing the MArc system with different language models and projects. These results include:
- Architecture Documentation: Complete arc42 documentation generated by the multi-agent system
- Conversation Logs: Detailed records of agent interactions during the architecture design process
- Generated Diagrams: PlantUML diagrams and their visual representations
- Performance Metrics: Character counts and analysis of generated content
The runs are organized by language model (OpenAI o3 vs o4-mini) and tested across multiple projects to enable comparative analysis of architecture quality, consistency, and content generation capabilities.
For detailed information about the structure and contents of execution results, see the Runs Folder Documentation.