# theayzek01/mev architecture

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

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

## Overview

MEV is an offline decision engine and intent-oriented file finder, exposed through a browser cockpit, MCP tools, and a decision HTTP API. The main flow accepts a user query or state, routes language where needed, then returns a typed decision or ranked file results. Search includes exact matching, semantic ranking and optional disk caching; decisions use distilled task data. The README documents these capabilities, but excerpts do not show all search internals or MCP dispatch, so uncertain links are omitted.

Main entry points: [`mcp_server.py`](https://github.com/theayzek01/mev/blob/master/mcp_server.py) (File finder), [`mev.py`](https://github.com/theayzek01/mev/blob/master/mev.py) (Typed decisions), [`dashboard.py`](https://github.com/theayzek01/mev/blob/master/dashboard.py) (Browser cockpit), [`index_cache.py`](https://github.com/theayzek01/mev/blob/master/index_cache.py) (Index cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_browser["Browser cockpit<br/>[dashboard.py]"]
  node_mcp["MCP tools<br/>[mcp_server.py]"]
  node_decision_http["Decision HTTP API<br/>[mev.py]"]
end

subgraph group_engine["Decision engine"]
  node_decision["Typed decisions<br/>[mev.py]"]
  node_language["Language routing<br/>[mev.py]"]
  node_task_data["Distilled tasks"]
end

subgraph group_search["File search"]
  node_finder["File finder<br/>[mcp_server.py]"]
  node_semantic["Semantic ranking<br/>[mcp_server.py]"]
  node_exact["Exact matching<br/>[mcp_server.py]"]
end

subgraph group_state["Search state"]
  node_cache[("Index cache<br/>[index_cache.py]")]
end

node_user(("User"))
node_file_tree["Repository files"]
node_cache_file[("&#96;.mevidx&#96; cache")]
node_ranked["Ranked files"]
node_typed_result["Typed result"]

node_user -->|"uses"| node_browser
node_browser -->|"submits state"| node_decision
node_browser -->|"submits search"| node_finder
node_browser -->|"submits text"| node_language
node_user -->|"invokes tools"| node_mcp
node_mcp -->|"delegates to"| node_decision
node_mcp -->|"delegates to"| node_language
node_mcp -->|"runs search"| node_finder
node_user -->|"posts decision"| node_decision_http
node_decision_http -->|"calls"| node_decision
node_decision -->|"routes text"| node_language
node_decision -->|"loads task data"| node_task_data
node_decision -->|"returns"| node_typed_result
node_finder -->|"routes query"| node_language
node_finder -->|"scans and reads"| node_file_tree
node_finder -->|"matches literals"| node_exact
node_finder -->|"ranks candidates"| node_semantic
node_finder -->|"loads and updates"| node_cache
node_cache -->|"reads and writes"| node_cache_file
node_finder -->|"returns results"| node_ranked

click node_browser "https://github.com/theayzek01/mev/blob/master/dashboard.py"
click node_mcp "https://github.com/theayzek01/mev/blob/master/mcp_server.py"
click node_decision_http "https://github.com/theayzek01/mev/blob/master/mev.py"
click node_decision "https://github.com/theayzek01/mev/blob/master/mev.py"
click node_language "https://github.com/theayzek01/mev/blob/master/mev.py"
click node_task_data "https://github.com/theayzek01/mev/blob/master/distilled_tasks.json"
click node_finder "https://github.com/theayzek01/mev/blob/master/mcp_server.py"
click node_semantic "https://github.com/theayzek01/mev/blob/master/mcp_server.py"
click node_exact "https://github.com/theayzek01/mev/blob/master/mcp_server.py"
click node_cache "https://github.com/theayzek01/mev/blob/master/index_cache.py"

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_browser,node_mcp,node_decision_http,node_user toneBlue
class node_decision,node_language,node_task_data,node_cache_file toneAmber
class node_finder,node_semantic,node_exact toneMint
class node_cache toneRose
class node_file_tree,node_ranked,node_typed_result toneIndigo
```

## Components

### User interfaces

- [Browser cockpit](https://github.com/theayzek01/mev/blob/master/dashboard.py): `dashboard.py`
- [MCP tools](https://github.com/theayzek01/mev/blob/master/mcp_server.py): `mcp_server.py`
- [Decision HTTP API](https://github.com/theayzek01/mev/blob/master/mev.py): `mev.py`

### Decision engine

- [Typed decisions](https://github.com/theayzek01/mev/blob/master/mev.py): `mev.py`
- [Language routing](https://github.com/theayzek01/mev/blob/master/mev.py): `mev.py`
- [Distilled tasks](https://github.com/theayzek01/mev/blob/master/distilled_tasks.json): `distilled_tasks.json`

### File search

- [File finder](https://github.com/theayzek01/mev/blob/master/mcp_server.py): `mcp_server.py`
- [Semantic ranking](https://github.com/theayzek01/mev/blob/master/mcp_server.py): `mcp_server.py`
- [Exact matching](https://github.com/theayzek01/mev/blob/master/mcp_server.py): `mcp_server.py`

### Search state

- [Index cache](https://github.com/theayzek01/mev/blob/master/index_cache.py): `index_cache.py`

### Other components

- **User**
- **Repository files**
- **`.mevidx` cache**
- **Ranked files**
- **Typed result**

## Connections

- User → Browser cockpit: uses (evidence: `README.md`)
- Browser cockpit → Typed decisions: submits state (evidence: `dashboard.py`)
- Browser cockpit → File finder: submits search (evidence: `dashboard.py`)
- Browser cockpit → Language routing: submits text (evidence: `dashboard.py`)
- User → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → Typed decisions: delegates to (evidence: `mcp_server.py`)
- MCP tools → Language routing: delegates to (evidence: `mcp_server.py`)
- MCP tools → File finder: runs search (evidence: `mcp_server.py`)
- User → Decision HTTP API: posts decision (evidence: `README.md`)
- Decision HTTP API → Typed decisions: calls (evidence: `mev.py`)
- Typed decisions → Language routing: routes text (evidence: `mev.py`)
- Typed decisions → Distilled tasks: loads task data (evidence: `mev.py`)
- Typed decisions → Typed result: returns (evidence: `mev.py`)
- File finder → Language routing: routes query (evidence: `mcp_server.py`)
- File finder → Repository files: scans and reads (evidence: `mcp_server.py`)
- File finder → Exact matching: matches literals (evidence: `mcp_server.py`)
- File finder → Semantic ranking: ranks candidates (evidence: `mcp_server.py`)
- File finder → Index cache: loads and updates (evidence: `mcp_server.py`)
- Index cache → `.mevidx` cache: reads and writes (evidence: `index_cache.py`)
- File finder → Ranked files: returns results (evidence: `README.md`)
