# jiaxuanliu-arsko/vaspilot architecture

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

- Interactive diagram: https://gitdiagram.com/jiaxuanliu-arsko/vaspilot
- Repository: https://github.com/jiaxuanliu-arsko/vaspilot

## Overview

VASPilot automates materials-science calculations through web-submitted tasks, CrewAI agents, and MCP calculation tools. The main workflow plans a study, obtains structure/input support, runs and monitors VASP jobs, then stores and presents results. The README also describes Materials Project access, JSON RAG, plotting, memory, and both Flask and Quart interfaces. Several implementation details are documented but not visible in the sampled excerpts; those links are omitted or marked unverified rather than inferred as calls.

Main entry points: [`src/vaspilot/crew/vasp_crew.py`](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/crew/vasp_crew.py) (Crew orchestration), [`src/vaspilot/tools/mcp/mcp_server.py`](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/mcp_server.py) (MCP tool server), [`src/vaspilot/server/flask_server/flask_server.py`](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/server/flask_server/flask_server.py) (Flask server), [`src/vaspilot/server/quart_server/quart_server.py`](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/server/quart_server/quart_server.py) (Quart server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Task interface"]
  node_flask["Flask server<br/>[flask_server.py]"]
  node_quart["Quart server<br/>[quart_server.py]"]
  node_listener["Event listener<br/>[server_listener.py]"]
end

subgraph group_agents["Agent orchestration"]
  node_crew["Crew orchestration<br/>[vasp_crew.py]"]
  node_llm["Local LLM client<br/>[local_llm.py]"]
  node_wait["Calculation polling<br/>[wait_calc_tool.py]"]
end

subgraph group_mcp["Calculation services"]
  node_mcpserver["MCP tool server<br/>[mcp_server.py]"]
  node_struct["Structure tools<br/>[struct_tools.py]"]
  node_vasp["VASP calculations<br/>[vasp_calculate.py]"]
  node_plot["Plot execution<br/>[python_plot.py]"]
  node_calcdb[("Calculation records<br/>[sqlite_database.py]")]
end

subgraph group_knowledge["Knowledge and memory"]
  node_rag["JSON RAG tools<br/>[json_rag_tool.py]"]
  node_embed["Embedding client<br/>[embedding.py]"]
end

node_user(("Researcher"))
node_model(("LLM service"))
node_materials[("Materials Project")]
node_slurm["Slurm scheduler"]

node_user -->|"submits task"| node_quart
node_user -->|"submits task"| node_flask
node_quart -.->|"starts workflow"| node_crew
node_flask -.->|"starts workflow"| node_crew
node_crew -.->|"uses model"| node_llm
node_llm -->|"requests completions"| node_model
node_crew -->|"configures tools"| node_rag
node_crew -.->|"configures embeddings"| node_embed
node_rag -.->|"embeds queries"| node_embed
node_crew -->|"configures tool"| node_wait
node_wait -->|"checks status"| node_mcpserver
node_mcpserver -->|"dispatches tools"| node_struct
node_mcpserver -->|"dispatches calculations"| node_vasp
node_mcpserver -->|"executes plots"| node_plot
node_mcpserver -->|"reads and writes"| node_calcdb
node_vasp -.->|"submits jobs"| node_slurm
node_struct -.->|"retrieves structures"| node_materials
node_quart -.->|"registers events"| node_listener
node_flask -.->|"registers events"| node_listener

click node_flask "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/server/flask_server/flask_server.py"
click node_quart "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/server/quart_server/quart_server.py"
click node_listener "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/listener/server_listener.py"
click node_crew "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/crew/vasp_crew.py"
click node_llm "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/crew/local_llm.py"
click node_wait "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/wait_calc_tool.py"
click node_rag "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/json_rag_tool.py"
click node_embed "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/crew/embedding.py"
click node_mcpserver "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/mcp_server.py"
click node_struct "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/struct_tools.py"
click node_vasp "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/vasp_calculate.py"
click node_plot "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/python_plot.py"
click node_calcdb "https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/sqlite_database.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_flask,node_quart,node_listener toneBlue
class node_crew,node_llm,node_wait,node_materials toneAmber
class node_mcpserver,node_struct,node_vasp,node_plot,node_calcdb toneMint
class node_rag,node_embed,node_slurm toneRose
class node_user,node_model toneIndigo
```

## Components

### Task interface

- [Flask server](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/server/flask_server/flask_server.py): `src/vaspilot/server/flask_server/flask_server.py`
- [Quart server](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/server/quart_server/quart_server.py): `src/vaspilot/server/quart_server/quart_server.py`
- [Event listener](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/listener/server_listener.py): `src/vaspilot/listener/server_listener.py`

### Agent orchestration

- [Crew orchestration](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/crew/vasp_crew.py): `src/vaspilot/crew/vasp_crew.py`
- [Local LLM client](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/crew/local_llm.py): `src/vaspilot/crew/local_llm.py`
- [Calculation polling](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/wait_calc_tool.py): `src/vaspilot/tools/wait_calc_tool.py`

### Calculation services

- [MCP tool server](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/mcp_server.py): `src/vaspilot/tools/mcp/mcp_server.py`
- [Structure tools](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/struct_tools.py): `src/vaspilot/tools/mcp/struct_tools.py`
- [VASP calculations](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/vasp_calculate.py): `src/vaspilot/tools/mcp/vasp_calculate.py`
- [Plot execution](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/python_plot.py): `src/vaspilot/tools/mcp/python_plot.py`
- [Calculation records](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/mcp/sqlite_database.py): `src/vaspilot/tools/mcp/sqlite_database.py`

### Knowledge and memory

- [JSON RAG tools](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/tools/json_rag_tool.py): `src/vaspilot/tools/json_rag_tool.py`
- [Embedding client](https://github.com/jiaxuanliu-arsko/vaspilot/blob/main/src/vaspilot/crew/embedding.py): `src/vaspilot/crew/embedding.py`

### Other components

- **Researcher**
- **LLM service**
- **Materials Project**
- **Slurm scheduler**

## Connections

- Researcher → Quart server: submits task (evidence: `README.md`)
- Researcher → Flask server: submits task (evidence: `README.md`)
- Quart server → Crew orchestration: starts workflow
- Flask server → Crew orchestration: starts workflow
- Crew orchestration → Local LLM client: uses model (evidence: `src/vaspilot/crew/vasp_crew.py`)
- Local LLM client → LLM service: requests completions (evidence: `src/vaspilot/crew/local_llm.py`)
- Crew orchestration → JSON RAG tools: configures tools (evidence: `src/vaspilot/crew/vasp_crew.py`)
- Crew orchestration → Embedding client: configures embeddings (evidence: `src/vaspilot/crew/vasp_crew.py`)
- JSON RAG tools → Embedding client: embeds queries
- Crew orchestration → Calculation polling: configures tool (evidence: `src/vaspilot/crew/vasp_crew.py`)
- Calculation polling → MCP tool server: checks status (evidence: `src/vaspilot/tools/wait_calc_tool.py`)
- MCP tool server → Structure tools: dispatches tools (evidence: `src/vaspilot/tools/mcp/mcp_server.py`)
- MCP tool server → VASP calculations: dispatches calculations (evidence: `src/vaspilot/tools/mcp/mcp_server.py`)
- MCP tool server → Plot execution: executes plots (evidence: `src/vaspilot/tools/mcp/mcp_server.py`)
- MCP tool server → Calculation records: reads and writes (evidence: `src/vaspilot/tools/mcp/mcp_server.py`)
- VASP calculations → Slurm scheduler: submits jobs
- Structure tools → Materials Project: retrieves structures
- Quart server → Event listener: registers events (evidence: `src/vaspilot/server/quart_server/quart_server.py`)
- Flask server → Event listener: registers events (evidence: `src/vaspilot/server/flask_server/flask_server.py`)
