Draft: docs: adding mermaid sequence diagram displaying the current picture

I'm opening this MR to facilitate discussions around adding a sequence diagram. This will help us better understand the runtime flow and interactions between various actors involved in the project. The diagram won't aim to exhaustively define internal validation logic, but rather illustrate the relationships and calls required for git-eca to complete its task effectively.

README.md

@@ -152,3 +152,77 @@ The `Volatile` column denotes whether the property is subject to change once ini
 | parent_project | integer/null | ✓ | Denotes whether the project has a parent, which indicates a fork. However, the user can remove the relation to the parent project. |
 | creation_date | string | x | The project's creation date. |
 | deletion_date | string/null | ✓ | The project's deletion date. Subject to change. |
+
+## Current Picture
+
+### Main Flow
+```mermaid
+sequenceDiagram
+    participant Git as Git Provider
+    participant ECA as Git ECA Rest API
+    participant Cache as Cache Layer
+    participant DB as Database
+
+    alt GitHub Webhook Event
+        Git->>ECA: Send webhook event with commits
+        activate ECA
+        ECA->>Git: Set commit status to pending
+        ECA->>Git: Fetch additional commit details
+        Git-->>ECA: Commit details
+    else GitLab Pre-receive Hook
+        Git->>ECA: Send commits for validation
+        activate ECA
+    end
+
+    ECA->>Cache: Bulk lookup of commit validation status
+    activate Cache
+    Cache->>DB: Query for persisted validation results
+    DB-->>Cache: Return persisted data
+    Cache-->>ECA: Return validation status
+    deactivate Cache
+
+    loop For each non-cached or failed commit
+        Note over ECA: See "Commit Validation Process" diagram
+    end
+
+    alt GitHub Webhook Event
+        ECA->>Git: Update PR status with results
+        ECA->>Git: Add review comments if needed
+    else GitLab Pre-receive Hook
+        alt Validation Failed
+            ECA-->>Git: Reject push with error details
+        else Validation Passed
+            ECA-->>Git: Allow push to proceed
+        end
+    end
+
+    deactivate ECA
+```
+
+### Commit Validation Process
+```mermaid
+sequenceDiagram
+    participant ECA as Git ECA Rest API
+    participant DB as Database
+    participant Projects as Eclipse Projects API
+    participant Users as Eclipse Accounts API
+    participant Bots as Eclipse Bots API
+
+    alt Not cached or needs revalidation
+        ECA->>Projects: Check if is project-managed
+        Projects-->>ECA: Project management status
+
+        par Account Validation
+            ECA->>Users: Validate commit author ECA
+            Users-->>ECA: Author agreement status
+        and
+            ECA->>Users: Validate commit committer ECA
+            Users-->>ECA: Committer agreement status
+        and
+            ECA->>Bots: Check if bot account
+            Bots-->>ECA: Bot validation status
+        end
+
+        ECA->>DB: Store validation results
+    end
+```
\ No newline at end of file