docs: update indexer tap agent sectino

Signed-off-by: Gustavo Inacio <[email protected]>

Author: gusinacio

README.md

@@ -171,11 +171,46 @@ The Subgraph Service is an [axum](https://crates.io/crates/axum)-based web serve
 
 ### indexer-tap-agent
 
-The TAP Agent is an actor-based system powered by [ractor](https://crates.io/crates/ractor). It is responsible for processing receipts into RAVs and marking them ready for redemption.
+The TAP Agent is an actor-based system powered by [ractor](https://crates.io/crates/ractor). It processes receipts into RAVs (Receipt Aggregate Vouchers) and prepares them for redemption by the `indexer-agent`.
 
 #### Key Features
-- **Receipt Processing:** Handles receipts stored by `indexer-service-rs`, performing aggregation and RAV generation.
-- **Concurrency Management:** Leverages the actor model to efficiently manage receipt processing tasks.
+1. **Receipt Processing:**
+   - Receipts are fetched from the `receipts` table in the database using `pglisten`.
+   - The actor system validates and processes receipts before aggregating them into RAVs.
+   - Debug logs can be activated using `RUST_LOG=debug` to provide additional insights during the receipt lifecycle.
+
+2. **Actor System:**
+   - The TAP Agent operates using three main actor groups:
+     - **SenderAccountManager:** 
+       - Monitors the indexer's escrow accounts.
+       - Handles receipt routing to the appropriate `SenderAllocation`.
+       - Kills the application if the database connection is lost.
+     - **SenderAccount:**
+       - Tracks receipts, pending RAVs, and invalid receipts across allocations.
+       - Ensures the escrow account has sufficient funds to cover outstanding obligations.
+       - Selects the next allocation for creating a RAV request and manages `SenderAllocation` actors.
+     - **SenderAllocation:**
+       - Represents a `(sender, allocation)` tuple.
+       - Processes receipts and sends updated values to the `SenderAccount`.
+       - Handles `TriggerRequest` messages to initiate RAV creation.
+
+3. **RAV Workflow:**
+   - Valid receipts are aggregated into RAVs, which replace older RAVs in the database.
+   - Once an allocation is closed, the system creates a **Last RAV**, aggregating all receipts. This final RAV is marked as "Last" and prepared for redemption by the `indexer-agent`.
+
+4. **Metrics and Monitoring:**
+   - The TAP Agent exposes detailed metrics to monitor system behavior. Key metrics include:
+     - **Unaggregated Receipts:** Ensure unaggregated receipts remain below the `max_willing_to_lose` value to prevent the sender from being denied.
+     - **RAV Request Failures:** Monitor the rate of failed RAV requests, as repeated failures can disrupt aggregation.
+   - Full details of all metrics can be found in the [Metrics Documentation](https://github.com/graphprotocol/indexer-rs/blob/gustavo/rebuild-documentation/docs/Metrics.md#tap-agent-metrics).
+   - A Grafana dashboard is available to visualize system metrics and provide a clear overview of the TAP Agent's performance:
+     - [Download Dashboard JSON](https://github.com/graphprotocol/indexer-rs/blob/gustavo/rebuild-documentation/docs/dashboard.json).
+
+5. **Troubleshooting:**
+   - If RAV requests fail or unaggregated receipts exceed the `max_willing_to_lose` limit:
+     - Check the **RAV failure metrics**.
+     - Review debug logs (`RUST_LOG=debug`) for additional context.
+     - Use the Grafana dashboard to identify bottlenecks or failures in the actor system.
 
 
 ## Crates