diff --git a/README.md b/README.md
index 3eb2727a1b2271a70c397f851f50e5077d90f54e..4bdfa756fea4b720f6851d067e821832c78f8d34 100644
--- a/README.md
+++ b/README.md
@@ -15,28 +15,57 @@
 - **Assigment**:
   - A Formula 1 team is in need to manage its participation to the world championship. The team has two cars participating to each race, each one driven by one driver, with other test drivers available to develop the car further. The manager of the team can set the driver for each car and manage a list of other (test) drivers that are under contract and he can also set as main drivers if unhappy about results. Each driver has a name, surname, nationality, and set of characteristics (e.g. driving on the wet, aggressiveness, etc..) that the manager can visualize. The car is composed of several components (engine, suspensions), that the different departments of the team (e.g. engine, aerodynamics) evolve during time. The manager can pick from a list of components and assemble the cars that will participate to the next race. Engineers from other departments can login to the system and put newer components available. The manager is notified that those components are available and that they can be used to improve the car.
 
+- **Modules**:
+  <br>Our application is divided into 4 separate spring boot modules, as shown on the class diagram
+1) Core module:
+  <br>Core module contains most of the functionality of the project assignment. It communicates with the other modules via their REST api's.
+2) Notifications module:
+  <br>Notifications module sends e-mail (or other) notifications to team members.
+3) Visualisation module:
+  <br>Visualization module provides a visualization of given JSON data in readable HTML (or other) format. Team manager will be able to visualize current state of both cars.
+4) Applications module:
+  <br>Applications module allows people to send an application to this team. Manager can view these applications and hire new drivers for his team.
+
 - **Diagrams**:
 
 ![IMAGE_DESCRIPTION](diagrams/class_diagram.png)
 ![IMAGE_DESCRIPTION](diagrams/use_case_diagram.png)
 
-# Pro vývoj
-
-Nemělo by být potřeba upravovat pom.xml nikde, pouze v formula-team-management v sekci modules pro přidání nových modulů.
-
-V openapi.yaml si nejprve specifikujte tag, který reprezentuje classu, do které se vygenerujou vaše metody např. CarService.
-Tento tag pak používejte k označení metod, ať se všechny negenerujou do jedné obří classy, ale jsou pěkně rozdělené.
-
-Vygenerování se spouští normálně pomocí:
+# Build and run the app
+Build the app (all modules) by running 
+```bash
+mvn clean install
+```
+in the project's parent directory, or build separate modules by running the same command inside the module's parent directory. For example, to build notifications module:
 ```bash
+cd notification
 mvn clean install
 ```
-Pokud tam budete mít chyby, tak přepínač -e je srozumitelně vypisuje.
+Tests are run automatically during the build, but if you want to run them again, use:
+```bash
+mvn test
+```
+again, either in the parent directory to test all modules, or inside separate modules to only test one at a time.
 
-Appka se spustĂ­ pomocĂ­:
+To run a module, just run:
 ```bash
 cd core
 mvn
 ```
+or alternatively:
+```bash
+cd core
+mvn spring-boot:run
+```
+
+To see the running REST api's in action, use CURL or swagger UI:
+ http://localhost:8080/swagger-ui/index.html
+
+Just note that each module runs on a different port by default, so care where you send your requests.<br>
+**Default ports:**
+- core module: 8080
+- notifications module: 8083
+- visualization module: 8082
+- applications module: 8081
 
-A potom si to možete vyzkušat přes swagger na adrese http://localhost:8080/swagger-ui/index.html.
+These ports can be overridden either in the application.properties file of each module, or by specifying the port manually when running the "mvn" command to run the module.