Infrastructure - FEUP-MEIC-DS-2024-25/ai4sd GitHub Wiki

The Hero Alliance: a guide

Introduction to the Hero Alliance Project

Welcome to the Hero Alliance project! :)

Up until now, you've been prototyping your ideas on how to improve the AI4SD landscape. You've done great work, and you should be proud of yourselves!!!

Now we'll be taking the next step: creating a real AI assistant and integrating it with other assistants.

While you will interact with cloud technologies and AI capabilities (as part of your superhero functionality), the key takeaway from this course will be how to work together to develop a high-quality, large-scale software system.

In this guide, we will explore how to build and manage a superhero-themed cloud application in Google Cloud Platform (GCP), with inspiration from the Marvel Universe. We’ll explain how different components of the system interact with each other, how you’ll use the technologies, and how to collaborate effectively to make sure everything works as a unified whole.

1. The Hero Alliance/Marvel Analogy

Why These Names?

In this project, we’ve drawn inspiration from the Marvel Universe, specifically focusing on the Avengers and X-Men.

We believe analogies are great ways to explain hard concepts. We hope this analogy can help you. If anything here is not clear, feel free to contact us!

  • Avengers: In the project, Avengers represents a web application with both a frontend and a backend. The frontend displays all the superheroes and their capabilities, and the backend manages the logic and interactions with other components like the superhero services, Vault (Firestore), Nexus (Cloud Storage), and Pub/Sub.

  • X-Men: The X-Men in our project is analogous to a VS Code extension, meaning it has only a backend and cannot have a frontend deployed on GCP. The backend handles interactions with superheroes but without the need for a frontend.

  • Vault: Vault acts as the central storage system for all superhero data It’s built using Firestore, which will store and manage all superhero-related information. Avengers and X-Men can also make use of this to store relevant data.

  • Nexus: Nexus is a Cloud Storage bucket where the repositories your superheroes will work with are stored. Jarvis will help keep Nexus up-to-date by periodically "polling" GitHub to ensure all repositories are synchronized.

  • Echoes: Echoes represent a Pub/Sub system for superhero communication. Every superhero can send or receive messages to/from other superheroes via Pub/Sub topics such as echo-jarvis. Jarvis also interacts with Echoes to broadcast updates. You can create your own Echoes. Try to follow the naming convention echo-whatever.

  • Superheroes: These are the Cloud Run services that represent individual superheroes. Each superhero has GenAI capabilities that help with tasks like:

    • Requirements Engineering
    • Software Architecture
    • Software Testing and Validation
    • Agile and Code Refactoring

    Superheroes are managed in Cloud Run, and their data is stored in Vault (Firestore), in a particular collection for each superhero which you can create. They can interact with each other via Pub/Sub Echoes.

  • Jarvis: Jarvis keeps Nexus (Cloud Storage) updated by polling GitHub for the latest changes in superhero repositories. Nexus stores all repositories that the superheroes interact with. This is because LLMs have a time limit to which they have knowledge about. This augments their capabilities.

  • Ultron: You'll notice that there is no cloud resource for Ultron, which is the LLM you'll be using. This is because we noticed that some LLMs are better than others for what your assistants will be doing, and we want you to have the freedom of selecting the one you prefer. Simply get an API key from an LLM service such as Gemini or ChatGPT, and get to work! This may be obvious, but this integration is up to you... :) You get the bonus of not being rate-limited by your peers, which is a nice plus!

Why This Architecture?

This setup is not exactly microservices but close to it. It’s about making smart trade-offs. Here’s why we chose this architecture:

  • The Avengers need both a frontend and backend to display superheroes and manage requests.
  • The X-Men, being a VS Code extension, only need a backend to process superhero interactions.
  • Jarvis integrates with Nexus to keep repositories updated, ensuring superheroes always have the latest code.
  • Vault (Firestore) acts as the database for all components, keeping everything organized and consistent.

It’s not microservices in the purest sense, but this architecture strikes a balance between simplicity and scalability, while still allowing flexibility and modularity.

You may be asking why you don't have an individual database per superhero. Apart from the costs that would imply, Vault supports multiple collection in the same service, which partially simulates the behavior of having a dedicated database. So, in practice, you should not have any issues regarding this.

This architecture ensures that your superhero can function by itself, but it is also able to be integrated into a larger (and, hopefully, better) system in a seamless manner.

2. Explanation of GCP Technologies Used

We’ll now explain the technologies being used in this project and how they relate to the analogy.

Google Cloud Run (Superheroes, Avengers, X-Men, Jarvis):

  • What it is: A fully managed serverless platform for deploying and managing containers.
  • Why it’s used: Each superhero is a Cloud Run service that can scale automatically based on demand. Avengers and X-Men backends are also deployed as Cloud Run services to handle requests and manage the logic of superhero interactions.
  • Analogy: The superheroes are like individual heroes in a Marvel movie. Each has their unique abilities (containers) and works together to fight evil (process requests).

Firestore (Vault):

  • What it is: A NoSQL document database that’s part of Firebase.
  • Why it’s used: It stores data for the superheroes, backend services, and Jarvis, allowing you to store JSON-like data in a scalable way.
  • Analogy: Vault is like a brain, storing critical data for each superhero. Each superhero’s capabilities, interactions, and details are securely stored in Vault.

Google Pub/Sub (Communication and Echo-jarvis Topics):

  • What it is: A messaging service for building event-driven systems and handling asynchronous communication between applications.

  • Why it’s used: Pub/Sub is used for superhero communication. Superheroes can "talk" to each other through topics like echo-jarvis. Jarvis can send updates or information across services via these topics.

  • Analogy: Pub/Sub is like the Avengers’ comms system, where superheroes can send messages to each other (using topics like "echo-jarvis").

    Important Note on Echoes:

    • Currently, we have an echo topic called echo-jarvis. This is an example of an echo that one superhero (Jarvis) uses to communicate with other superheroes.
    • Naming convention for echoes: All future echo topics should ideally follow the naming style of echo-<superhero-name>. This ensures consistency in communication channels and makes it easier to track which superhero is sending the messages.

Google Cloud Storage (Nexus and Avengers Frontend):

  • What it is: A service for storing and accessing large amounts of unstructured data, such as files and images, all common artifacts in software repositories.
  • Why it’s used: Nexus and Avengers Frontend (Cloud Storage) will hold all superhero-related repositories, images, and other important assets such as the static components of the React web app. It provides scalable and durable storage for the project.
  • Analogy: Nexus is like Avengers HQ, storing the files and equipment the heroes need to function. Avengers Frontend is like the Avengers’ command center, where all hero information is displayed.

Important note on Docker

All cloud run services should be run on Docker containers. This is to prevent "but it works on my computer!" scenarios, among other reasons. Containers allow software to be run anywhere there is a runtime that can interpret them, which is great for cloud development, considering all of us have different systems which are, in turn, configured differently.

3. Hero Alliance: Cloud Infrastructure Quickstart

Step-by-step guide

  1. Ask your professor for a JSON key for your specific superhero
  2. Once you get the key, you can use it on your code files (just be sure to not store it in the repository: save it as a secret, do not leave it publicly accessible). Authenticate with gcloud auth activate-service-account --key-file=superhero-0Y-0Y.json
  3. In order to deploy your code to the cloud, you simply create a branch from main, make a Pull Request with the changes you have in mind, and, if/when it gets accepted and merged, a pipeline will be triggered

Important remarks

  • The pipeline will only work for superheroes if you comply with the following conditions:
    • You must respect the structure of the AI4SD repository. That means the root of the repository should look like this:
      • avengers/
      • x-men/
      • superheroes/
        • superhero-01-01/
        • superhero-01-02/
        • ...
      • strange/
      • jarvis/
      • infrastructure/
        • pipeline
        • terraform
    • So, if, for instance, you are working on superhero-01-02, put that code inside the respective file. If you don't respect this hierarchy, your changes won't be picked up by the pipeline
    • In order for the pipeline to update your superhero, it must have a Dockerfile in its root path. For the example above, the path would be superheroes/superhero-01-02/Dockerfile
    • Additionally, inside the avengers/ folder, you must have an index.html file. Otherwise, your web app will not be visible in its public link
  • The pipeline is responsible for building, pushing, and deploying a docker image of your superhero to the cloud. This is an entirely automated process, so there is no need to run any commands in a CLI
  • If you have not yet created your repository, then an example hello-world image will be used for all cloud run instances. Only when you follow all of the above instructions will you be able to have the cloud update your superhero
  • Regarding X-Men, it will not be deployed in the cloud, as it is a VS Code extension. However, you may extend the existing pipeline with building and publication automations if you so desire. The best way to automate that process is up to you to decide
  • You have at your availability the following resources:
    • avengers cloud storage bucket: the web app of AI4SD (up to you to develop)
      • This is not a VM but a data container. Because you will be using ReactJS to develop the frontend of the app, its output are just static files. Thus, this is a cost effective approach for maintaining a frontend.
    • superhero-0X-0Y cloud run instance: your superhero service powered by GenAI capabilities (up to you to develop by us)
      • The service account name of your superhero follows the format superhero-0X-0Y@hero-alliance-feup-ds-24-25.iam.gserviceaccount.com
    • nexus cloud storage bucket: a data bucket that will hold the repositories your superhero will use (already deployed by us)
      • We recommend creating one folder per superhero. Inside that folder you can put whatever you want there
    • vault firestore: data storage for holding information specific to your superhero (internally it is mandatory that it is referred by GCP as (default)) (already deployed by us)
      • Again, we recommend one collection per superhero
    • strange cloud run instance: a service for orchestrating superhero execution (up to you to develop by us)
      • The service account name of strange follows the format hero-alliance-strange@hero-alliance-feup-ds-24-25.iam.gserviceaccount.com
    • jarvis cloud run instance: a service for synchronizing the contents of nexus with GitHub (already deployed by us)
      • The service account name of jarvis follows the format hero-alliance-jarvis@hero-alliance-feup-ds-24-25.iam.gserviceaccount.com
    • echo-jarvis pub/sub: a communication channel that allows jarvis to let superheroes know there are updates in repositories held in nexus (already deployed by us)
    • echo-superheroes pub/sub: same as above, but for superheroes to communicate with each other (already deployed by us)
  • You can access the Google Cloud Platform web console to inspect information about the cloud infrastructure. The login credentials are: [email protected] + hero-alliance-feup-ds-24-25.

Public superhero links

4. Collaboration Reminder

Remember, this project is a collaborative effort, and your superhero is only a small part of the overall application. You can contribute to any part of the system, whether it’s the frontend, backend, repositories, or communication systems.

We truly trust you and believe you can do great work whilst adopting an agile mindset. As a consequence, we as teachers should increase your agility as much as possible. That's why we are very lenient regarding permissions.

However, you are not free to do anything you want. If you need a new cloud resource or a major architectural change, you must talk with us first. Everything is logged, and any malicious actions will have consequences. We trust you to collaborate responsibly and positively, so this surely won't be an issue :)

On another note, remember that teamwork is truly important. You're most likely to fail if you don't work as a united team, even if you are the most skilled student in the whole class. You'll probably have differences among your teammates, but remember: you are all striving for a common goal.

Work hard! These are many different topics you haven't heard of up until now, so it's natural that you feel lost. That just means you're doing things right: you're learning! Hard work beats talent any day :)

5. Encouragement and Trust

We believe in you and trust that you will create something amazing. You've proven your value during the past classes and in the prototypes' session. Your teamwork and dedication will result in Avengers and X-Men being projects we will all be proud of. We look forward to seeing how you grow and learn in the process.

Try to have fun along the way! You can specialize in parts of the system you prefer, forming "guilds". We don't want DS to be a burden to you.

Remember we are here to help! Don't hesitate in getting in touch with us if you need anything. We are also part of the team!

Good luck, heroes! :) We are sure you'll do great!!!

Important Edits

  • It has been detected that even one sole failing Dockerfile causes the full pipeline update to crash and fail. To circumvent this, be sure to try/catch your build, making it so it is skippable when it fails!