1MEIC02T1: Generate Architectural Diagrams - FEUP-MEIC-DS-2024-25/ai4sd GitHub Wiki

The goal of the product is to generate architectural diagrams from descriptions of architectural patterns collected in software repositories, enabling developers to easily visualize, understand, and refine software architectures based on documented patterns and best practices.

Vision

The product vision is to create a tool that empowers software development teams to automatically generate architectural diagrams from text descriptions of patterns found in software repositories. This tool will significantly streamline the process of understanding, designing, and maintaining complex software systems by reducing manual effort in creating and interpreting architectural diagrams.

By offering easy-to-use, AI-powered functionality, the tool ensures that software teams can spend less time on repetitive tasks and more on decision-making, enhancing productivity and clarity. It aims to bridge the gap between architecture description and visualization, allowing teams to focus on refining their designs rather than documenting them. The tool will also promote consistency by adhering to best practices when generating diagrams, thus ensuring that every team member and stakeholder has a clear understanding of the software architecture at any point in the development process.

In the long term, this tool will serve as a key asset in software development workflows, providing ongoing value as architectural patterns evolve and systems scale. The product will be adaptable to different types of repositories and patterns, making it an indispensable part of any modern software development toolkit.

Research

The following are examples of "similar" projects, analyzed in terms of their strengths and weaknesses compared to the envisioned product:

  • PlantUML

    • Pros: Open-source, widely used, integrates with many tools like GitLab, and offers text-based diagram creation.
    • Cons: Requires manual updates, which can be tedious for complex projects.

  • Structurizr

    • Pros: Automatically generates C4 diagrams, offers a SaaS platform, integrates with codebases.
    • Cons: Requires specific documentation structure to work, limiting flexibility.

  • Mermaid

    • Pros: Integrates well with markdown and documentation platforms like GitHub, automating visual documentation to an extent.

    • Cons: Still requires structured, domain-specific syntax. Lacks deep integration for software repository analysis and natural language processing.

  • Lucidchart

    • Pros: Highly flexible for creating diagrams and offers a user-friendly interface.
    • Cons: Not directly integrated with codebases, requires manual input.

  • Architexa

    • Pros: Provides seamless IDE integration for real-time architecture visualization. Includes features for interactive exploration and easy sharing, which improves collaboration among development teams.

    • Cons: Requires manual configuration for creating initial diagrams, limiting automation. Primarily designed for specific IDEs, which restricts flexibility for teams using other development environments or tools.

Compared to these projects, our product differentiates by focusing on converting unstructured natural language descriptions from repository documentation into meaningful, accurate diagrams, saving time and reducing manual overhead for developers, and such tools, according to our research, aren't available.

The main downside compared to some existing tools is that it may take longer to gather data to refine the model in order to recognize a wide range of architectural patterns.

Domain Analysis

Include high-level class diagram with key domain concepts. Complement this diagram with other high-level diagrams has appropriate (activity, sequence, etc.).

Architecture and design

Describe the architecture and design of the tool. Use component/deployment diagrams. If needed, resort to package diagrams to organize them into more manageable parts.

Be clear about what is the current architecture/design and what is the one you envision in the future, in case they are different. Identify main risks and justify the most important choices to show the soundness of the architecture and design that you have implemented or plan to implement.

Technologies

Identify the main technologies, languages and frameworks used. Clearly identify which ones were restrictions imposed by the client and which were your own choices. Justify your choices and explain in your own words the motivation for the restrictions of your client.

Explain the prototype or base implementation that you have implemented in Sprint 0, and how that has informed the rest of the development.

Development guide

Explain what a new developer to the project should know in order to develop the system, including who to build, run and test it in a development environment.

Document any APIs, formats and protocols needed for development (but don't forget that public APIs should also be accessible from the "How to use" above).

Describe coding conventions and other guidelines adopted by the team(s).

Security concerns

Identify potential security vulnerabilities classes and explain what the team has done to mitigate them.

Quality assurance

Describe which tools are used for quality assurance and link to relevant resources. Namely, provide access to reports for coverage and mutation analysis, static analysis, and other tools that may be used for QA.

How to use

Explain how to use your tool from an user standpoint. This can include short videos, screenshots, or API documentation, depending on what makes sense for your particular software and target users. If needed, link to external resources or additional markdown files with further details (please add them to this wiki).

How to contribute

Explain what a new developer should know in order to develop the tool, including how to build, run and test it in a development environment.

Defer technical details to the technical documentation below, which should include information and decisions on architectural, design and technical aspects of the tool.

Contributions

Link to the factsheets of each team and of each team-member. For example: