Improve Architecture docs (#406)

* Improve Architecture docs

Co-authored-by: Caio Rodrigues <[email protected]>
Co-authored-by: Guilherme Oliveira do Carmo Carvalho <[email protected]>

docs/Architecture.md

@@ -1,42 +1,61 @@
-Maestro v10 (aka Next) is a complete rewrite of the service, focusing on improving code maintainability, knowing what is being done on the rooms/schedulers, and changing the state management.
+Maestro Next is a composition of different modules. Internally they are all part of the same code base but could be executed by giving the right arguments to the command line (or to your docker container entry point). E.g. `go run main.go start [MODULE_NAME]`
 
-The main focus of the refactor was to take Maestro's strengths and areas that could be improved. After brainstorming, we've decided that a simpler and more concrete model was necessary to maximize those areas.
+Maestro is composed of **Management API**, **Rooms API**, **Operation Execution Worker**, **Runtime Watcher Worker**, and **Metrics Reporter Worker.** 
 
-The proposed model is very similar to what continuous integration services do. You have a definition of what has to be done, and there is an implementation that takes it and executes it. This describes the overall model of this version. We call it "Operations".
+Each module has its responsibilities and is divided apart in a way to avoid mixing the execution process. Each module was thought to avoid parallel problems and to give the client more visibility about which [**Operations**](Operations.md) are being executed and their respective status.
 
 
-## Architecture
+![architecture IMAGE](./diagrams/Architecture.jpg)
 
-Besides the new model described above, this release presents a completely different architecture and code organization.
+### Maestro modules
 
-```
-                        │
-Current components (v9) │ Next components (v10)
-                        │
-┌──────┐ ┌───┐          │ ┌─────────────────┐    ┌─────────┐
-│Worker│ │API│          │ │Operations Worker│    │Rooms API│
-└──────┘ └───┘          │ └─────────────────┘    └─────────┘
-                        │
-                        │ ┌──────────────┐ ┌───────────────┐
-                        │ │Management API│ │Runtime Watcher│
-                        │ └──────────────┘ └───────────────┘
-```
+> ⚠ Note: Maestro currently only supports Kubernetes as Game Rooms runtime system. So Workers interact with them.
 
--   Management API (Public API): This is the API that manages the scheduler and rooms. It is the component the users (usually game engineers) use while interacting with Maestro, making updates, and fetching scheduler information;
--   Rooms API (Internal API): API used by the game rooms to report their status to Maestro and communicate any extra information that may apply;
--   Operations executor worker: Worker that takes queued operations and processes them;
--   Runtime watcher: Watches any state change that happens on the Runtime and takes the necessary action (like updating some Maestro state or triggering an operation);
+#### Management API
 
-## Code structure
-Maestro codebase is organized following some concepts of Hexagonal architecture (Ports & Adapters). This "style" was used as a base of the development and had some adaptations. For example, the API is not considered a primary/input Port. Instead, it is outside the core package.
+Management API is the module responsible for receiving user requests. It accepts gRPC and HTTP requests and provides several kinds of routes that are aggregated in two services: **schedulers service** and **operations service**.
 
-Most of the business logic is present at services, and they rely on the ports to not depend on the specific implementations.
+The **schedulers service** exposes features for managing schedulers, like creating a new scheduler, fetching its information, or updating them.  
+The **operations service** exposes features for tracking operations and changing their status, like listing operations by status or canceling them.
 
-Entities are the structs that hold data on the system, and they don't provide any logic besides its initialization and validation. Therefore, services and ports should "communicate" using entities so that the entire system "speaks" the same language regarding data structs.
+Management API relies on Redis for retrieving operations and game rooms, and on Postgres for retrieving and persisting schedulers.
 
-The API is responsible for converting the external protocol (currently gRPC with grpc-gateway) to entities, invoking the necessary service, and converting the response back.
 
-### Workers
-Maestro now provides a form of extending and adding more workers if they follow a worker interface. This was done to have the same pattern applied to the operation execution worker and runtime watcher. Workers are managed by the "WorkersManager," which starts an instance for each scheduler present on the storage. With this model, the implementation doesn't have to deal with multiple tenants (schedulers).
+![Management API IMAGE](./diagrams/Architecture-Management-API.jpg)
 
-Workers are not inside the service package, although they hold business logic about execution and flows. They were isolated since workers are a kind of service that has to implement an interface. Besides this difference, workers should be treated like core services.
+#### Rooms API
+
+Rooms API is the module that provides an API that **must** be used by game rooms to sync their status with Maestro. To maestro work properly, it needs to be constantly informed about the status of each game room it manages. Also, if there are forwarders configured for the scheduler, those events are forwarded from Maestro at this module.
+
+> ⚠ Note: The requests that Maestro forwards in the Rooms API are documented in [this proto file](https://github.com/topfreegames/protos/blob/master/maestro/grpc/protobuf/events.proto).
+> ⚠ Note: [Maestro client](https://github.com/topfreegames/maestro-client) could be used to ease the integration of the Game Room with Maestro.
+
+![Rooms API IMAGE](./diagrams/Architecture-Rooms-API.jpg)
+
+#### Operation Execution Worker
+
+> ⚠ Note: In Maestro a worker is a collection of routines that executes a flow related to one and only one **Scheduler** each.
+
+Operation Execution Worker is a process that constantly keeps ensuring each active **Scheduler** will have a thread (execution worker) that executes operations enqueued in the related **Scheduler** operation queue. So in this way became possible to track the events that happened and change a certain **Scheduler** in a healthier way.
+
+You could find all operations at [Operations section](Operations.md#available-operations)
+
+![Operation Execution Worker IMAGE](./diagrams/Architecture-Operation-Execution-Worker.jpg)
+
+#### Runtime Watcher Worker
+
+> ⚠ Note: In Maestro a worker is a collection of routines that executes a flow related to one and only one **Scheduler** each.
+
+Runtime Watcher Worker listens to runtime events related to the **Scheduler** and reflects the changes in **Maestro**. Currently, it listens for Game Rooms creation, deletion, and update.
+
+![Runtime Watcher Worker IMAGE](./diagrams/Architecture-Runtime-Watcher-Worker.jpg)
+
+#### Metrics Reporter Worker
+
+> ⚠ Note: In Maestro a worker is a collection of routines that executes a flow related to one and only one **Scheduler** each.
+
+From time to time Metrics Reporter Worker watch runtime to report metrics from them, such as the number of game rooms instances that are `ready`, `pending`, `error`, `unknown`, or `terminating` status. As well it watches from Game Rooms storage its status that could be `ready`, `pending`, `error`, `occupied`, `terminating`, or `unready`.
+
+This module is optional since you don't need it for any specific functionalities of the application.
+
+![Metrics Reporter Worker IMAGE](./diagrams/Architecture-Metrics-Reporter-Worker.jpg)