diff --git a/README.md b/README.md index 57b4ea971..4a5652893 100644 --- a/README.md +++ b/README.md @@ -19,20 +19,33 @@ AI4MDE is an open-source research initiative at [LIACS](https://liacs.leidenuniv.nl/) that aims to bridge the gap between AI and Model-Driven Engineering. AI4MDE is a web-based environment in which users can design and manage UML Class, Activity, and Use Case Diagrams via a user-friendly interface. The platform provides the option to generate fully functional Django software prototypes from these diagrams. ## ⚡️ Quick start -Get up and running with the AI4MDE studio and API in no time: +To get up and running with the AI4MDE tool in no time, use the code below. For more explanations and environment requirements, read [docs/setup.md](./docs/setup.md) (you will need Docker, Git, and, if you are on Windows, WSL). -``` +```bash +# Ensure that you have the Docker installed +docker -v +docker compose version + +# Clone the repository git clone https://github.com/ai4mde/studio.git -cd frontend -docker-compose up -d -``` +cd studio -Now visit [http://ai4mde.localhost](http://ai4mde.localhost) +# Create secrets file +cp config/secrets.env.example config/secrets.env +# If you want, you can edit config/secrets.env, config/api.env, or config/prototypes.env at this point +# Build and start all the containers (add -d flag to start in background) +docker compose up -d --build -For a full tutorial on how to install AI4MDE, see: [setup.md](./docs/setup.md) +# To stop the containers, you can use +docker compose down +``` -For an overview of the technical architecture, see [architecture.md](./docs/architecture.md) -
+Now visit [http://ai4mde.localhost](http://ai4mde.localhost). +The login credentials can be found in `config/api.env`. + +- For explanations on using the diagram modelling features, see [docs/users-guide.md](./docs/users-guide.md). + +- For an overview of the technical architecture, see [docs/architecture.md](./docs/architecture.md). -![Alt](https://repobeats.axiom.co/api/embed/80709bf7ea933c8ce8605ee6e8136a5f9420dcd6.svg "Repobeats analytics image") +- You can report issues using our [bug reporting board](https://github.com/orgs/ai4mde/projects/12). This is public for viewing, but requires us to add you as a collaborator in order to post a new issue. Please, contact someone from the course support team in order to be added. diff --git a/config/secrets.env.example b/config/secrets.env.example index 524b28637..067760b23 100644 --- a/config/secrets.env.example +++ b/config/secrets.env.example @@ -1,4 +1,4 @@ # Secret keys # DO NOT COMMIT -OPENAI_KEY= -GROQ_API_KEY= \ No newline at end of file +OPENAI_KEY="" +GROQ_API_KEY="" \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md index 0b6b1d9bf..03cbaa843 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -10,47 +10,49 @@ AI4MDE · Installation Guide -Get up and running with the AI4MDE studio and API in no time: +Depending on your operating system, you should set up your envirnoment to meet the following requirements: +- For Windows, please work from [WSL 2.1.5](https://learn.microsoft.com/en-us/windows/wsl/install) or higher, +and set up Docker Desktop according to these [instructions](https://docs.docker.com/desktop/features/wsl/). +- For a Linux distribution, you may use a regular terminal. Set up [Docker Engine](https://docs.docker.com/engine/install/) or [Docker Desktop](https://docs.docker.com/desktop/setup/install/linux/), as well. +- For macOS, you should also be able to use a regular terminal. Make sure to install [Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/). -``` -git clone https://github.com/ai4mde/studio.git -cd frontend -docker-compose up -d -``` +Check that [Git](https://github.com/git-guides/install-git) is installed on your device. -Now visit [http://ai4mde.localhost](http://ai4mde.localhost) +> ☝️ If you are using Docker Desktop, make sure it is running on your device before using the commands below in your terminal. -
+With these requirements met, you can get started from a Linux, macOS or WSL terminal: -## Installation - -> ☝️ This project is assumes you run a GNU/Linux system. -> If you find yourself on Windows, please work from WSL2. -> You should be fine on macOS. If you're just running without -> contributing, ignore the above. +```bash +# Ensure that you have the Docker installed +docker -v +docker compose version -The easiest way to get started is through a container runtime and the docker compose file at the root. If these terms are unfamiliar to you, start with installing a container runtime. +# Clone the repository +git clone https://github.com/ai4mde/studio.git +cd studio +``` -Before the environment can be built, secret API keys need to be specified in `/config/secrets.env`. An example of such a file can be seen in `/config/secrets.env.example`. +Before the environment can be built, you need to provide your secret OpenAI and Groq API keys in `/config/secrets.env`. An example of such a file can be seen in `/config/secrets.env.example`. You have to perform this step in order to run the software, however you may leave the values empty if you are not interested in using the LLM features. Feel free to use the terminal or any code/text editor for this step. -With everything ready and this repository cloned, you can get started from a shell: +> ☝️ Also, take note of the username and password stored in files `config/api.env` and `config/prototypes.env`. These are your credentials for logging into AI4MDE, and any potential web application prototypes you might generate with it, respectively: `DJANGO_SUPERUSER_USERNAME = admin` and `DJANGO_SUPERUSER_PASSWORD = sequoias`. You may update your credentials in these files if you wish. ```bash -# Ensure that you have the correct tools installed, you might have to restart -# your shell -docker -v -docker compose version +# Configure secrets (required file; values optional if you won't use LLM features) +cp config/secrets.env.example config/secrets.env +# edit config/secrets.env +# edit config/api.env +# edit config/prototypes.env -# Build all the necessary images (only required on first install or dependency change) -docker compose build +# Build and Start all the containers (add -d flag to start in background) +docker compose up -d --build -# Start all the containers (add -d flag to start in background) -docker compose up +# To stop the containers, you can use +docker compose down ``` This will start multiple services in the background and set everything up (for development). As soon as that's done, you can find the following services on your machine's network: -- [ai4mde.localhost](http://ai4mde.localhost) - Frontend, from `/frontend` -- [api.ai4mde.localhost](http://api.ai4mde.localhost) - API from `/api` -- [prototype.ai4mde.localhost](http://prototype.ai4mde.localhost) - Running prototype in `/prototypes/generated_prototypes` -- [prototypes_api.ai4mde.localhost](http://prototypes_api.ai4mde.localhost) - Prototype management API from `/prototypes/backend` +- [ai4mde.localhost](http://ai4mde.localhost) - Frontend, from `/frontend`. As a non-contributing user, this is where you can interact with the AI4MDE tool. Use the credentials from `config/api.env` to log in. +- [api.ai4mde.localhost](http://api.ai4mde.localhost) - API from `/api`. +- [prototype.ai4mde.localhost](http://prototype.ai4mde.localhost) - Running prototype in `/prototypes/generated_prototypes`. +- [prototypes_api.ai4mde.localhost](http://prototypes_api.ai4mde.localhost) - Prototype management API from `/prototypes/backend`. diff --git a/docs/users-guide.md b/docs/users-guide.md new file mode 100644 index 000000000..06d7b141b --- /dev/null +++ b/docs/users-guide.md @@ -0,0 +1,53 @@ +

+ AI4MDE studio +

+ +

+ Working with Diagrams +

+ +You can create diagrams from scratch in the `Projects` section accessible from the sidebar menu. Here, you first create and name your project. A project can have many systems, and a system can have many diagrams. For example, you might want to create a project called `Airline`, which is split over several systems such as `Logistics`, `Payments`, `Marketing`, `Maintenance`, etc. Each of these systems might contain one or several class, use case or activity diagrams. These diagrams may or may not have common elements, like the class `Airplane` appearing in class diagrams in both the `Logistics` and the `Maintenance` systems. + +Once you have your project and system, you can get started working on a diagram. + +

+ Class Diagrams +

+ +

Nodes

+Creating and Editing +

Nodes are the buidling blocks of class diagrams. By right-clicking your modelling area, you have the option to create a new node representing a Class, Enum, Signal or Application. You will have to name your node. If you are creating an Enum, you can also use the create menu to specify your literals. By right clicking a node, you then have the option to edit it. This allows you to:

+ +Importing Nodes from Other Systems +

In the class diagram, you have the option to import nodes from other diagrams, and even from other systems within your project. The origin system is marked when it is different than the current one. Sometimes you are importing a node that in other diagrams has some preexisting edges connecting it to nodes that already exist in your current diagram. If that happens, these edges will be added to your current diagram as well.

+Removing and Deleting +

You have two options in terms of removing a node:

+ +

This distinction is important when you have imported a node to multiple systems, and allows you to decide whether you want to delete it only from the current diagram or from everywhere in your project.

+ +
+ +

Edges

+Creating and Editing +

You can create an edge by right-clicking on a source node and then selecting the Connect option, then selecting the target node. You can create different types of edges: Association, Generalization, Composition, Dependency. In the edge creation menu, you have the option of setting a label, as well as any eventual source/target label or multiplicity. You can right-click an edge and then select Edit in order to change all of these properties.

+ +

You may be in the situation of having to reposition edges in order to avoid overlaps that can make the label, multiplicityes or edge type indistinguishable. You can drag the circular endpoints to reposition the edge. You can also add bending points by double-clicking a specific spot on the edge. These points are also draggable. If you wish to delete a bending point, you can do so by right-clicking it.

+ +Removing and Deleting +

When removing an edge, you have similar options as for a node:

+ +

Once again, this distinction is important when you have imported the same nodes to multiple systems, which can lead to imported edges that reoccur in multiple diagrams.

\ No newline at end of file