# sridhar636146591/mev-shield architecture

> Architecture diagram of the GitHub repository sridhar636146591/mev-shield, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sridhar636146591/mev-shield
- Repository: https://github.com/sridhar636146591/mev-shield

## Overview

MEV Shield is a Web3 platform for detecting pending-transaction attacks and helping users assess or mitigate their risk. The principal workflow is mempool monitoring, attack detection and risk scoring, then presenting findings through the dashboard and live notifications; users can also simulate trades or submit transactions privately through Flashbots. The README documents market analysis, premium payments, and analytics as additional capabilities. Several service and route implementations were not sampled, so their internal call relationships are not asserted.

Main entry points: [`mev-detector/src/App.js`](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/App.js) (React app), [`server/src/routes/api.ts`](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/routes/api.ts) (API routes), [`server/src/server.ts`](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/server.ts) (HTTP and WS server), [`server/src/services/mempoolMonitor.ts`](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/mempoolMonitor.ts) (Mempool monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User experience"]
  node_app["React app<br/>[App.js]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_attack_ui["Attack detector UI<br/>[AttackDetector.tsx]"]
  node_mempool_ui["Mempool monitor UI<br/>[MempoolMonitor.tsx]"]
  node_charts["Charts and heatmap<br/>[Charts.tsx]"]
  node_ai_chat["AI chat<br/>[AIChat.js]"]
  node_email_ui["Email alerts UI<br/>[EmailAlerts.js]"]
  node_education["Education<br/>[Education.js]"]
  node_rewards["Rewards<br/>[Rewards.js]"]
  node_market_ui["Market analysis UI"]
  node_wallet["Wallet connection<br/>[MetaMaskButton.js]"]
  node_simulator["Trade simulator<br/>[Simulator.js]"]
  node_flashbots_ui["Private protection UI"]
end

subgraph group_detection["Detection pipeline"]
  node_mempool["Mempool monitor<br/>[mempoolMonitor.ts]"]
  node_alchemy_listener["Alchemy listener"]
  node_detector["MEV detector<br/>[mevDetector.ts]"]
end

subgraph group_protection["Protection services"]
  node_flashbots["Flashbots relay"]
end

subgraph group_insights["Insights and accounts"]
  node_analytics["Historical analytics"]
  node_market_service["Market data service"]
  node_email_service["Alert delivery"]
  node_institutional["Institutional API"]
end

subgraph group_backend["Backend platform"]
  node_backend_entry["HTTP and WS server<br/>[server.ts]"]
  node_api["API routes<br/>[api.ts]"]
  node_database[("Persistence<br/>[database.ts]")]
end

node_user(("Web3 user"))
node_alchemy{{"Alchemy"}}
node_flashbots_external{{"Flashbots relay"}}
node_market_apis{{"Market data providers"}}
node_metamask{{"MetaMask"}}

node_user -->|"uses"| node_app
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_attack_ui
node_app -->|"renders"| node_mempool_ui
node_app -->|"renders"| node_charts
node_app -->|"renders"| node_ai_chat
node_app -->|"renders"| node_email_ui
node_app -->|"renders"| node_education
node_app -->|"renders"| node_rewards
node_app -->|"renders"| node_market_ui
node_app -->|"renders"| node_wallet
node_app -->|"offers"| node_simulator
node_app -->|"offers"| node_flashbots_ui
node_app -->|"requests attacks"| node_api
node_backend_entry -->|"mounts routes"| node_api
node_backend_entry -->|"connects"| node_database
node_backend_entry -->|"broadcasts alerts"| node_mempool
node_alchemy_listener -.->|"monitors pool"| node_alchemy
node_mempool -.->|"analyzes transactions"| node_detector
node_backend_entry -.->|"starts monitoring"| node_mempool
node_flashbots -->|"submits privately"| node_flashbots_external
node_market_service -.->|"fetches data"| node_market_apis
node_wallet -.->|"connects wallet"| node_metamask
node_api -.->|"serves analytics"| node_analytics
node_api -.->|"serves market data"| node_market_service
node_api -.->|"configures alerts"| node_email_service
node_api -.->|"routes protection"| node_flashbots

click node_app "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/App.js"
click node_dashboard "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Dashboard.tsx"
click node_attack_ui "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/AttackDetector.tsx"
click node_mempool_ui "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/MempoolMonitor.tsx"
click node_charts "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Charts.tsx"
click node_ai_chat "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/AIChat.js"
click node_email_ui "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/EmailAlerts.js"
click node_education "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Education.js"
click node_rewards "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Rewards.js"
click node_market_ui "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/CryptoMarketTrends.js"
click node_wallet "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/MetaMaskButton.js"
click node_simulator "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Simulator.js"
click node_flashbots_ui "https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/FlashbotsProtection.js"
click node_backend_entry "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/server.ts"
click node_api "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/routes/api.ts"
click node_database "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/database.ts"
click node_mempool "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/mempoolMonitor.ts"
click node_alchemy_listener "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/alchemyMempoolListener.ts"
click node_detector "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/utils/mevDetector.ts"
click node_flashbots "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/flashbotsService.ts"
click node_analytics "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/analytics/analyticsService.ts"
click node_market_service "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/cryptoMarketService.ts"
click node_email_service "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/emailAlertService.ts"
click node_institutional "https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/institutional/institutionalService.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_dashboard,node_attack_ui,node_mempool_ui,node_charts,node_ai_chat,node_email_ui,node_education,node_rewards,node_market_ui,node_wallet,node_simulator,node_flashbots_ui,node_user toneBlue
class node_mempool,node_alchemy_listener,node_detector toneAmber
class node_flashbots toneMint
class node_analytics,node_market_service,node_email_service,node_institutional toneRose
class node_backend_entry,node_api,node_database,node_alchemy,node_flashbots_external,node_market_apis,node_metamask toneIndigo
```

## Components

### User experience

- [React app](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/App.js): `mev-detector/src/App.js`
- [Dashboard](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Dashboard.tsx): `mev-detector/src/components/Dashboard.tsx`
- [Attack detector UI](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/AttackDetector.tsx): `mev-detector/src/components/AttackDetector.tsx`
- [Mempool monitor UI](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/MempoolMonitor.tsx): `mev-detector/src/components/MempoolMonitor.tsx`
- [Charts and heatmap](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Charts.tsx): `mev-detector/src/components/Charts.tsx`
- [AI chat](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/AIChat.js): `mev-detector/src/components/AIChat.js`
- [Email alerts UI](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/EmailAlerts.js): `mev-detector/src/components/EmailAlerts.js`
- [Education](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Education.js): `mev-detector/src/components/Education.js`
- [Rewards](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Rewards.js): `mev-detector/src/components/Rewards.js`
- [Market analysis UI](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/CryptoMarketTrends.js): `mev-detector/src/components/CryptoMarketTrends.js`
- [Wallet connection](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/MetaMaskButton.js): `mev-detector/src/components/MetaMaskButton.js`
- [Trade simulator](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/Simulator.js): `mev-detector/src/components/Simulator.js`
- [Private protection UI](https://github.com/sridhar636146591/mev-shield/blob/main/mev-detector/src/components/FlashbotsProtection.js): `mev-detector/src/components/FlashbotsProtection.js`

### Detection pipeline

- [Mempool monitor](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/mempoolMonitor.ts): `server/src/services/mempoolMonitor.ts`
- [Alchemy listener](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/alchemyMempoolListener.ts): `server/src/services/alchemyMempoolListener.ts`
- [MEV detector](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/utils/mevDetector.ts): `server/src/utils/mevDetector.ts`

### Protection services

- [Flashbots relay](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/flashbotsService.ts): `server/src/services/flashbotsService.ts`

### Insights and accounts

- [Historical analytics](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/analytics/analyticsService.ts): `server/src/services/analytics/analyticsService.ts`
- [Market data service](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/cryptoMarketService.ts): `server/src/services/cryptoMarketService.ts`
- [Alert delivery](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/emailAlertService.ts): `server/src/services/emailAlertService.ts`
- [Institutional API](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/services/institutional/institutionalService.ts): `server/src/services/institutional/institutionalService.ts`

### Backend platform

- [HTTP and WS server](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/server.ts): `server/src/server.ts`
- [API routes](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/routes/api.ts): `server/src/routes/api.ts`
- [Persistence](https://github.com/sridhar636146591/mev-shield/blob/main/server/src/database.ts): `server/src/database.ts`

### Other components

- **Web3 user**
- **Alchemy**
- **Flashbots relay**
- **Market data providers**
- **MetaMask**

## Connections

- Web3 user → React app: uses (evidence: `README.md`)
- React app → Dashboard: renders (evidence: `mev-detector/src/App.js`)
- React app → Attack detector UI: renders (evidence: `mev-detector/src/App.js`)
- React app → Mempool monitor UI: renders (evidence: `mev-detector/src/App.js`)
- React app → Charts and heatmap: renders (evidence: `mev-detector/src/App.js`)
- React app → AI chat: renders (evidence: `mev-detector/src/App.js`)
- React app → Email alerts UI: renders (evidence: `mev-detector/src/App.js`)
- React app → Education: renders (evidence: `mev-detector/src/App.js`)
- React app → Rewards: renders (evidence: `mev-detector/src/App.js`)
- React app → Market analysis UI: renders (evidence: `mev-detector/src/App.js`)
- React app → Wallet connection: renders (evidence: `mev-detector/src/App.js`)
- React app → Trade simulator: offers (evidence: `README.md`)
- React app → Private protection UI: offers (evidence: `README.md`)
- React app → API routes: requests attacks (evidence: `mev-detector/src/App.js`)
- HTTP and WS server → API routes: mounts routes (evidence: `server/src/server.ts`)
- HTTP and WS server → Persistence: connects (evidence: `server/src/server.ts`)
- HTTP and WS server → Mempool monitor: broadcasts alerts (evidence: `server/src/server.ts`)
- Alchemy listener → Alchemy: monitors pool (evidence: `README.md`)
- Mempool monitor → MEV detector: analyzes transactions
- HTTP and WS server → Mempool monitor: starts monitoring (evidence: `server/src/server.ts`)
- Flashbots relay → Flashbots relay: submits privately (evidence: `server/src/services/flashbotsService.ts`)
- Market data service → Market data providers: fetches data (evidence: `README.md`)
- Wallet connection → MetaMask: connects wallet (evidence: `README.md`)
- API routes → Historical analytics: serves analytics
- API routes → Market data service: serves market data
- API routes → Alert delivery: configures alerts
- API routes → Flashbots relay: routes protection