# mahmutcanborann/mcp-ev-digital-twin-agent architecture

> Architecture diagram of the GitHub repository mahmutcanborann/mcp-ev-digital-twin-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahmutcanborann/mcp-ev-digital-twin-agent
- Repository: https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent

## Overview

This repository is an EV digital-twin platform for battery health and range prediction, charging and driving analysis, fleet monitoring, maintenance recommendations, and conversational engineering reports. The principal flow is a driver or fleet user asking a question in the dashboard or an agent; the agent may discover/select MCP tools, invoke the MCP server, and return analysis or an LLM-generated explanation. The graph preserves the README’s major capabilities. Some dashboard and server source is excerpted, so uncertain internal wiring is omitted; roadmap items are not represented as implemented features.

Main entry points: [`mcp_servers/battery_soh_server.py`](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/mcp_servers/battery_soh_server.py) (MCP Tool Server), [`src/ev_twin_report.py`](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/ev_twin_report.py) (EV Twin Report), [`agent/ev_agent.py`](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/ev_agent.py) (EV Digital Twin Agent), [`dashboard/app.py`](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/dashboard/app.py) (Streamlit Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_dashboard["Streamlit Dashboard<br/>[app.py]"]
end

subgraph group_agents["Agent Orchestration"]
  node_discovery["Discovery MCP Agent"]
  node_tool_agent["MCP Tool Agent<br/>[mcp_tool_agent.py]"]
  node_tool_calling["Tool-Calling Agent"]
  node_ev_agent["EV Digital Twin Agent<br/>[ev_agent.py]"]
  node_llm_agent["LLM EV Agent<br/>[llm_ev_agent.py]"]
  node_mcp_server["MCP Tool Server"]
end

subgraph group_analysis["Vehicle Analytics"]
  node_battery["Battery Digital Twin<br/>[battery_twin.py]"]
  node_charging["Charging Analyzer"]
  node_driving["Driving Analyzer"]
  node_soh_model["SOH Model Files"]
  node_charging_data["Charging Patterns"]
end

subgraph group_fleet["Fleet and Reports"]
  node_report["EV Twin Report<br/>[ev_twin_report.py]"]
  node_maintenance["Predictive Maintenance"]
  node_monitoring["Monitoring Engine"]
  node_drift["Data Drift Detector<br/>[drift_detector.py]"]
  node_anomaly["Fleet Anomaly Detector"]
  node_knowledge["Battery Knowledge Base"]
  node_fleet_data["Fleet Status Data"]
end

subgraph group_integrations["External Services"]
  node_ollama["Ollama Gemma"]
end

node_user(("Driver or Fleet User"))

node_user -->|"asks or views"| node_dashboard
node_user -->|"asks"| node_discovery
node_user -->|"asks"| node_tool_agent
node_user -->|"asks"| node_tool_calling
node_dashboard -->|"requests twin results"| node_battery
node_dashboard -->|"requests actions"| node_maintenance
node_dashboard -->|"requests anomalies"| node_anomaly
node_dashboard -->|"requests health"| node_monitoring
node_discovery -->|"discovers and calls tools"| node_mcp_server
node_discovery -->|"retrieves context"| node_knowledge
node_discovery -->|"reads fleet context"| node_fleet_data
node_discovery -->|"selects tools and explains"| node_ollama
node_tool_agent -->|"routes tool calls"| node_mcp_server
node_tool_calling -->|"routes general questions"| node_ev_agent
node_tool_calling -->|"requests explanations"| node_ollama
node_ev_agent -->|"generates analyses"| node_report
node_ev_agent -->|"gets actions"| node_maintenance
node_ev_agent -->|"reads fleet rankings"| node_fleet_data
node_llm_agent -->|"generates analyses"| node_report
node_llm_agent -->|"gets actions"| node_maintenance
node_llm_agent -->|"checks system and fleet"| node_monitoring
node_llm_agent -->|"requests answer"| node_ollama
node_mcp_server -->|"dispatches twin tools"| node_battery
node_mcp_server -->|"dispatches charging tools"| node_charging
node_mcp_server -->|"dispatches driving tools"| node_driving
node_mcp_server -->|"dispatches agent tools"| node_ev_agent
node_mcp_server -->|"dispatches LLM tool"| node_llm_agent
node_mcp_server -->|"dispatches health checks"| node_monitoring
node_mcp_server -->|"dispatches drift checks"| node_drift
node_report -->|"generates battery summary"| node_battery
node_report -->|"gets charging analysis"| node_charging
node_report -->|"gets driving analysis"| node_driving
node_maintenance -->|"uses report"| node_report
node_monitoring -->|"generates system report"| node_report
node_monitoring -->|"reads fleet status"| node_fleet_data
node_battery -->|"loads model"| node_soh_model
node_charging -->|"analyzes sessions"| node_charging_data
node_ev_agent -.->|"requests explanation"| node_ollama

click node_dashboard "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/dashboard/app.py"
click node_discovery "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/discovery_mcp_agent.py"
click node_tool_agent "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/mcp_tool_agent.py"
click node_tool_calling "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/tool_calling_ev_agent.py"
click node_ev_agent "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/ev_agent.py"
click node_llm_agent "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/llm_ev_agent.py"
click node_mcp_server "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/mcp_servers/battery_soh_server.py"
click node_battery "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/battery_twin.py"
click node_charging "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/charging_analyzer.py"
click node_driving "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/driving_analyzer.py"
click node_report "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/ev_twin_report.py"
click node_maintenance "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/predictive_maintenance.py"
click node_monitoring "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/monitoring_engine.py"
click node_drift "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/drift_detector.py"
click node_anomaly "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/fleet_anomaly_detector.py"
click node_knowledge "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/battery_knowledge_base.py"
click node_soh_model "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/models/battery_soh_rf_model.pkl"
click node_fleet_data "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/models/fleet_latest_status.csv"
click node_charging_data "https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/data/ev_charging_patterns.csv"

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_dashboard,node_user toneBlue
class node_discovery,node_tool_agent,node_tool_calling,node_ev_agent,node_llm_agent,node_mcp_server toneAmber
class node_battery,node_charging,node_driving,node_soh_model,node_charging_data toneMint
class node_report,node_maintenance,node_monitoring,node_drift,node_anomaly,node_knowledge,node_fleet_data toneRose
class node_ollama toneIndigo
```

## Components

### User Interfaces

- [Streamlit Dashboard](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/dashboard/app.py): `dashboard/app.py`

### Agent Orchestration

- [Discovery MCP Agent](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/discovery_mcp_agent.py): `agent/discovery_mcp_agent.py`
- [MCP Tool Agent](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/mcp_tool_agent.py): `agent/mcp_tool_agent.py`
- [Tool-Calling Agent](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/tool_calling_ev_agent.py): `agent/tool_calling_ev_agent.py`
- [EV Digital Twin Agent](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/ev_agent.py): `agent/ev_agent.py`
- [LLM EV Agent](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/agent/llm_ev_agent.py): `agent/llm_ev_agent.py`
- [MCP Tool Server](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/mcp_servers/battery_soh_server.py): `mcp_servers/battery_soh_server.py`

### Vehicle Analytics

- [Battery Digital Twin](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/battery_twin.py): `src/battery_twin.py`
- [Charging Analyzer](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/charging_analyzer.py): `src/charging_analyzer.py`
- [Driving Analyzer](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/driving_analyzer.py): `src/driving_analyzer.py`
- [SOH Model Files](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/models/battery_soh_rf_model.pkl): `models/battery_soh_rf_model.pkl`
- [Charging Patterns](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/data/ev_charging_patterns.csv): `data/ev_charging_patterns.csv`

### Fleet and Reports

- [EV Twin Report](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/ev_twin_report.py): `src/ev_twin_report.py`
- [Predictive Maintenance](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/predictive_maintenance.py): `src/predictive_maintenance.py`
- [Monitoring Engine](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/monitoring_engine.py): `src/monitoring_engine.py`
- [Data Drift Detector](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/drift_detector.py): `src/drift_detector.py`
- [Fleet Anomaly Detector](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/fleet_anomaly_detector.py): `src/fleet_anomaly_detector.py`
- [Battery Knowledge Base](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/src/battery_knowledge_base.py): `src/battery_knowledge_base.py`
- [Fleet Status Data](https://github.com/mahmutcanborann/mcp-ev-digital-twin-agent/blob/main/models/fleet_latest_status.csv): `models/fleet_latest_status.csv`

### External Services

- **Ollama Gemma**

### Other components

- **Driver or Fleet User**

## Connections

- Driver or Fleet User → Streamlit Dashboard: asks or views
- Driver or Fleet User → Discovery MCP Agent: asks
- Driver or Fleet User → MCP Tool Agent: asks
- Driver or Fleet User → Tool-Calling Agent: asks
- Streamlit Dashboard → Battery Digital Twin: requests twin results
- Streamlit Dashboard → Predictive Maintenance: requests actions
- Streamlit Dashboard → Fleet Anomaly Detector: requests anomalies
- Streamlit Dashboard → Monitoring Engine: requests health
- Discovery MCP Agent → MCP Tool Server: discovers and calls tools
- Discovery MCP Agent → Battery Knowledge Base: retrieves context
- Discovery MCP Agent → Fleet Status Data: reads fleet context
- Discovery MCP Agent → Ollama Gemma: selects tools and explains
- MCP Tool Agent → MCP Tool Server: routes tool calls
- Tool-Calling Agent → EV Digital Twin Agent: routes general questions
- Tool-Calling Agent → Ollama Gemma: requests explanations
- EV Digital Twin Agent → EV Twin Report: generates analyses
- EV Digital Twin Agent → Predictive Maintenance: gets actions
- EV Digital Twin Agent → Fleet Status Data: reads fleet rankings
- LLM EV Agent → EV Twin Report: generates analyses
- LLM EV Agent → Predictive Maintenance: gets actions
- LLM EV Agent → Monitoring Engine: checks system and fleet
- LLM EV Agent → Ollama Gemma: requests answer
- MCP Tool Server → Battery Digital Twin: dispatches twin tools
- MCP Tool Server → Charging Analyzer: dispatches charging tools
- MCP Tool Server → Driving Analyzer: dispatches driving tools
- MCP Tool Server → EV Digital Twin Agent: dispatches agent tools
- MCP Tool Server → LLM EV Agent: dispatches LLM tool
- MCP Tool Server → Monitoring Engine: dispatches health checks
- MCP Tool Server → Data Drift Detector: dispatches drift checks
- EV Twin Report → Battery Digital Twin: generates battery summary
- EV Twin Report → Charging Analyzer: gets charging analysis
- EV Twin Report → Driving Analyzer: gets driving analysis
- Predictive Maintenance → EV Twin Report: uses report
- Monitoring Engine → EV Twin Report: generates system report
- Monitoring Engine → Fleet Status Data: reads fleet status
- Battery Digital Twin → SOH Model Files: loads model
- Charging Analyzer → Charging Patterns: analyzes sessions
- EV Digital Twin Agent → Ollama Gemma: requests explanation