Initial commit: MEV taxonomy, production pipeline, mermaid architecture, scaling notes

Made-with: Cursor

docs/ARCHITECTURE.md

@@ -0,0 +1,91 @@
+# 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