Why It Matters
- Gap narratives explain a tenant’s risk posture in plain English, updated automatically as controls and evidence change.
- Remediation playbooks give actionable steps per control, tailored to cloud provider.
- Evidence & policy suggestions reduce manual work during audits.
- All content is cached with content-hash deduplication — regeneration only happens when underlying data actually changes.
Architecture at a Glance
Multi-Provider Fallback
The worker tries providers in priority order. If a provider fails 3 consecutive times, its circuit opens for 5 minutes. This survived a real Anthropic outage (April 15, 2026 — 1h 32m down) without user-visible impact.| Priority | Provider | Primary Model |
|---|---|---|
| 1 | Anthropic | claude-sonnet-4-20250514 |
| 2 | OpenAI | gpt-4.1 |
| 3 | gemini-2.5-pro | |
| 4 | Groq | llama-3.3-70b-versatile |
Key Design Decisions
| Decision | Rationale |
|---|---|
| Queue-based, not inline | AI calls take 2-15s; blocking the request path would destroy UX |
| Content-hash deduplication | Don’t regenerate if underlying data hasn’t changed — saves cost and avoids churn |
| Multi-provider with circuit breaker | Single-provider dependency is a production risk (proven by Anthropic outage) |
| Per-tenant budgets | Prevents runaway costs; tier-based defaults match subscription level |
| Edge Function worker | Runs in Supabase’s Deno runtime, triggered every 60s by pg_cron |
What It Replaces
Previously, gap narratives were generated inline during page load via a direct Anthropic API call. This had no fallback, no caching, no budget controls, and blocked rendering for 3-8 seconds. The new system is async, resilient, and cost-controlled.Content Types
| Type | Scope | Cache Key |
|---|---|---|
gap_narrative | Per tenant | Risk snapshot + control statuses + evidence timestamps |
remediation_playbook | Per control + cloud provider (shared) | Control key + title + description + implementation notes |
evidence_suggestion | Per evidence item | Title + description + evidence type + updated_at |
policy_suggestion | Per policy version | Policy ID + version ID |
Next Steps
Architecture
Database schema, worker details, cron schedules
Integration Guide
How to wire AI content into Next.js components
API Reference
All RPCs and their parameters
Operations
Runbook for monitoring, debugging, and recovery