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, understanding large codebases can be challenging and time-consuming, with critical information spread in various forms of documentation and commit logs. This complexity slows onboarding processes and increases technical debt.

However, there is always a light at the end of the tunnel. In this case, that light is Archy, a powerful VSCode extension that automatically infers architectural patterns by parsing through the project’s documentation and scraped commit logs with the click of a button. Archy empowers developers and teams to navigate and manage complex projects effectively, transforming the way they interact with their code.

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

With Domain Analysis we aim to provide a clear overview of the project's main concepts and define the structure and behaviour of the final envisioned system. For this purpose we created two graphs:

  • Class diagram: define the key entities in the domain and their interaction

  • Sequence diagram: illustrate the behavior and flow of messages between components when a user utilizes the tool.

Class Diagram

In the class diagram we highlight four core concepts:

  • User - entity that interacts with the system

  • Prompt - textual input sent to Gemini. Includes initial converted data from different file types (pdf, docx, rtf..) to .txt; also includes user queries to refine Gemini's response, after an initial architectural pattern inference.

  • Output - textual response returned from Gemini, after a request.

  • Chat - bundle of prompts/outputs created when user interacts with the tool to infer one repository's architecture.

Currently, we don't have the "chat" component concept implemented, since all user requests consist of a single prompt, and a Gemini output, without the ability to refine a response.

class_diagram

Sequence Diagram

In the sequence diagram, we describe 3 message flows that occur in the assistant:

  • Steps 1 - 1.3 describe the start-up of the extension. The user opens the assistant, prompting a request to Firestore, in order to build the list of previous requests in the extension UI.

  • Steps 2 - 3.3 describe an inference of architectural patterns of a repository. The files present in the locally opened repository in VSCode are sent to the backend, which processes the data before sending it to Gemini. The Gemini output is stored in Firestore, and also returned to the user's frontend. In our idealized assistant, the user also has the ability to refine an output provided by Gemini, and write what he would like changed, which is covered in the loop condition of the diagram.

  • Steps 4 - 4.3 describe analyzing a previous request. A specific output id is fetched from Firestore to present in the frontend, covered in the opt condition of the diagram.

Sequence diagram

Architecture and design

To create the prototype for sprint 0 as fast as possible, initially, we developed our assistant with the backend logic glued to the VSCode extension user interface, resulting in a monolithic architecture, that should be separated in order to adapt to a microservices format.

Architecture and design old

After sprint 1, we separated the frontend and backend logic into different components.

After sprint 3, the backend server application communicates with Firestore.

Currently, the implemented architecture corresponds to the envisioned one, adopting the following format:

  • A user interacts with the assistant through the VSCode extension.
  • The VSCode extension communicates with a backend API, making requests and receiving responses.
  • In the backend, the server application communicates with the Gemini API, making requests and receiving responses.
  • In the backend, the server application communicates with the Firestore API, saving and retrieving Gemini outputs.

Architecture and design new

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

Key Management and Secrets Handling:

Managing secrets securely is a critical part of ensuring the safety and reliability of Archy. Below are the identified risks and the measures taken to mitigate them:

Use of Secrets:

  • Risk: Sensitive secrets, such as API keys for AI tools (e.g., Gemini) and Firestore/Cloud credentials, could be exposed if not properly secured. This exposure could lead to unauthorized access, data breaches, or service disruptions.
  • Mitigation: Store keys and secrets in environment variables instead of hardcoding them into the codebase.

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

New developers looking to contribute to the project should consider the following steps:

1. Setup the Development Environment:

  • Clone the repository.
  • Install dependencies for both frontend and backend as described under their respective sections.
  • For frontend, compile the VS Code extension by running npm i followed by ```npm run compile`` inside the frontend/ directory. Launch the extension in a development host environment via the VS Code Extension Development Host.

2. Understand the Code Structure:

  • Familiarize yourself with the structure of both the frontend and backend.
  • Review key files such as frontend/src/extension.ts for frontend activation logic and backend/app.js for backend API paths.

3. Testing and Debugging:

  • Use webview developer tools for frontend debugging.
  • Test backend endpoints locally using the Dockerized environment (docker compose up).

4. Pull Request:

  • Create a feature branch for your changes.
  • Submit a pull request (PR) with an explanation of your changes and reference the relevant issue.

Archy Public Link:

Contributions

Link to the factsheets of each team member's name and GitHub account.