ai4mde · IrinaMonaEpure · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026
diff --git 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)
-<br/>
+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
@@ -1,4 +1,4 @@
 # Secret keys
 # DO NOT COMMIT
-OPENAI_KEY=
-GROQ_API_KEY=
+OPENAI_KEY=""
+GROQ_API_KEY=""
diff --git a/docs/setup.md b/docs/setup.md
@@ -10,47 +10,49 @@
   AI4MDE &middot; <b>Installation Guide</b>
 </h1>
 
-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 <b>Windows</b>, please work from [WSL 2.1.5](https://learn.microsoft.com/en-us/windows/wsl/install) or higher,
+and set up <b>Docker Desktop</b> according to these [instructions](https://docs.docker.com/desktop/features/wsl/).
+- For a <b>Linux</b> 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 <b>macOS</b>, 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 <b>Docker Desktop</b>, make sure it is running on your device before using the commands below in your terminal.
 
-<br/>
+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
@@ -0,0 +1,53 @@
+<p align="center">
+    <img
+        src="https://avatars.githubusercontent.com/u/155311177"
+        alt="AI4MDE studio"
+        width="64"
+    />
+</p>
+
+<h1 align="center">
+  <b>Working with Diagrams</b>
+</h1>
+
+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.
+
+<h2 align="center">
+  <b>Class Diagrams</b>
+</h2>
+
+<h3>Nodes</h3>
+<b>Creating and Editing</b>
+<p>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 <b>Class</b>, <b>Enum</b>, <b>Signal</b> or <b>Application</b>. You will have to name your node. If you are creating an <b>Enum</b>, 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:</p>
+<ul>
+  <li>rename the node</li>
+  <li>edit attributes and methods for classes</li>
+  <li>edit literals for enums</li>
+</ul>
+<b>Importing Nodes from Other Systems</b>
+<p>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.</p>
+<b>Removing and Deleting</b>
+<p>You have two options in terms of removing a node:</p>
+<ul>
+  <li><b>Remove from Diagram</b>: only deletes the node and its edges in the current diagram.</li>
+  <li><b>Delete Completely</b>: removes the node and its edges in any diagram in your project.</li>
+</ul>
+<p>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.</p>
+
+<br/>
+
+<h3>Edges</h3>
+<b>Creating and Editing</b>
+<p>You can create an edge by right-clicking on a source node and then selecting the <b>Connect</b> option, then selecting the target node. You can create different types of edges: <b>Association</b>, <b>Generalization</b>, <b>Composition</b>, <b>Dependency</b>. 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 <b>Edit</b> in order to change all of these properties.</p>
+
+<p>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.</p>
+
+<b>Removing and Deleting</b>
+<p>When removing an edge, you have similar options as for a node:</p>
+<ul>
+  <li><b>Remove from Diagram</b>: only removes the edge from the current diagram.</li>
+  <li><b>Delete Completely</b>: removes the edge from any diagram in your project.</li>
+</ul>
+<p>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.</p>