diff --git a/README.md b/README.md
index 2acb6cdf..410b11dc 100644
--- a/README.md
+++ b/README.md
@@ -37,3 +37,77 @@ Format Rust code
 ```bash
 cargo fmt
 ```
+
+# Architecture
+
+## Lending flow
+
+```mermaid
+sequenceDiagram
+    box rgb(33,66,99)
+    participant UI
+    end
+    box rgb(33,33,99)
+    participant LendingPool
+    participant LoanManager
+    end
+    box rgb(33,66,33)
+    participant PriceOracle
+    end
+
+    UI->>LendingPool: get_balance()
+    LendingPool-->>UI: Balance
+
+    UI->>LoanManager: get_price()
+    LoanManager->>PriceOracle: last_price(Token)
+    PriceOracle-->>LoanManager: PriceData
+    LoanManager-->>UI: Price
+
+    UI->>LendingPool: get_interest_rate()
+    LendingPool->>LoanManager: get_interest_rate(Pool)
+    LoanManager-->>LendingPool: Interest rate
+    LendingPool-->>UI: Interest rate
+
+    UI->>LendingPool: deposit()
+    LendingPool-->>UI: OK/Error
+```
+
+## Borrow flow
+
+```mermaid
+sequenceDiagram
+    box rgb(33,66,99)
+    participant UI
+    end
+    box rgb(33,33,99)
+    participant LendingPool
+    participant LoanManager
+    end
+    box rgb(33,66,33)
+    participant PriceOracle
+    end
+
+    UI->>LendingPool: get_available_balance()
+    LendingPool-->>UI: Available Balance
+
+    UI->>LendingPool: get_interest_rate()
+    LendingPool->>LoanManager: get_interest_rate(Pool)
+    LoanManager-->>UI: Interest rate
+
+    UI->>LoanManager: get_price()
+    LoanManager->>PriceOracle: last_price(Token)
+    PriceOracle-->>LoanManager: PriceData
+    LoanManager-->>UI: Price
+
+    UI->>LoanManager: init_loan(token_borrow, borrow_amount, token_collat, collat_amount)
+    loop calculate_health_factor()
+        LoanManager->>PriceOracle: last_price(token_borrow)
+        PriceOracle-->>LoanManager: PriceData
+        LoanManager->>PriceOracle: last_price(token_collat)
+        PriceOracle-->>LoanManager: PriceData
+        LoanManager->>LoanManager: Check that health-factor is over minimum threshold
+    end
+    LoanManager-->>LendingPool: deposit_collateral()
+    LoanManager-->>LendingPool: borrow()
+    LoanManager-->>UI: OK/Error
+```