# vaishnavi220506/smartswap architecture

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

- Interactive diagram: https://gitdiagram.com/vaishnavi220506/smartswap
- Repository: https://github.com/vaishnavi220506/smartswap

## Overview

SmartSwap measures background interference on Windows, attributes stalls to CPU, memory, or storage, and applies verified mitigations to its own background workers. The principal workflow runs from the dashboard through the API and isolated trial runner into measurement, controller decisions, and native process controls; trial results return to the dashboard. The README also documents live monitoring, paired comparisons, reports, and a separate randomized study and analysis workflow. Some API and dashboard details are documented but their implementation excerpts are incomplete, so only evidenced connections are shown.

Main entry points: [`backend/engine.py`](https://github.com/vaishnavi220506/smartswap/blob/main/backend/engine.py) (Trial engine), [`backend/app.py`](https://github.com/vaishnavi220506/smartswap/blob/main/backend/app.py) (Web API), [`research/run_study.py`](https://github.com/vaishnavi220506/smartswap/blob/main/research/run_study.py) (Study runner), [`research/analyze.py`](https://github.com/vaishnavi220506/smartswap/blob/main/research/analyze.py) (Study analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_ui["Dashboard UI<br/>[app.js]"]
  node_api["Web API<br/>[app.py]"]
  node_db[("Run database<br/>[app.py]")]
end

subgraph group_runtime["Trial runtime"]
  node_runner["Isolated runner<br/>[trial_runner.py]"]
  node_engine["Trial engine<br/>[engine.py]"]
end

subgraph group_control["Control and measurement"]
  node_probes["Canary and workloads<br/>[probes.py]"]
  node_controller["WSI and policy ladder<br/>[controller.py]"]
  node_native["Verified Windows controls<br/>[native.py]"]
  node_stats["Statistics<br/>[stats.py]"]
end

subgraph group_research["Research"]
  node_study["Study runner<br/>[run_study.py]"]
  node_analysis["Study analysis<br/>[analyze.py]"]
  node_results["Study artifacts"]
end

node_user(("User"))

node_user -->|"uses"| node_ui
node_ui -->|"requests"| node_api
node_api -->|"launches"| node_runner
node_runner -->|"runs"| node_engine
node_engine -->|"starts probes"| node_probes
node_engine -->|"executes decisions"| node_controller
node_engine -->|"applies controls"| node_native
node_api -->|"calibrates"| node_engine
node_api -->|"persists runs"| node_db
node_api -->|"uses statistics"| node_stats
node_engine -.->|"returns trial data"| node_api
node_study -->|"runs trials"| node_engine
node_analysis -->|"uses statistics"| node_stats
node_analysis -.->|"writes analysis"| node_results
node_study -.->|"records trials"| node_results

click node_ui "https://github.com/vaishnavi220506/smartswap/blob/main/frontend/app.js"
click node_api "https://github.com/vaishnavi220506/smartswap/blob/main/backend/app.py"
click node_db "https://github.com/vaishnavi220506/smartswap/blob/main/backend/app.py"
click node_runner "https://github.com/vaishnavi220506/smartswap/blob/main/backend/trial_runner.py"
click node_engine "https://github.com/vaishnavi220506/smartswap/blob/main/backend/engine.py"
click node_probes "https://github.com/vaishnavi220506/smartswap/blob/main/backend/probes.py"
click node_controller "https://github.com/vaishnavi220506/smartswap/blob/main/backend/controller.py"
click node_native "https://github.com/vaishnavi220506/smartswap/blob/main/backend/native.py"
click node_stats "https://github.com/vaishnavi220506/smartswap/blob/main/backend/stats.py"
click node_study "https://github.com/vaishnavi220506/smartswap/blob/main/research/run_study.py"
click node_analysis "https://github.com/vaishnavi220506/smartswap/blob/main/research/analyze.py"
click node_results "https://github.com/vaishnavi220506/smartswap/tree/main/research/results"

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_ui,node_api,node_db,node_user toneBlue
class node_runner,node_engine toneAmber
class node_probes,node_controller,node_native,node_stats toneMint
class node_study,node_analysis,node_results toneRose
```

## Components

### Dashboard

- [Dashboard UI](https://github.com/vaishnavi220506/smartswap/blob/main/frontend/app.js): `frontend/app.js`
- [Web API](https://github.com/vaishnavi220506/smartswap/blob/main/backend/app.py): `backend/app.py`
- [Run database](https://github.com/vaishnavi220506/smartswap/blob/main/backend/app.py): `backend/app.py`

### Trial runtime

- [Isolated runner](https://github.com/vaishnavi220506/smartswap/blob/main/backend/trial_runner.py): `backend/trial_runner.py`
- [Trial engine](https://github.com/vaishnavi220506/smartswap/blob/main/backend/engine.py): `backend/engine.py`

### Control and measurement

- [Canary and workloads](https://github.com/vaishnavi220506/smartswap/blob/main/backend/probes.py): `backend/probes.py`
- [WSI and policy ladder](https://github.com/vaishnavi220506/smartswap/blob/main/backend/controller.py): `backend/controller.py`
- [Verified Windows controls](https://github.com/vaishnavi220506/smartswap/blob/main/backend/native.py): `backend/native.py`
- [Statistics](https://github.com/vaishnavi220506/smartswap/blob/main/backend/stats.py): `backend/stats.py`

### Research

- [Study runner](https://github.com/vaishnavi220506/smartswap/blob/main/research/run_study.py): `research/run_study.py`
- [Study analysis](https://github.com/vaishnavi220506/smartswap/blob/main/research/analyze.py): `research/analyze.py`
- [Study artifacts](https://github.com/vaishnavi220506/smartswap/tree/main/research/results): `research/results`

### Other components

- **User**

## Connections

- User → Dashboard UI: uses (evidence: `README.md`)
- Dashboard UI → Web API: requests (evidence: `frontend/app.js`)
- Web API → Isolated runner: launches (evidence: `backend/app.py`)
- Isolated runner → Trial engine: runs (evidence: `backend/trial_runner.py`)
- Trial engine → Canary and workloads: starts probes (evidence: `backend/engine.py`)
- Trial engine → WSI and policy ladder: executes decisions (evidence: `backend/engine.py`)
- Trial engine → Verified Windows controls: applies controls (evidence: `backend/engine.py`)
- Web API → Trial engine: calibrates (evidence: `backend/app.py`)
- Web API → Run database: persists runs (evidence: `backend/app.py`)
- Web API → Statistics: uses statistics (evidence: `backend/app.py`)
- Trial engine → Web API: returns trial data (evidence: `backend/app.py`)
- Study runner → Trial engine: runs trials (evidence: `research/run_study.py`)
- Study analysis → Statistics: uses statistics (evidence: `research/analyze.py`)
- Study analysis → Study artifacts: writes analysis
- Study runner → Study artifacts: records trials
