# vivek1106-04/borgpilot architecture

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

- Interactive diagram: https://gitdiagram.com/vivek1106-04/borgpilot
- Repository: https://github.com/vivek1106-04/borgpilot

## Overview

BorgPilot ingests Google Borg traces into AsterixDB, then supports an LLM-driven SRE investigation and offline predictive analytics. The primary user workflow is to ask an incident question; the agent consults the MCP gateway’s tools to inspect datasets, query telemetry, and return an evidence-backed root-cause summary. Separate batch workflows score machine failure risk and recommend instance rightsizing, persisting results in AsterixDB for later investigation. Some implementation details, especially MCP wiring and rightsizing persistence, are supported by README documentation rather than fully sampled source.

Main entry points: [`agent/loop.py`](https://github.com/vivek1106-04/borgpilot/blob/main/agent/loop.py) (Investigation loop), [`sre/asterix_io.py`](https://github.com/vivek1106-04/borgpilot/blob/main/sre/asterix_io.py) (AsterixDB SQL I/O), [`ingestion/load_to_asterix.py`](https://github.com/vivek1106-04/borgpilot/blob/main/ingestion/load_to_asterix.py) (Provision and load), [`ingestion/fetch_borg.py`](https://github.com/vivek1106-04/borgpilot/blob/main/ingestion/fetch_borg.py) (Fetch Borg shards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Trace ingestion"]
  node_fetch["Fetch Borg shards<br/>[fetch_borg.py]"]
  node_loader["Provision and load<br/>[load_to_asterix.py]"]
end

subgraph group_agent["SRE investigation"]
  node_agent_loop["Investigation loop<br/>[loop.py]"]
  node_prompts["SRE prompts<br/>[prompts.py]"]
end

subgraph group_risk["Failure prediction"]
  node_features["Machine features<br/>[features.py]"]
  node_predict["Failure-risk scoring<br/>[predict.py]"]
end

subgraph group_rightsizing["Capacity rightsizing"]
  node_rightsize["Rightsizing analysis<br/>[rightsize.py]"]
end

subgraph group_storage["Analytics store"]
  node_asterix[("AsterixDB")]
  node_sql_io["AsterixDB SQL I/O<br/>[asterix_io.py]"]
end

node_operator(("SRE operator"))
node_mcp["AsterixDB MCP gateway"]
node_llm["Anthropic model"]

node_operator -->|"asks question"| node_agent_loop
node_agent_loop -->|"uses prompts"| node_prompts
node_agent_loop -->|"requests responses"| node_llm
node_agent_loop -->|"calls tools"| node_mcp
node_mcp -->|"queries SQL++"| node_asterix
node_fetch -->|"supplies shards"| node_loader
node_fetch -->|"downloads from"| node_asterix
node_loader -->|"provisions and loads"| node_asterix
node_predict -->|"fetches and persists"| node_sql_io
node_predict -->|"builds features"| node_features
node_sql_io -->|"uses SQL++ helper"| node_loader
node_sql_io -->|"reads and writes"| node_asterix
node_rightsize -->|"fetches and persists"| node_sql_io
node_rightsize -->|"stores recommendations"| node_asterix

click node_fetch "https://github.com/vivek1106-04/borgpilot/blob/main/ingestion/fetch_borg.py"
click node_loader "https://github.com/vivek1106-04/borgpilot/blob/main/ingestion/load_to_asterix.py"
click node_agent_loop "https://github.com/vivek1106-04/borgpilot/blob/main/agent/loop.py"
click node_prompts "https://github.com/vivek1106-04/borgpilot/blob/main/agent/prompts.py"
click node_sql_io "https://github.com/vivek1106-04/borgpilot/blob/main/sre/asterix_io.py"
click node_features "https://github.com/vivek1106-04/borgpilot/blob/main/sre/features.py"
click node_predict "https://github.com/vivek1106-04/borgpilot/blob/main/sre/predict.py"
click node_rightsize "https://github.com/vivek1106-04/borgpilot/blob/main/sre/rightsize.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_fetch,node_loader toneBlue
class node_agent_loop,node_prompts toneAmber
class node_features,node_predict toneMint
class node_rightsize toneRose
class node_asterix,node_sql_io,node_operator,node_mcp,node_llm toneIndigo
```

## Components

### Trace ingestion

- [Fetch Borg shards](https://github.com/vivek1106-04/borgpilot/blob/main/ingestion/fetch_borg.py): `ingestion/fetch_borg.py`
- [Provision and load](https://github.com/vivek1106-04/borgpilot/blob/main/ingestion/load_to_asterix.py): `ingestion/load_to_asterix.py`

### SRE investigation

- [Investigation loop](https://github.com/vivek1106-04/borgpilot/blob/main/agent/loop.py): `agent/loop.py`
- [SRE prompts](https://github.com/vivek1106-04/borgpilot/blob/main/agent/prompts.py): `agent/prompts.py`

### Failure prediction

- [Machine features](https://github.com/vivek1106-04/borgpilot/blob/main/sre/features.py): `sre/features.py`
- [Failure-risk scoring](https://github.com/vivek1106-04/borgpilot/blob/main/sre/predict.py): `sre/predict.py`

### Capacity rightsizing

- [Rightsizing analysis](https://github.com/vivek1106-04/borgpilot/blob/main/sre/rightsize.py): `sre/rightsize.py`

### Analytics store

- **AsterixDB**
- [AsterixDB SQL I/O](https://github.com/vivek1106-04/borgpilot/blob/main/sre/asterix_io.py): `sre/asterix_io.py`

### Other components

- **SRE operator**
- **AsterixDB MCP gateway**
- **Anthropic model**

## Connections

- SRE operator → Investigation loop: asks question (evidence: `README.md`)
- Investigation loop → SRE prompts: uses prompts (evidence: `agent/loop.py`)
- Investigation loop → Anthropic model: requests responses (evidence: `agent/loop.py`)
- Investigation loop → AsterixDB MCP gateway: calls tools (evidence: `agent/loop.py`)
- AsterixDB MCP gateway → AsterixDB: queries SQL++
- Fetch Borg shards → Provision and load: supplies shards (evidence: `ingestion/load_to_asterix.py`)
- Fetch Borg shards → AsterixDB: downloads from (evidence: `ingestion/fetch_borg.py`)
- Provision and load → AsterixDB: provisions and loads (evidence: `ingestion/load_to_asterix.py`)
- Failure-risk scoring → AsterixDB SQL I/O: fetches and persists (evidence: `sre/predict.py`)
- Failure-risk scoring → Machine features: builds features (evidence: `sre/predict.py`)
- AsterixDB SQL I/O → Provision and load: uses SQL++ helper (evidence: `sre/asterix_io.py`)
- AsterixDB SQL I/O → AsterixDB: reads and writes (evidence: `sre/asterix_io.py`)
- Rightsizing analysis → AsterixDB SQL I/O: fetches and persists (evidence: `sre/rightsize.py`)
- Rightsizing analysis → AsterixDB: stores recommendations (evidence: `README.md`)
