docs: applying Martin's comments to be more accurate with the flow

README.md

@@ -155,91 +155,74 @@ The `Volatile` column denotes whether the property is subject to change once ini
 
 ## Current Picture
 
+### Main Flow
 ```mermaid
 sequenceDiagram
-    participant Git as Git Providers (GitHub/GitLab)
+    participant Git as Git Provider
     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
+    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->>Git: Fetch all commit details
-    Git-->>ECA: Commits data
+    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 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
+    loop For each non-cached or failed commit
+        Note over ECA: See "Commit Validation Process" diagram
     end
 
-    ECA->>DB: Store validation results
-    
-    alt GitHub PR
-        ECA->>Git: Update PR status with combined results
+    alt GitHub Webhook Event
+        ECA->>Git: Update PR status with results
         ECA->>Git: Add review comments if needed
-    else GitLab Push
-        ECA->>Git: Update status for each commit
+    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
 
-    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
+### 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
 
-4. **Result Aggregation**:
-   - Combines validation results from all commits
-   - Updates status in the Git provider
-   - Adds explanatory comments if any validation fails
+    alt Not cached or needs revalidation
+        ECA->>Projects: Check if is project-managed
+        Projects-->>ECA: Project management status
 
-5. **Response**:
-   - Returns final validation status to Git provider
-   - Contribution is either approved or blocked based on combined validation results
+        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
 
-The service ensures all contributions comply with Eclipse Foundation policies while maintaining a smooth developer experience through clear feedback and efficient validation processing.
+        ECA->>DB: Store validation results
\ No newline at end of file
+    end
+```
\ No newline at end of file