# vikashftw/canary architecture

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

- Interactive diagram: https://gitdiagram.com/vikashftw/canary
- Repository: https://github.com/vikashftw/canary

## Overview

Bloodhound is an autonomous QA and bug-remediation system: a browser explorer checks expected versus observed behavior while Sentry captures thrown errors and traces; both feed findings into deduplicating triage, which diagnoses, proposes a fix, and produces a regression test. The dashboard presents runs, traces, fixes, and memory, alongside an instrumented checkout demo and autonomy controls. The README documents the end-to-end handoffs; source excerpts confirm the triage sequence, trace access, memory capabilities, and checkout behavior. Some web and explorer integrations are unsampled, so their internal connections are not expanded.

Main entry points: [`src/triage/engine.ts`](https://github.com/vikashftw/canary/blob/main/src/triage/engine.ts) (Triage engine), [`web/src/app/_components/RunController.tsx`](https://github.com/vikashftw/canary/blob/main/web/src/app/_components/RunController.tsx) (Run dashboard), [`src/contracts/finding.ts`](https://github.com/vikashftw/canary/blob/main/src/contracts/finding.ts) (Finding contract), [`src/memory/index.ts`](https://github.com/vikashftw/canary/blob/main/src/memory/index.ts) (Memory services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Detection"]
  node_explorer["Browser explorer"]
  node_browser["Headless browser"]
  node_sentry_capture["Sentry capture"]
  node_finding["Finding contract<br/>[finding.ts]"]
end

subgraph group_triage["Triage &amp; Remediation"]
  node_triage_engine["Triage engine<br/>[engine.ts]"]
  node_trace_access["Trace access<br/>[trace-client.ts]"]
  node_trace_data["Trace data<br/>[trace.ts]"]
  node_judge["Root-cause judge<br/>[judge.ts]"]
  node_llm["LLM client<br/>[llm.ts]"]
  node_fixer["Fix strategies<br/>[fixer.ts]"]
  node_regression["Regression author<br/>[regression.ts]"]
  node_verifier["Fix verifier<br/>[verifier.ts]"]
  node_resolution["Resolution contract<br/>[resolution.ts]"]
  node_canonical_cache[("Canonical fix cache<br/>[canonical.ts]")]
end

subgraph group_memory["Memory"]
  node_memory_api["Memory services<br/>[index.ts]"]
  node_finding_store[("Finding history<br/>[finding-store.ts]")]
  node_vector_recall["Semantic recall"]
end

subgraph group_dashboard["Dashboard &amp; Demo"]
  node_dashboard["Run dashboard<br/>[RunController.tsx]"]
  node_run_api["Run API<br/>[route.ts]"]
  node_autonomy["Autonomy controls<br/>[autonomy-runner.ts]"]
  node_checkout_ui["Checkout demo<br/>[page.tsx]"]
  node_checkout_state[("Cart and findings<br/>[_cart.ts]")]
end

subgraph group_integrations["External Services"]
  node_redis[("Redis")]
  node_sentry["Sentry"]
  node_anthropic["Anthropic"]
end

node_operator(("QA operator"))

node_operator -->|"starts run"| node_dashboard
node_dashboard -->|"requests run"| node_run_api
node_operator -.->|"initiates exploration"| node_explorer
node_explorer -.->|"drives actions"| node_browser
node_explorer -.->|"emits findings"| node_finding
node_sentry_capture -.->|"captures errors"| node_sentry
node_sentry -.->|"raises findings"| node_finding
node_finding -->|"enters triage"| node_triage_engine
node_triage_engine -->|"fetches trace"| node_trace_access
node_trace_access -->|"requests trace"| node_sentry
node_trace_access -->|"maps response"| node_trace_data
node_triage_engine -->|"judges finding"| node_judge
node_judge -.->|"requests completion"| node_llm
node_triage_engine -->|"selects fix"| node_fixer
node_fixer -.->|"requests fix"| node_llm
node_triage_engine -->|"uses fallback"| node_canonical_cache
node_triage_engine -->|"creates test"| node_regression
node_triage_engine -->|"verifies resolution"| node_verifier
node_triage_engine -->|"produces resolution"| node_resolution
node_triage_engine -.->|"shares dedup contract"| node_memory_api
node_memory_api -->|"exposes history"| node_finding_store
node_memory_api -->|"exposes recall"| node_vector_recall
node_finding_store -.->|"stores canonical history"| node_sentry
node_vector_recall -.->|"searches vectors"| node_redis
node_memory_api -.->|"connects optionally"| node_redis
node_llm -->|"sends completion"| node_anthropic
node_dashboard -->|"displays outcome"| node_resolution
node_dashboard -->|"shows finding"| node_finding
node_dashboard -.->|"offers controls"| node_autonomy
node_checkout_ui -.->|"uses checkout"| node_checkout_state
node_checkout_state -->|"records finding"| node_finding

click node_explorer "https://github.com/vikashftw/canary/tree/main/explorer"
click node_sentry_capture "https://github.com/vikashftw/canary/blob/main/web/instrumentation-client.ts"
click node_finding "https://github.com/vikashftw/canary/blob/main/src/contracts/finding.ts"
click node_triage_engine "https://github.com/vikashftw/canary/blob/main/src/triage/engine.ts"
click node_trace_access "https://github.com/vikashftw/canary/blob/main/src/sentry/trace-client.ts"
click node_trace_data "https://github.com/vikashftw/canary/blob/main/src/sentry/trace.ts"
click node_judge "https://github.com/vikashftw/canary/blob/main/src/triage/judge.ts"
click node_llm "https://github.com/vikashftw/canary/blob/main/src/triage/llm.ts"
click node_fixer "https://github.com/vikashftw/canary/blob/main/src/triage/fixer.ts"
click node_regression "https://github.com/vikashftw/canary/blob/main/src/triage/regression.ts"
click node_verifier "https://github.com/vikashftw/canary/blob/main/src/triage/verifier.ts"
click node_resolution "https://github.com/vikashftw/canary/blob/main/src/contracts/resolution.ts"
click node_canonical_cache "https://github.com/vikashftw/canary/blob/main/src/cache/canonical.ts"
click node_memory_api "https://github.com/vikashftw/canary/blob/main/src/memory/index.ts"
click node_finding_store "https://github.com/vikashftw/canary/blob/main/src/memory/finding-store.ts"
click node_vector_recall "https://github.com/vikashftw/canary/blob/main/src/memory/similar-findings.ts"
click node_dashboard "https://github.com/vikashftw/canary/blob/main/web/src/app/_components/RunController.tsx"
click node_run_api "https://github.com/vikashftw/canary/blob/main/web/src/app/api/run/route.ts"
click node_autonomy "https://github.com/vikashftw/canary/blob/main/web/src/lib/autonomy-runner.ts"
click node_checkout_ui "https://github.com/vikashftw/canary/blob/main/web/src/app/checkout/page.tsx"
click node_checkout_state "https://github.com/vikashftw/canary/blob/main/web/src/app/api/checkout/_cart.ts"

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_explorer,node_browser,node_sentry_capture,node_finding toneBlue
class node_triage_engine,node_trace_access,node_trace_data,node_judge,node_llm,node_fixer,node_regression,node_verifier,node_resolution,node_canonical_cache toneAmber
class node_memory_api,node_finding_store,node_vector_recall toneMint
class node_dashboard,node_run_api,node_autonomy,node_checkout_ui,node_checkout_state toneRose
class node_redis,node_sentry,node_anthropic,node_operator toneIndigo
```

## Components

### Detection

- [Browser explorer](https://github.com/vikashftw/canary/tree/main/explorer): `explorer`
- **Headless browser**
- [Sentry capture](https://github.com/vikashftw/canary/blob/main/web/instrumentation-client.ts): `web/instrumentation-client.ts`
- [Finding contract](https://github.com/vikashftw/canary/blob/main/src/contracts/finding.ts): `src/contracts/finding.ts`

### Triage & Remediation

- [Triage engine](https://github.com/vikashftw/canary/blob/main/src/triage/engine.ts): `src/triage/engine.ts`
- [Trace access](https://github.com/vikashftw/canary/blob/main/src/sentry/trace-client.ts): `src/sentry/trace-client.ts`
- [Trace data](https://github.com/vikashftw/canary/blob/main/src/sentry/trace.ts): `src/sentry/trace.ts`
- [Root-cause judge](https://github.com/vikashftw/canary/blob/main/src/triage/judge.ts): `src/triage/judge.ts`
- [LLM client](https://github.com/vikashftw/canary/blob/main/src/triage/llm.ts): `src/triage/llm.ts`
- [Fix strategies](https://github.com/vikashftw/canary/blob/main/src/triage/fixer.ts): `src/triage/fixer.ts`
- [Regression author](https://github.com/vikashftw/canary/blob/main/src/triage/regression.ts): `src/triage/regression.ts`
- [Fix verifier](https://github.com/vikashftw/canary/blob/main/src/triage/verifier.ts): `src/triage/verifier.ts`
- [Resolution contract](https://github.com/vikashftw/canary/blob/main/src/contracts/resolution.ts): `src/contracts/resolution.ts`
- [Canonical fix cache](https://github.com/vikashftw/canary/blob/main/src/cache/canonical.ts): `src/cache/canonical.ts`

### Memory

- [Memory services](https://github.com/vikashftw/canary/blob/main/src/memory/index.ts): `src/memory/index.ts`
- [Finding history](https://github.com/vikashftw/canary/blob/main/src/memory/finding-store.ts): `src/memory/finding-store.ts`
- [Semantic recall](https://github.com/vikashftw/canary/blob/main/src/memory/similar-findings.ts): `src/memory/similar-findings.ts`

### Dashboard & Demo

- [Run dashboard](https://github.com/vikashftw/canary/blob/main/web/src/app/_components/RunController.tsx): `web/src/app/_components/RunController.tsx`
- [Run API](https://github.com/vikashftw/canary/blob/main/web/src/app/api/run/route.ts): `web/src/app/api/run/route.ts`
- [Autonomy controls](https://github.com/vikashftw/canary/blob/main/web/src/lib/autonomy-runner.ts): `web/src/lib/autonomy-runner.ts`
- [Checkout demo](https://github.com/vikashftw/canary/blob/main/web/src/app/checkout/page.tsx): `web/src/app/checkout/page.tsx`
- [Cart and findings](https://github.com/vikashftw/canary/blob/main/web/src/app/api/checkout/_cart.ts): `web/src/app/api/checkout/_cart.ts`

### External Services

- **Redis**
- **Sentry**
- **Anthropic**

### Other components

- **QA operator**

## Connections

- QA operator → Run dashboard: starts run (evidence: `web/src/app/_components/RunController.tsx`)
- Run dashboard → Run API: requests run (evidence: `web/src/app/_components/RunController.tsx`)
- QA operator → Browser explorer: initiates exploration (evidence: `README.md`)
- Browser explorer → Headless browser: drives actions (evidence: `README.md`)
- Browser explorer → Finding contract: emits findings (evidence: `README.md`)
- Sentry capture → Sentry: captures errors (evidence: `README.md`)
- Sentry → Finding contract: raises findings (evidence: `README.md`)
- Finding contract → Triage engine: enters triage (evidence: `README.md`)
- Triage engine → Trace access: fetches trace (evidence: `src/triage/engine.ts`)
- Trace access → Sentry: requests trace (evidence: `src/sentry/trace-client.ts`)
- Trace access → Trace data: maps response (evidence: `src/sentry/trace-client.ts`)
- Triage engine → Root-cause judge: judges finding (evidence: `src/triage/engine.ts`)
- Root-cause judge → LLM client: requests completion
- Triage engine → Fix strategies: selects fix (evidence: `src/triage/engine.ts`)
- Fix strategies → LLM client: requests fix
- Triage engine → Canonical fix cache: uses fallback (evidence: `src/triage/engine.ts`)
- Triage engine → Regression author: creates test (evidence: `src/triage/engine.ts`)
- Triage engine → Fix verifier: verifies resolution (evidence: `src/triage/engine.ts`)
- Triage engine → Resolution contract: produces resolution (evidence: `README.md`)
- Triage engine → Memory services: shares dedup contract (evidence: `src/memory/index.ts`)
- Memory services → Finding history: exposes history (evidence: `src/memory/index.ts`)
- Memory services → Semantic recall: exposes recall (evidence: `src/memory/index.ts`)
- Finding history → Sentry: stores canonical history
- Semantic recall → Redis: searches vectors
- Memory services → Redis: connects optionally (evidence: `src/memory/index.ts`)
- LLM client → Anthropic: sends completion (evidence: `src/triage/llm.ts`)
- Run dashboard → Resolution contract: displays outcome (evidence: `README.md`)
- Run dashboard → Finding contract: shows finding (evidence: `README.md`)
- Run dashboard → Autonomy controls: offers controls (evidence: `README.md`)
- Checkout demo → Cart and findings: uses checkout (evidence: `README.md`)
- Cart and findings → Finding contract: records finding (evidence: `web/src/app/api/checkout/_cart.ts`)
