docs(mm-bot): add class diagrams

docs(mm-bot): add architecture
docs(mm-bot): add scenarios

mm-bot/docs/README.md

@@ -1,17 +1,27 @@
 # MM Bot
 MM Bot is a process designed to supply liquidity to YAB Escrow orders.
-![img.png](images/img.png)
+
 ## Logical View
 ### Functional Requirements
 - The bot must be able to read an order from the Escrow contract.
 - The bot must be able to perform a transfer in Ethereum to the recipient address through the Payment
 Registry contract.
-- The bot must be able to perform a withdrawal in Ethereum to recover the funds in the L2 through the
+- The bot must be able to perform a repay in Ethereum to recover the funds in the L2 through the
 Payment Registry contract.
 - The bot must be able to store the orders in a database and update their status.
 - In case of an error, the bot must be able to store the error and retry the order.
 
-[Diagrama de clases]
+### Simplified Class Diagram
+The following diagram shows the mm classes and how they interact with each other.
+
+![mm_diagram_class.svg](images%2Fmm_diagram_class.svg)
+
+### Full Class Diagram
+The following diagram is a detailed version of the previous diagram, 
+showing the attributes and methods of each class.
+
+![mm_diagram_class_full.svg](images%2Fmm_diagram_class_full.svg)
+
 ## Process View
 ### Non-Functional Requirements
 - The bot must be able to handle multiple orders simultaneously.
@@ -21,38 +31,57 @@ Payment Registry contract.
 - The bot must be able to retry failed orders.
 - The bot must be able to perform adequate logs for the orders tracking.
 
-### Simplified Class Diagram
-```plantuml
-@startuml
-class Bot {
-    -order: Order
-    -paymentRegistry: PaymentRegistry
-    -database: Database
-    +run()
-    +readOrder()
-    +transfer()
-    +withdraw()
-    +storeOrder()
-    +updateOrder()
-    +storeError()
-    +retryOrder()
-}
-@enduml
-```
-![MM_Diagram_Class.svg](images%2FMM_Diagram_Class.svg)
-![MM_Diagram_Class_Full.svg](images%2FMM_Diagram_Class_Full.svg)
-
-## Development View (TODO)
+### Architecture
+The bot architecture is as follows:
+
+![architecture.png](images%2Farchitecture.png)
+The bot is composed of the following components:
+- **MM Bot**: The main process of the bot. It has the following subcomponents:
+  - `Main Order Indexer`: The `Main Order Indexer` is responsible for indexing the orders from 
+    the pending blocks.
+  - `Order Processor`: The `Order Processor` is responsible for processing the orders.
+  - `Failed Orders Processor`: The `Failed Orders Processor` is responsible for retrying the failed orders.
+  It runs every 5 minutes.
+  - `Accepted Blocks Processor`: The `Accepted Blocks Processor` is responsible for indexing the orders
+    that belong to accepted blocks. It runs every 5 minutes.
+- **Database**: The database is used to store the following data:
+  - Orders.
+  - Errors.
+  - Block numbers.
+
+An important aspect is that the bot must be able to handle multiple orders simultaneously.
+For that reason, the bot uses asyncio to handle the orders concurrently. This way is preferred
+over using threads, due to the potentially high number of orders that the bot must handle and 
+the fact that the bot is I/O bound.
+
+Another important aspect is that the bot must have a reliable network connection to communicate
+with Ethereum and L2 networks RPCs.
 
 ## Physical View
-[Version completa de la arquitectura]
+The system is deployed in an EC2 virtual machine in AWS.
+The EC2 runs the bot process and the database.
+
+![physical_view.png](images/physical_view.png)
 
 ## Scenarios
-1 Flujo de una orden
-[Estado de una orden]
+### 1. Order Processing Flow
+The following diagram shows the flow of an order through the bot.
+
+![state_diagram.svg](images%2Fstate_diagram.svg)
+
+### 2. Failed Orders Reprocessing
+When an order fails, the bot stores the error and marks the order as failed. So, the `Failed
+Orders Processor` will retry the failed orders. The following diagram shows the flow of a 
+failed order through the bot.
+
+![failed_orders.svg](images%2Ffailed_orders.svg)
 
-2 Orden fallida
+### 3. Shutdown Recovery
+When the bot starts, it retrieves incomplete orders from the database and continues their processing.
 
-3 Recuperacion de estado
+### Accepted Blocks Indexation
+The Main Order Indexer process orders from pending blocks. The `Orders from
+Accepted Blocks Processor` will index the orders that belong to accepted blocks. This way, if the `Main Order
+Indexer` loses an order, it will be taken from the `Orders from Accepted Blocks Processor`.
 
-4 Indexacion bloques aceptados
+![accepted_blocks.svg](images%2Faccepted_blocks.svg)

mm-bot/docs/diagrams/accepted_blocks.puml

@@ -0,0 +1,19 @@
+@startuml
+actor User as U
+entity Escrow as E #purple
+entity "Payment Registry" as PR #blue
+control "Order Processor" as OP
+control "Order from Accepted Blocks Processor" as ABP
+database Database
+
+ABP -[#purple]> E : Get Orders from Accepted Blocks
+ABP -> Database : Store missing orders
+ABP -> OP : Process missing Order
+OP -> OP : Processing Order
+OP -[#blue]> PR : Process Order
+PR -[#blue]> U: Send funds
+OP -[#purple]> E : Repay funds
+OP -> Database : Store Order as completed
+
+@enduml
+

mm-bot/docs/diagrams/failed_orders.puml

@@ -0,0 +1,20 @@
+@startuml
+actor User as U
+entity Escrow as E #purple
+entity "Payment Registry" as PR #blue
+control "Order Processor" as OP
+control "Failed Order Processor" as FOP
+database Database
+
+U -[#purple]> E : Set Order
+OP -[#purple]> E : Get Order
+OP ->x OP : Processing Order
+OP -> Database : Store Order as failed due to error
+FOP -> Database : Get failed orders
+FOP -> OP : Process failed order
+OP -[#blue]> PR : Process Order
+PR -[#blue]> U: Send funds
+OP -[#purple]> E : Repay funds
+OP -> Database : Store Order as completed
+
+@enduml