Architecture Diagrams
Signal tier topology, decision pipeline, provider hierarchy, fallback chain, SAIQ framework, and enforcement path.
Decision Pipeline
Every authorization request flows through the same deterministic pipeline. No branching on provider availability — degraded providers are handled transparently by the cache hierarchy before the hot path is reached.
Signal Tier Architecture
Providers are ranked by trust tier. The routing engine selects the lowest defensible signal — never an average. Every tier has a defined fallback.
Cache Architecture
All provider data flows through the cache hierarchy. The hot path never calls external providers directly.
SAIQ Governance Framework
The four-layer evaluation model applied to every authorization request. Layers execute sequentially within the latency budget.
Resolve authoritative signal value from provider hierarchy. Apply Lowest Defensible Signal doctrine. No provider averaging. Return with source, freshness, estimated/synthetic flags.
Multi-objective scoring against evaluation order: Policy → Water → SLA → Carbon → Cost. Exit early on hard policy or water violation. Return action candidate with reasoning chain.
Provenance validation. Provider disagreement detection and classification (none/low/medium/high/severe). Fallback documentation. Policy trace assembly.
Confidence scoring. Quality tier assignment (HIGH/MEDIUM/LOW). Governance lease calculation. Operating mode determination (NORMAL/STRESS/CRISIS). proofHash computation.
Five-Level Fallback Chain
Degradation is transparent and documented. Every fallback level sets the appropriate flags in the decision output.
| Level | Source | Condition | Flags Set |
|---|---|---|---|
| L1 | Live provider data | Normal operation — fresh signal | estimatedFlag per provider · HIGH tier |
| L2 | Warm cache (15min) | Background worker recent success | fallbackUsed=false · MEDIUM tier possible |
| L3 | Warm cache (1–6hr) | Provider degraded but not dead | fallbackUsed=true · LOW tier · leaseExpiry=30min |
| L4 | Ember structural baseline | All real-time providers failed | syntheticFlag=true · LOW · Ember-sourced note in policyTrace |
| L5 | Static 450 gCO₂/kWh | All data paths failed | syntheticFlag=true · LOW · operatingMode=CRISIS |
Enforcement Path
CO₂Router integrates at the execution boundary — the moment before compute resources are provisioned. Two primary integration patterns:
# .github/workflows/build.yml
- name: Authorize execution
run: |
DECISION=$(curl -s \
-H "Authorization: Bearer $CO2_TOKEN" \
-d '{"workloadId":"'$GITHUB_RUN_ID'",
"regions":["us-east-1","eu-west-1"],
"deadline":"'$DEADLINE'"}' \
$CO2_ROUTER_URL/api/v1/authorize)
ACTION=$(echo $DECISION | jq -r '.decision')
if [ "$ACTION" = "deny" ]; then
echo "::error::Execution denied by CO₂Router"
exit 1
fi
echo "Authorized: $ACTION"
echo "Region: $(echo $DECISION | jq -r '.selectedRegion')"
echo "Carbon: $(echo $DECISION | jq -r '.carbonIntensity')g/kWh"# ValidatingWebhookConfiguration
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: co2router-admission
webhooks:
- name: authorize.co2router.io
rules:
- apiGroups: ["batch"]
resources: ["jobs"]
operations: ["CREATE"]
clientConfig:
service:
name: co2router-webhook
namespace: co2router-system
path: /admission/authorize
failurePolicy: Fail # Hard stop on denyInitial Region Scope
| Region | Cloud Providers | Primary Signal | EIA-930 Coverage |
|---|---|---|---|
us-east-1 | AWS / GCP / Azure | WattTime (PJM) | Yes — PJM BA |
us-west-2 | AWS / GCP / Azure | WattTime (CAISO_NORTH) | Yes — CAISO BA |
eu-west-1 | AWS / GCP / Azure | Electricity Maps (IE) | No — Electricity Maps only |
eu-central-1 | AWS / GCP / Azure | Electricity Maps (DE) | No — Electricity Maps only |
ap-southeast-1 | AWS / GCP / Azure | Electricity Maps (SG) | No — Electricity Maps only |
ap-northeast-1 | AWS / GCP / Azure | Electricity Maps (JP) | No — Electricity Maps only |
Core Data Model Relationships
DecisionLog (append-only)
├── CarbonCommand (per-request, 22 required fields)
│ └── CarbonLedgerEntry (audit-grade accounting)
├── GridSignalSnapshot[] (one per candidate region)
│ └── ProviderSnapshot[] (one per active provider per region)
├── MultiSignalSnapshot (MSS — provenance summary)
│ ├── carbonLineage: string[]
│ └── waterLineage: string[]
├── DecisionTraceEnvelope (full canonical state)
│ └── proofHash: SHA-256
└── WaterBundle (nullable — facility data)
├── scenario: "current" | "2030" | "2050" | "2080"
└── sources: Aqueduct21 | AWARE20 | WWFWaterRisk