# virtocommerce/ai-tools architecture

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

- Interactive diagram: https://gitdiagram.com/virtocommerce/ai-tools
- Repository: https://github.com/virtocommerce/ai-tools

## Overview

ai-tools is an agentic QA system for Virto Commerce, with the marketplace-installable vc-fix plugin as its flagship and a broader direct-clone QA crew. The primary workflow configures a project, routes a reported bug to the right repository and tracker, supports an autonomous fix, then verifies and transitions the ticket; monitoring is a parallel day-two workflow. The graph also preserves regression orchestration and performance tooling. Relationships for unsampled subsystems rely on README descriptions; omitted source limits finer call-level detail.

Main entry points: [`plugins/vc-fix`](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix) (Autonomous fix), [`ci/run-regression.ts`](https://github.com/virtocommerce/ai-tools/blob/main/ci/run-regression.ts) (Regression runner), [`plugins/vc-fix/skills/project-init`](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix/skills/project-init) (Project onboarding), [`plugins/vc-fix/skills/qa-fix-routing/repo-router.ts`](https://github.com/virtocommerce/ai-tools/blob/main/plugins/vc-fix/skills/qa-fix-routing/repo-router.ts) (Repository routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Bug lifecycle plugin"]
  node_project_init["Project onboarding"]
  node_bug_triage["Bug reproduction"]
  node_fix_agent["Autonomous fix"]
  node_fix_verify["Fix verification"]
  node_monitoring["Bug monitoring"]
end

subgraph group_integrations["Project integrations"]
  node_repo_router["Repository routing<br/>[repo-router.ts]"]
  node_tracker_adapters["Tracker adapters"]
  node_vcs_adapters["Code-host adapters"]
  node_tracker_service[("Jira or Azure Boards")]
  node_code_host[("GitHub or Azure Repos")]
end

subgraph group_regression["Regression QA"]
  node_monitor_runner["Monitoring runner<br/>[run-monitor.ts]"]
  node_appinsights["App Insights client<br/>[appinsights.ts]"]
  node_fingerprints[("Signal fingerprints")]
  node_regression_runner["Regression runner<br/>[run-regression.ts]"]
  node_suite_manifest["Suite selection<br/>[suite-manifest.ts]"]
  node_suite_scheduler["Lane scheduler<br/>[scheduler.ts]"]
  node_test_cases["Test-case curation"]
  node_app_insights_service[("Azure App Insights")]
end

subgraph group_performance["Performance QA"]
  node_perf_load["Load-test scenarios"]
  node_perf_trace["Trace analysis"]
  node_perf_compare["Benchmark comparison<br/>[compare-reports.cs]"]
end

subgraph group_shared["Shared configuration"]
  node_profile["Project profile"]
  node_env_config["Environment config<br/>[config.js]"]
end

node_operator(("QA operator"))
node_commerce_platform["Virto Commerce platform"]

node_operator -->|"onboards project"| node_project_init
node_project_init -->|"writes profile"| node_profile
node_project_init -->|"writes environment"| node_env_config
node_operator -->|"reports issue"| node_bug_triage
node_bug_triage -->|"files bug"| node_tracker_adapters
node_bug_triage -->|"routes fix"| node_repo_router
node_repo_router -->|"loads routing data"| node_profile
node_fix_agent -->|"selects repository"| node_repo_router
node_fix_agent -->|"contributes changes"| node_vcs_adapters
node_fix_agent -->|"updates bug"| node_tracker_adapters
node_operator -->|"requests fix"| node_fix_agent
node_operator -->|"requests verification"| node_fix_verify
node_fix_verify -->|"transitions ticket"| node_tracker_adapters
node_operator -->|"requests monitoring"| node_monitoring
node_monitor_runner -->|"queries telemetry"| node_appinsights
node_monitor_runner -->|"records signals"| node_fingerprints
node_monitoring -->|"queries telemetry"| node_app_insights_service
node_regression_runner -->|"resolves suites"| node_suite_manifest
node_regression_runner -->|"schedules lanes"| node_suite_scheduler
node_operator -->|"runs regression"| node_regression_runner
node_test_cases -.->|"supplies suite cases"| node_regression_runner
node_operator -.->|"runs load test"| node_perf_load
node_perf_load -.->|"generates workload"| node_commerce_platform
node_perf_trace -.->|"informs analysis"| node_perf_compare

click node_project_init "https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix/skills/project-init"
click node_profile "https://github.com/virtocommerce/ai-tools/blob/main/plugins/vc-fix/scripts/lib/project-profile.mjs"
click node_bug_triage "https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix"
click node_repo_router "https://github.com/virtocommerce/ai-tools/blob/main/plugins/vc-fix/skills/qa-fix-routing/repo-router.ts"
click node_tracker_adapters "https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix/skills/qa-fix-routing/trackers"
click node_vcs_adapters "https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix/skills/qa-fix-routing/vcs"
click node_fix_agent "https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix"
click node_fix_verify "https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix"
click node_monitoring "https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix/skills/qa-monitoring"
click node_monitor_runner "https://github.com/virtocommerce/ai-tools/blob/main/ci/run-monitor.ts"
click node_appinsights "https://github.com/virtocommerce/ai-tools/blob/main/ci/lib/appinsights.ts"
click node_fingerprints "https://github.com/virtocommerce/ai-tools/blob/main/ci/lib/fingerprint-store.ts"
click node_regression_runner "https://github.com/virtocommerce/ai-tools/blob/main/ci/run-regression.ts"
click node_suite_manifest "https://github.com/virtocommerce/ai-tools/blob/main/ci/lib/suite-manifest.ts"
click node_suite_scheduler "https://github.com/virtocommerce/ai-tools/blob/main/ci/lib/scheduler.ts"
click node_test_cases "https://github.com/virtocommerce/ai-tools/blob/main/scripts/test-cases/append-test-cases-to-suite.ts"
click node_perf_load "https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-perf/skills/perf-loadtest/loadtests/scenarios"
click node_perf_trace "https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-perf/skills/perf-trace/perftools"
click node_perf_compare "https://github.com/virtocommerce/ai-tools/blob/main/plugins/vc-perf/skills/perf-benchmark/compare-reports.cs"
click node_env_config "https://github.com/virtocommerce/ai-tools/blob/main/config.js"

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_project_init,node_bug_triage,node_fix_agent,node_fix_verify,node_monitoring toneBlue
class node_repo_router,node_tracker_adapters,node_vcs_adapters,node_tracker_service,node_code_host toneAmber
class node_monitor_runner,node_appinsights,node_fingerprints,node_regression_runner,node_suite_manifest,node_suite_scheduler,node_test_cases,node_app_insights_service toneMint
class node_perf_load,node_perf_trace,node_perf_compare toneRose
class node_profile,node_env_config,node_operator,node_commerce_platform toneIndigo
```

## Components

### Bug lifecycle plugin

- [Project onboarding](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix/skills/project-init): `plugins/vc-fix/skills/project-init`
- [Bug reproduction](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix): `plugins/vc-fix`
- [Autonomous fix](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix): `plugins/vc-fix`
- [Fix verification](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix): `plugins/vc-fix`
- [Bug monitoring](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix/skills/qa-monitoring): `plugins/vc-fix/skills/qa-monitoring`

### Project integrations

- [Repository routing](https://github.com/virtocommerce/ai-tools/blob/main/plugins/vc-fix/skills/qa-fix-routing/repo-router.ts): `plugins/vc-fix/skills/qa-fix-routing/repo-router.ts`
- [Tracker adapters](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix/skills/qa-fix-routing/trackers): `plugins/vc-fix/skills/qa-fix-routing/trackers`
- [Code-host adapters](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-fix/skills/qa-fix-routing/vcs): `plugins/vc-fix/skills/qa-fix-routing/vcs`
- **Jira or Azure Boards**
- **GitHub or Azure Repos**

### Regression QA

- [Monitoring runner](https://github.com/virtocommerce/ai-tools/blob/main/ci/run-monitor.ts): `ci/run-monitor.ts`
- [App Insights client](https://github.com/virtocommerce/ai-tools/blob/main/ci/lib/appinsights.ts): `ci/lib/appinsights.ts`
- [Signal fingerprints](https://github.com/virtocommerce/ai-tools/blob/main/ci/lib/fingerprint-store.ts): `ci/lib/fingerprint-store.ts`
- [Regression runner](https://github.com/virtocommerce/ai-tools/blob/main/ci/run-regression.ts): `ci/run-regression.ts`
- [Suite selection](https://github.com/virtocommerce/ai-tools/blob/main/ci/lib/suite-manifest.ts): `ci/lib/suite-manifest.ts`
- [Lane scheduler](https://github.com/virtocommerce/ai-tools/blob/main/ci/lib/scheduler.ts): `ci/lib/scheduler.ts`
- [Test-case curation](https://github.com/virtocommerce/ai-tools/blob/main/scripts/test-cases/append-test-cases-to-suite.ts): `scripts/test-cases/append-test-cases-to-suite.ts`
- **Azure App Insights**

### Performance QA

- [Load-test scenarios](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-perf/skills/perf-loadtest/loadtests/scenarios): `plugins/vc-perf/skills/perf-loadtest/loadtests/scenarios`
- [Trace analysis](https://github.com/virtocommerce/ai-tools/tree/main/plugins/vc-perf/skills/perf-trace/perftools): `plugins/vc-perf/skills/perf-trace/perftools`
- [Benchmark comparison](https://github.com/virtocommerce/ai-tools/blob/main/plugins/vc-perf/skills/perf-benchmark/compare-reports.cs): `plugins/vc-perf/skills/perf-benchmark/compare-reports.cs`

### Shared configuration

- [Project profile](https://github.com/virtocommerce/ai-tools/blob/main/plugins/vc-fix/scripts/lib/project-profile.mjs): `plugins/vc-fix/scripts/lib/project-profile.mjs`
- [Environment config](https://github.com/virtocommerce/ai-tools/blob/main/config.js): `config.js`

### Other components

- **QA operator**
- **Virto Commerce platform**

## Connections

- QA operator → Project onboarding: onboards project (evidence: `README.md`)
- Project onboarding → Project profile: writes profile (evidence: `README.md`)
- Project onboarding → Environment config: writes environment (evidence: `README.md`)
- QA operator → Bug reproduction: reports issue (evidence: `README.md`)
- Bug reproduction → Tracker adapters: files bug (evidence: `README.md`)
- Bug reproduction → Repository routing: routes fix (evidence: `README.md`)
- Repository routing → Project profile: loads routing data (evidence: `plugins/vc-fix/skills/qa-fix-routing/repo-router.ts`)
- Autonomous fix → Repository routing: selects repository (evidence: `plugins/vc-fix/skills/qa-fix-routing/repo-router.ts`)
- Autonomous fix → Code-host adapters: contributes changes (evidence: `README.md`)
- Autonomous fix → Tracker adapters: updates bug (evidence: `README.md`)
- QA operator → Autonomous fix: requests fix (evidence: `README.md`)
- QA operator → Fix verification: requests verification (evidence: `README.md`)
- Fix verification → Tracker adapters: transitions ticket (evidence: `README.md`)
- QA operator → Bug monitoring: requests monitoring (evidence: `README.md`)
- Monitoring runner → App Insights client: queries telemetry (evidence: `ci/run-monitor.ts`)
- Monitoring runner → Signal fingerprints: records signals (evidence: `ci/run-monitor.ts`)
- Bug monitoring → Azure App Insights: queries telemetry (evidence: `README.md`)
- Regression runner → Suite selection: resolves suites (evidence: `ci/run-regression.ts`)
- Regression runner → Lane scheduler: schedules lanes (evidence: `ci/run-regression.ts`)
- QA operator → Regression runner: runs regression (evidence: `README.md`)
- Test-case curation → Regression runner: supplies suite cases (evidence: `ci/run-regression.ts`)
- QA operator → Load-test scenarios: runs load test
- Load-test scenarios → Virto Commerce platform: generates workload
- Trace analysis → Benchmark comparison: informs analysis
