docs: adding mermaid sequence diagram displaying the current picture

README.md

@@ -152,3 +152,94 @@ 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
+
+```mermaid
+sequenceDiagram
+    participant Git as Git Providers (GitHub/GitLab)
+    participant ECA as Git ECA Rest API
+    participant Cache as Cache Layer
+    participant DB as Database
+    participant Projects as Eclipse Projects API
+    participant Users as Eclipse Accounts API
+    participant Bots as Eclipse Bots API
+
+    Git->>ECA: Send PR/Push event
+    activate ECA
+    
+    alt GitHub PR
+        ECA->>Git: Fetch PR details
+        Git-->>ECA: PR data
+    else GitLab Push
+        ECA->>Git: Fetch repository details
+        Git-->>ECA: Repository data
+    end
+
+    ECA->>Git: Fetch all commit details
+    Git-->>ECA: Commits data
+
+    loop For each commit in PR/Push
+        ECA->>Cache: Check cached validation
+        activate Cache
+        Cache->>DB: Query if not in cache
+        DB-->>Cache: Return data
+        Cache-->>ECA: Return validation status
+        deactivate Cache
+
+        par Eclipse Foundation API Checks
+            ECA->>Projects: Validate project status
+            Projects-->>ECA: Project validation
+        and
+            ECA->>Users: Check ECA status
+            Users-->>ECA: User agreements
+        and
+            ECA->>Bots: Verify bot accounts
+            Bots-->>ECA: Bot validation
+        end
+    end
+
+    ECA->>DB: Store validation results
+    
+    alt GitHub PR
+        ECA->>Git: Update PR status with combined results
+        ECA->>Git: Add review comments if needed
+    else GitLab Push
+        ECA->>Git: Update status for each commit
+    end
+
+    ECA-->>Git: Return validation result
+    deactivate ECA
+
+```
+
+The git-eca service acts as a central validation gateway for Git contributions to Eclipse Foundation projects. Here's how it works:
+
+1. **Contribution Event**:
+   - A developer submits a PR (GitHub) or push (GitLab)
+   - The Git provider sends a webhook event to git-eca
+
+2. **Initial Context Gathering**:
+   - git-eca fetches complete details about the contribution context
+   - For PRs: gets PR metadata
+   - For pushes: gets repository context
+   - Retrieves all commits involved in the change
+
+3. **Per-Commit Processing**:
+   - For each commit in the contribution:
+     * Checks cached results to avoid duplicate processing
+     * Validates against Eclipse Foundation systems in parallel:
+       - Projects API: Verifies project status and repository ownership
+       - Accounts API: Validates contributor agreements (ECA)
+       - Bots API: Verifies automated contribution accounts
+
+4. **Result Aggregation**:
+   - Combines validation results from all commits
+   - Updates status in the Git provider
+   - Adds explanatory comments if any validation fails
+
+5. **Response**:
+   - Returns final validation status to Git provider
+   - Contribution is either approved or blocked based on combined validation results
+
+The service ensures all contributions comply with Eclipse Foundation policies while maintaining a smooth developer experience through clear feedback and efficient validation processing.
\ No newline at end of file