# mukesh-2710/canary2 architecture

> Architecture diagram of the GitHub repository mukesh-2710/canary2, 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/mukesh-2710/canary2
- Repository: https://github.com/mukesh-2710/canary2

## Overview

CanaryGate ingests request telemetry, filters and segments it into endpoint/client cohorts, then evaluates new endpoints against absolute limits and established endpoints against stable traffic. The cohort verdicts drive a sticky traffic ramp and an audit trail. Operators use the React console to load scenarios, submit evaluations, inspect cohort and naive-global comparisons, and tune thresholds. The main orchestration and decision paths are visible in the sampled backend references; some UI-to-API and unsampled subsystem links are documented or left unverified.

Main entry points: [`backend/app/main.py`](https://github.com/mukesh-2710/canary2/blob/main/backend/app/main.py) (API routes), [`frontend/src/App.jsx`](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/App.jsx) (Console state and actions), [`backend/app/decision.py`](https://github.com/mukesh-2710/canary2/blob/main/backend/app/decision.py) (Cohort referee), [`frontend/src/api.js`](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Telemetry intake"]
  node_api["API routes<br/>[main.py]"]
  node_event_schema["Event models<br/>[models.py]"]
  node_otlp["OTLP normalization<br/>[telemetry.py]"]
  node_event_store[("Rolling event store<br/>[store.py]")]
  node_scenario_loader["Scenario generator<br/>[scenarios.py]"]
end

subgraph group_evaluation["Evaluation engine"]
  node_cohorting["Cohort segmentation<br/>[cohort.py]"]
  node_filters["Event filters<br/>[filters.py]"]
  node_decision["Cohort referee<br/>[decision.py]"]
  node_statistics["Statistical tests<br/>[stats.py]"]
  node_metric_plugins["Metric plugins<br/>[metrics.py]"]
  node_config["Decision thresholds<br/>[config.py]"]
end

subgraph group_rollout["Rollout control"]
  node_aggregation["Verdict aggregator<br/>[aggregator.py]"]
  node_audit["Evaluation audit<br/>[audit.py]"]
end

subgraph group_console["Operator console"]
  node_console["Console state and actions<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_scenario_ui["Scenario controls<br/>[ScenarioLoader.jsx]"]
  node_ingestion_ui["Ingestion panel<br/>[IngestionPanel.jsx]"]
  node_cohort_ui["Cohort results<br/>[CohortList.jsx]"]
  node_naive_ui["Naive comparison"]
  node_verdict_ui["Verdict display<br/>[VerdictBanner.jsx]"]
  node_strictness_ui["Threshold controls"]
  node_audit_ui["Audit timeline<br/>[AuditTimeline.jsx]"]
end

node_operator(("Operator"))
node_telemetry_source(("Telemetry source"))

node_telemetry_source -->|"sends telemetry"| node_api
node_api -->|"validates events"| node_event_schema
node_api -->|"normalizes traces"| node_otlp
node_api -->|"stores events"| node_event_store
node_api -->|"loads scenarios"| node_scenario_loader
node_api -->|"reads evaluation window"| node_event_store
node_api -->|"segments events"| node_cohorting
node_api -->|"evaluates cohorts"| node_decision
node_decision -->|"preprocesses events"| node_filters
node_decision -->|"tests degradation"| node_statistics
node_decision -->|"evaluates metrics"| node_metric_plugins
node_decision -->|"reads thresholds"| node_config
node_api -->|"aggregates verdicts"| node_aggregation
node_api -->|"records evaluations"| node_audit
node_aggregation -->|"uses ramp ladder"| node_config
node_operator -->|"operates"| node_console
node_console -->|"requests actions"| node_api_client
node_console -->|"renders"| node_scenario_ui
node_console -->|"renders"| node_ingestion_ui
node_console -->|"renders"| node_cohort_ui
node_console -->|"renders"| node_naive_ui
node_console -->|"renders"| node_verdict_ui
node_console -->|"renders"| node_strictness_ui
node_console -->|"renders"| node_audit_ui
node_api_client -.->|"calls HTTP endpoints"| node_api
node_api -->|"updates traffic ramp"| node_aggregation
node_audit_ui -->|"requests audit history"| node_api_client
node_strictness_ui -->|"reads and patches config"| node_api_client

click node_api "https://github.com/mukesh-2710/canary2/blob/main/backend/app/main.py"
click node_event_schema "https://github.com/mukesh-2710/canary2/blob/main/backend/app/models.py"
click node_otlp "https://github.com/mukesh-2710/canary2/blob/main/backend/app/telemetry.py"
click node_event_store "https://github.com/mukesh-2710/canary2/blob/main/backend/app/store.py"
click node_scenario_loader "https://github.com/mukesh-2710/canary2/blob/main/backend/app/scenarios.py"
click node_cohorting "https://github.com/mukesh-2710/canary2/blob/main/backend/app/cohort.py"
click node_filters "https://github.com/mukesh-2710/canary2/blob/main/backend/app/filters.py"
click node_decision "https://github.com/mukesh-2710/canary2/blob/main/backend/app/decision.py"
click node_statistics "https://github.com/mukesh-2710/canary2/blob/main/backend/app/stats.py"
click node_metric_plugins "https://github.com/mukesh-2710/canary2/blob/main/backend/app/metrics.py"
click node_config "https://github.com/mukesh-2710/canary2/blob/main/backend/app/config.py"
click node_aggregation "https://github.com/mukesh-2710/canary2/blob/main/backend/app/aggregator.py"
click node_audit "https://github.com/mukesh-2710/canary2/blob/main/backend/app/audit.py"
click node_console "https://github.com/mukesh-2710/canary2/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/mukesh-2710/canary2/blob/main/frontend/src/api.js"
click node_scenario_ui "https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/ScenarioLoader.jsx"
click node_ingestion_ui "https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/IngestionPanel.jsx"
click node_cohort_ui "https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/CohortList.jsx"
click node_naive_ui "https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/NaiveVsStratified.jsx"
click node_verdict_ui "https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/VerdictBanner.jsx"
click node_strictness_ui "https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/StrictnessPanel.jsx"
click node_audit_ui "https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/AuditTimeline.jsx"

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_api,node_event_schema,node_otlp,node_event_store,node_scenario_loader toneBlue
class node_cohorting,node_filters,node_decision,node_statistics,node_metric_plugins,node_config toneAmber
class node_aggregation,node_audit toneMint
class node_console,node_api_client,node_scenario_ui,node_ingestion_ui,node_cohort_ui,node_naive_ui,node_verdict_ui,node_strictness_ui,node_audit_ui toneRose
class node_operator,node_telemetry_source toneIndigo
```

## Components

### Telemetry intake

- [API routes](https://github.com/mukesh-2710/canary2/blob/main/backend/app/main.py): `backend/app/main.py`
- [Event models](https://github.com/mukesh-2710/canary2/blob/main/backend/app/models.py): `backend/app/models.py`
- [OTLP normalization](https://github.com/mukesh-2710/canary2/blob/main/backend/app/telemetry.py): `backend/app/telemetry.py`
- [Rolling event store](https://github.com/mukesh-2710/canary2/blob/main/backend/app/store.py): `backend/app/store.py`
- [Scenario generator](https://github.com/mukesh-2710/canary2/blob/main/backend/app/scenarios.py): `backend/app/scenarios.py`

### Evaluation engine

- [Cohort segmentation](https://github.com/mukesh-2710/canary2/blob/main/backend/app/cohort.py): `backend/app/cohort.py`
- [Event filters](https://github.com/mukesh-2710/canary2/blob/main/backend/app/filters.py): `backend/app/filters.py`
- [Cohort referee](https://github.com/mukesh-2710/canary2/blob/main/backend/app/decision.py): `backend/app/decision.py`
- [Statistical tests](https://github.com/mukesh-2710/canary2/blob/main/backend/app/stats.py): `backend/app/stats.py`
- [Metric plugins](https://github.com/mukesh-2710/canary2/blob/main/backend/app/metrics.py): `backend/app/metrics.py`
- [Decision thresholds](https://github.com/mukesh-2710/canary2/blob/main/backend/app/config.py): `backend/app/config.py`

### Rollout control

- [Verdict aggregator](https://github.com/mukesh-2710/canary2/blob/main/backend/app/aggregator.py): `backend/app/aggregator.py`
- [Evaluation audit](https://github.com/mukesh-2710/canary2/blob/main/backend/app/audit.py): `backend/app/audit.py`

### Operator console

- [Console state and actions](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Scenario controls](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/ScenarioLoader.jsx): `frontend/src/components/ScenarioLoader.jsx`
- [Ingestion panel](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/IngestionPanel.jsx): `frontend/src/components/IngestionPanel.jsx`
- [Cohort results](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/CohortList.jsx): `frontend/src/components/CohortList.jsx`
- [Naive comparison](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/NaiveVsStratified.jsx): `frontend/src/components/NaiveVsStratified.jsx`
- [Verdict display](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/VerdictBanner.jsx): `frontend/src/components/VerdictBanner.jsx`
- [Threshold controls](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/StrictnessPanel.jsx): `frontend/src/components/StrictnessPanel.jsx`
- [Audit timeline](https://github.com/mukesh-2710/canary2/blob/main/frontend/src/components/AuditTimeline.jsx): `frontend/src/components/AuditTimeline.jsx`

### Other components

- **Operator**
- **Telemetry source**

## Connections

- Telemetry source → API routes: sends telemetry (evidence: `README.md`)
- API routes → Event models: validates events (evidence: `backend/app/main.py`)
- API routes → OTLP normalization: normalizes traces (evidence: `backend/app/main.py`)
- API routes → Rolling event store: stores events (evidence: `backend/app/main.py`)
- API routes → Scenario generator: loads scenarios (evidence: `backend/app/main.py`)
- API routes → Rolling event store: reads evaluation window (evidence: `README.md`)
- API routes → Cohort segmentation: segments events (evidence: `backend/app/main.py`)
- API routes → Cohort referee: evaluates cohorts (evidence: `backend/app/main.py`)
- Cohort referee → Event filters: preprocesses events (evidence: `backend/app/decision.py`)
- Cohort referee → Statistical tests: tests degradation (evidence: `backend/app/decision.py`)
- Cohort referee → Metric plugins: evaluates metrics (evidence: `backend/app/decision.py`)
- Cohort referee → Decision thresholds: reads thresholds (evidence: `backend/app/decision.py`)
- API routes → Verdict aggregator: aggregates verdicts (evidence: `backend/app/main.py`)
- API routes → Evaluation audit: records evaluations (evidence: `backend/app/main.py`)
- Verdict aggregator → Decision thresholds: uses ramp ladder (evidence: `backend/app/aggregator.py`)
- Operator → Console state and actions: operates (evidence: `README.md`)
- Console state and actions → API client: requests actions (evidence: `frontend/src/App.jsx`)
- Console state and actions → Scenario controls: renders (evidence: `frontend/src/App.jsx`)
- Console state and actions → Ingestion panel: renders (evidence: `frontend/src/App.jsx`)
- Console state and actions → Cohort results: renders (evidence: `frontend/src/App.jsx`)
- Console state and actions → Naive comparison: renders (evidence: `frontend/src/App.jsx`)
- Console state and actions → Verdict display: renders (evidence: `frontend/src/App.jsx`)
- Console state and actions → Threshold controls: renders (evidence: `frontend/src/App.jsx`)
- Console state and actions → Audit timeline: renders (evidence: `frontend/src/App.jsx`)
- API client → API routes: calls HTTP endpoints
- API routes → Verdict aggregator: updates traffic ramp (evidence: `README.md`)
- Audit timeline → API client: requests audit history (evidence: `frontend/src/components/AuditTimeline.jsx`)
- Threshold controls → API client: reads and patches config (evidence: `frontend/src/components/StrictnessPanel.jsx`)
