1MEIC02T04: Archy - FEUP-MEIC-DS-2024-25/ai4sd GitHub Wiki

Our tool aims to analyze local data such as commit logs and documentation in software repositories and infer which patterns are present in source code.

More details about the product should be found here below, including the product vision, market research and domain analysis.

Vision

In modern software development, the need to read the documentation of an unfamiliar project can take a long time, especially in large codebases that often have architectures that could be easier to understand. Critical insights are often spread in various files – text documentation, and commit logs – making it difficult to have a coherent architectural overview. As a result, teams face slow onboarding processes, a lack of insight into structural dependencies, growing technological debt, and a higher chance of mistakes and ineffective teamwork.

However, there is always a light at the end of the tunnel. In this case, that light is Archy a powerful VSCode extension that with the click of a button automatically infers architectural patterns by parsing through the project’s documentation and scraped commit logs. This extension is designed to transform how developers and teams understand, explore, and interact with their code’s architecture, making it easier to maintain, and refactor complex projects.

Archy offers a unique opportunity to tap into the developer tools market with a differentiated, high-value product that directly addresses widespread challenges in the current software development space.

Research

During the development of the product we didn't find any specific tool that manages to do what we are aiming to perform. Most of the applications help in the construction of documentation in a more standard way by providing templates, analyze only multiple types of documentation or can only infer the architecture from existing code. Such tools found were:

  • GitHub analytics and GitHub insights - Helps analyze commit logs and provides metrics about cycles of development and activity but doesn't give insight in architectural patterns

  • docAnalyzer.ai - This is a broader tool, that applies to all types of documents and provides an AI-powered analyzes. While our tool focus only on the software architecture and can provide a more focused querys to the AI agent.

  • MAXQDA - This tool excels in pattern recognition, statistical analysis and visual data representations. Since it lacks the direct use of an AI assistance that allows the automation of the process.

Domain Analysis

Class Diagram

class_diagram

Sequence Diagram

sequence_diagram

Activity diagram

Activity diagram

Architecture and design

Architecture and design

To create the prototype as fast as possible, we developed it with the backend logic glued with the VSCode extension user interface. Still, we intend to change it to be separated in order to adapt to a microservices format.

Technologies

We selected Node.js and TypeScript as our primary technologies, due to the restrictions associated with creating a VSCode Extension: they require these environments to integrate with the editor, making them essential choices.

In Sprint 0, we developed a base implementation of the extension, focusing on essential functionality: fetching commit logs from the user's workspace and sending them to Gemini, which processes those logs to infer architectural patterns, which are then outputted in a Markdown file for easy review within VSCode. The prototype confirmed that it's feasible to do the application in a VSCode extension while outputting the information in a developer-friendly format, which allows users to get information on their project readily while being very user-friendly and simple.

Development guide

The tool is currently divided in two microservices: a VSCode frontend extension and a dockerized backend.

Frontend

The frontend is built in Typescript, with Webview and ESBundler integration, using VS Code extensibility API. To build and run the frontend, go inside the folder "frontend/". There, run:

npm i
npm run compile
code .

In the new VSCode window that opens, open "frontend/src/extension.ts". Then press F5, and choose "VSCode Extension Development Host" environment in the opened dropdown. The Archy logo should appear on the left column of extensions. For testing during development, run "Shift + Alt + P" (windows) or "Shift + Cmd + P" (linux) and select "Developer: Open Webview Developer Tools" in the dropdown, for console debugging during development.

The structure of the frontend is described below:

  • "frontend/src/panels/": webview panels
  • "frontend/src/scripts/": processing of opened repository's data
  • "frontend/src/webview": webview main functions
  • "frontend/src/extension.ts": activate function for VSCode extension

Backend

The backend is built in Express JS. To run the backend, go inside the folder "backend/". There run:

    docker compose up

The structure of the backend is described below:

  • "backend/app.js": declare endpoint paths
  • "backend/routes/": define each endpoint
  • "backend/scripts/": API requests and processing of received data in endpoints

Conventions

No specific coding conventions are followed

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

The extension has a button where you click to infer the architecture, and then it analyses the repository. After a short time, there is an output of the Markdown file with the answer, which you can save to your computer.

This is a simple GIF on how to use the extension
archy

Sprint retrospective

Sprint 1

  • What went well? - We managed to divide the backend and frontend, dockerized our backend, kept with the weekly meetings routine we had established in sprint 0.

  • What went poorly? - We didn't manage to accomplish most of our sprint PBI's, we were too optimistic on the effort estimation.

  • What can we do to improve? - Better communication of tasks completion and more realistic estimations of PBI's effort.

  • What ideas do we have? - Finish the unaccomplished PBI's, integrate with Vault and Google Cloud and try to find a common VS Code frontend with the other teams.

This is how our product board looked at the end of the sprint 1 imagem

Sprint 2

  • What went well? - Improvement from previous sprint, managed to accomplish all but one PBI we aimed to do. Better communication, we understood what everyone did and could follow each other's progress. Attempt to communicate and establish a common VS Code extension frontend. Started integration with cloud and finished Vault integration.

  • What went poorly? - Difficulties in the deployment to the cloud, secrets that lead to the non-deployment to the cloud. We didn't interact with other groups, as much as it was needed.

  • What can we do to improve? - Focus more on establishing a good communication with other groups and contribute to global project.

  • What ideas do we have? - We want to try to move our idea of a frontend forward, complete the infrastructure integration and continue refining our product.

This is the initial state of the board in sprint 2 imagem

This is how our product board looked at the end of sprint 2 imagem

Sprint 3

  • What went well? - We were able to deploy fully to the cloud, including the use of secrets, integration to the global extension frontend. Also made use of the firestore component from cloud.

  • What went poorly? - Since the main focus of this sprint was to refine what we already had and make sure it was well deployed, new features were left behind.

  • What can we do to improve? - Learn more about extension development and all the required components, as to expedite our overall development.

  • What ideas do we have? - Refine the overall frontend and deploy the extension into the VS Code marketplace.

This is how our product board looked at the end of sprint 3 imagem

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: