# Architecture diagrams (Mermaid)

**Last Updated:** 2026-04-13  
**Document Version:** 1.0  
**Status:** Reference

Diagrams are **illustrative**: production systems differ by chain, relay, custody, and team policy (including exclusion of harmful MEV). For implementation-level naming, use **`MEV_Bot/specs/SERVICE_ARCHITECTURE_AND_MESSAGE_CONTRACTS.md`** in the proxmox parent submodule.

---

## 1. Online pipeline (steady state)

```mermaid
flowchart TB
  subgraph dataLayer [Data_layer]
    Rpc[Rpc_nodes_archive_plus_head]
    Mempool[Mempool_or_private_flow]
    Indexers[Pool_indexers_and_logs]
  end
  subgraph core [Core_compute]
    Graph[Liquidity_graph_hot_state]
    Sim[Deterministic_EVM_simulation]
    Strat[Strategy_and_risk_limits]
  end
  subgraph exec [Execution]
    Bundle[Bundle_builder_signed_txs]
    Relay[Relay_or_builder_auction]
    Chain[Chain_settlement]
  end
  subgraph capital [Capital_and_ops]
    Inv[Inventory_and_treasury]
    Obs[Observability_and_safety]
  end
  Rpc --> Indexers
  Mempool --> Sim
  Indexers --> Graph
  Graph --> Sim
  Sim --> Strat
  Strat --> Bundle
  Bundle --> Relay
  Relay --> Chain
  Chain --> Inv
  Strat --> Obs
  Relay --> Obs
  Inv --> Strat
```

**Reading order:** Data feeds refresh graph and triggers; simulation consumes graph plus pending hints; strategy gates bundles; execution competes for inclusion; settlement updates inventory; observability closes the loop.

---

## 2. Pending transaction to candidate bundle (simplified)

```mermaid
flowchart LR
  Pending[Pending_tx_or_signal]
  Local[Local_pre_state_S]
  Post[Post_state_S_prime]
  Cand[Candidate_searcher_txs]
  Profit[Profit_and_gas_check]
  Bundle[Bundle_payload]
  Pending --> Local
  Local --> Post
  Post --> Cand
  Cand --> Profit
  Profit --> Bundle
```

This is the **backrun-shaped** view: model how someone else’s transaction moves state, then evaluate whether your bundle is profitable **after** that transition (and under your ordering assumptions).

---

## 3. Typical technology map (non-prescriptive)

| Concern | Examples (illustrative only) |
|--------|------------------------------|
| RPC / chain access | Self-hosted execution client, archive node, websocket subscriptions |
| Hot state | Redis, in-memory graph, columnar snapshots for replay |
| Messaging | NATS, Kafka, or in-process channels (see `MEV_Bot` MVP: NATS) |
| Simulation | revm, Foundry-style forks, custom EVM + state DB |
| Storage | PostgreSQL for pools, runs, PnL |
| Signing | HSM, remote signer, segregated keys per role |
| Submission | Relay HTTP APIs, builder gRPC, public `eth_sendRawTransaction` |

---

## Related

- [PRODUCTION_PIPELINE.md](PRODUCTION_PIPELINE.md) — narrative and `MEV_Bot` mapping  
- [OPPORTUNITY_TAXONOMY.md](OPPORTUNITY_TAXONOMY.md) — opportunity classes  
- [SCALING_AND_REALITY.md](SCALING_AND_REALITY.md) — constraints