docs: Add documentation (#8)

* docs: Add documentation (#7)

* docs(gh): Add contribution guidelines

* docs: Add environment variables description

* docs: Add flow and sequences diagrams

* docs(gh): Add README file

README.md

@@ -0,0 +1,18 @@
+# Tests Micro-service
+
+Welcome to the tests micro-service. This service is responsible for running the teacher's tests against the student's code and pushing the results to the `submissions-status-updates` queue for the `Submissions Status Updater` micro-service to pick them up and update the database accordingly.
+
+Below is a diagram of the overall architecture of the system with the tests micro-service highlighted in green.
+
+![Tests microservice highlighted with a green rectangle in the overall architecture diagram](./docs/images/tests-microservice-highlighted.png)
+
+## Documentation
+
+Please, refer to the following documents for more information about the tests micro-service:
+
+| Document | Description |
+| --- | --- |
+| [Contributing](./docs/contributing.md) | Contributing guidelines. |
+| [Environment](./docs/environment.md) | A description of the environment variables used by the tests micro-service. |
+| [Sequences Diagrams](./docs/diagrams/sequences.md) | A collection of sequence diagrams describing the interactions between the tests micro-service and other components of the system. |
+| [Flow Diagrams](./docs/diagrams/flow.md) | A collection of flow diagrams describing the flow of the tests micro-service. |

docs/contributing.md

@@ -0,0 +1,62 @@
+# General organization contribution guidelines
+
+Please, read the [General Contribution Guidelines](https://github.com/upb-code-labs/docs/blob/main/CONTRIBUTING.md) before contributing.
+
+# Tests micro-service contribution guidelines
+
+## Project structure / architecture
+
+The tests micro-service's architecture is based on the Hexagonal Architecture in order to make it easier to maintain and extend.
+
+The project structure is as follows:
+
+- `domain`: Contains the business logic of the tests micro-service.
+  - `definitions`: Contains the interfaces (contracts) of the tests micro-service. 
+  - `entities`: Contains the entities of the tests micro-service.
+  - `dtos`: Contains the data transfer objects of the tests micro-service.
+
+- `application`: Contains the application logic (use cases) of the tests micro-service.
+
+- `infrastructure`: Contains the implementation of the tests micro-service's interfaces (contracts) and the external dependencies of the tests micro-service.
+  - `implementations`: Contains the implementations of the `domain` interfaces (contracts).
+  - `rabbitmq`: Contains the RabbitMQ related code.
+  - `static_files`: Contains the static files micro-service related code.
+
+- `utils`: Contains the utility functions of the tests micro-service.
+
+Note that, as the `application` layer cannot depend on the `infrastructure` layer, the `application` layer only uses the interfaces (contracts) defined in the `domain` layer, so, any implementation in the `infrastructure` layer can injected and used by the `application` layer without any problem.
+
+The above allows us, for instance, to use multiple `LanguageTestsRunner` implementations (`JavaTestsRunner`, `TypescriptTestsRunner`, etc.) without having to change the `application` layer.
+
+## Local development
+
+### Dependencies
+
+The following dependencies are required to run the tests micro-service locally:
+
+- [Go 1.21.5](https://golang.org/doc/install)
+- [Podman](https://podman.io/getting-started/installation) (To build and test the container image)
+
+Please, note that `Podman` is a drop-in replacement for `Docker`, so you can use `Docker` instead if you prefer.
+
+Additionally, you may want to install the following dependencies to make your life easier:
+
+- [Air](https://github.com/cosmtrek/air) (for live reloading)
+
+### Running the tests micro-service locally
+
+As the role of the tests micro-service is to listen for messages in the `submissions` queue and run the tests for the submissions, you will need to run the [gateway](https://github.com/UPB-Code-Labs/main-api) project first in order to initialize the queue, database and the other micro-services and send submissions by using the REST API.
+
+After you have the gateway running, you can start the tests micro-service by running the following command:
+
+```bash
+air 
+```
+
+This will start the tests micro-service and will watch for changes in the source code and restart the service automatically.
+
+Additionally, you may want to generate a `.air.toml` file and add the `tests_exec_dir/` directory to the `exclude_dir` list in order to avoid restarting the service when the tests are executed, to do this, run the following command or refer to the [Air documentation](https://github.com/cosmtrek/air)
+
+```bash
+air init
+```

docs/diagrams/flow.md

@@ -0,0 +1,37 @@
+# Sequences diagrams
+
+## Run tests
+
+### Java implementation
+
+```mermaid
+flowchart TD
+    Start --> A[Save .zip archives in the FS]
+    A --> B{Error?}
+    B -- Yes --> Z
+
+    B -- No --> D[Extract .zip archives]
+    D --> E{Error?}
+    E -- Yes --> Z
+
+    E -- No --> F[Merge extracted folders]
+    F --> G{Error?}
+    G -- Yes --> Z
+
+    G -- No --> H[Run test command]
+    H --> I[Sanitize Stdout / Stderr]
+    I --> J[Delete tests execution folder]
+    J --> Z
+
+    Z[Send update to the SSU Queue] --> Finish
+```
+
+#### Explanations
+
+- `Merge extracted folders`: In this step, the `src/test/java` folder from the teacher's code is merged with the `src/main/java` folder from the student's code in the `src/` folder of the language template in order to: 
+
+  - Use the `pom.xml` file from the language template to make sure no additional dependencies are added or removed from the project by the teacher or the student. **This is important because we only guarantee that the tests will run correctly and securely if the dependencies are the same as the ones defined in the language template.**
+
+  - Run the teacher's tests against the student's code.
+
+- `Sanitize Stdout / Stderr`: In this step, the `stdout` and `stderr` of the tests execution are sanitized in order to remove any sensitive information that may be present in the output of the tests execution (e.g. File paths, etc.).

docs/diagrams/sequences.md

@@ -0,0 +1,32 @@
+# Sequences diagrams
+
+## Full micro-service flow
+
+```mermaid
+sequenceDiagram
+    participant SQ as Submissions Queue 
+    participant TMSvc as Tests Microservice
+    participant SSUQ as Submissions Status Updates Queue
+    participant SFMSvc as Static Files Microservice
+    
+    
+    SQ ->> TMSvc: Pull message with job metadata.
+
+    TMSvc -->> SSUQ: Send "running" update.
+    
+    TMSvc ->>+ SFMSvc: Get .zip archive with the language template.
+    SFMSvc-->>- TMSvc: .zip archive bytes.
+    TMSvc ->>+ SFMSvc: Get .zip archive with teacher's tests.
+    SFMSvc-->>- TMSvc: .zip archive bytes.
+    TMSvc ->>+ SFMSvc: Get .zip archive with the student's code.
+    SFMSvc-->>- TMSvc: .zip archive bytes.
+
+    TMSvc -->> TMSvc: Run tests.
+
+    TMSvc -->> SSUQ: Send "ready" update.
+
+    TMSvc -->> SQ: ACK message.
+    
+```
+
+Please, note that the `Run tests` step is further detailed in the [flow diagrams](./flow.md).

docs/environment.md

@@ -0,0 +1,9 @@
+# Environment
+
+This document describes the required environment variables to run the micro-service.
+
+| Name                          | Description                                     | Example                                  | Mandatory |
+| ----------------------------- | ----------------------------------------------- | ---------------------------------------- |  -------- |
+| `RABBIT_MQ_CONNECTION_STRING` | The connection string to the RabbitMQ instance. | `amqp://username:password@address:port/` | Yes       |
+| `STATIC_FILES_MICROSERVICE_ADDRESS`        | The address of the static files micro-service.  | `http://domain:port`                  | Yes       |
+| `TESTS_EXECUTION_DIRECTORY`      | The path (preferably absolute) to the directory where the tests will be executed. | `/tmp` | No       |