Skip to main content

​
Integrations

Follow the guide in docs/adding-new-integration.md in the repository. The high-level steps:
  1. Insert a provider row in integration_providers and integration_provider_display
  2. Create a new Edge Function at supabase/functions/sync-{slug}/index.ts
  3. Implement entity sync and finding detection logic
  4. Register the provider’s OAuth client credentials (scopes, redirect URI)
  5. Add the provider to the trigger-sync dispatcher switch statement
  6. Map findings to unified controls for evidence materialization
See the Integration Engine docs for the full architecture.
Check these in order:
  1. Sync job status: Query integration_sync_jobs for the connection 
    SELECT * FROM integration_sync_jobs
WHERE connection_id = 'uuid' ORDER BY started_at DESC LIMIT 5;
  2. Sync logs: Check integration_sync_log for detailed error messages
  3. Edge Function logs: 
    supabase functions logs sync-azure-ad --project-ref hcyyegiialkkjcdxpfat
  4. Token validity: Check if the OAuth token has expired and the refresh failed
  5. Provider API: Verify the provider API is not rate-limited or down
See the Debugging Guide for more common issues.

​
Risk and Scoring

The risk score is a composite 0-100 value (100 = best) computed from four weighted components:
  • Control Maturity (35%): Average maturity across enabled controls
  • Evidence Coverage (25%): Percentage of controls with accepted evidence
  • Framework Compliance (25%): Weighted framework readiness scores
  • Integration Findings (15%): Severity-weighted open findings
Scores are recomputed nightly at 2 AM UTC via pg_cron and on significant events (evidence accepted, findings resolved).See the Risk Scoring docs for the full model.

​
Billing

  1. Set Stripe environment variables in .env.local: 
    STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
  2. Create products and prices in the Stripe Dashboard (or via Stripe CLI)
  3. Configure the webhook endpoint in Stripe to point to {APP_URL}/api/billing/webhook
  4. For local testing, use the Stripe CLI to forward webhooks: 
    stripe listen --forward-to localhost:3000/api/billing/webhook
  5. The webhook handler processes checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, and invoice.payment_failed events.

​
Frameworks

  1. Insert the framework in compliance_frameworks: 
    INSERT INTO compliance_frameworks (id, name, slug, version, description)
VALUES (gen_random_uuid(), 'PCI DSS 4.0', 'pci-dss-4', '4.0', 'Payment Card Industry Data Security Standard');
  2. Add requirements to framework_requirements with the framework ID
  3. Map requirements to unified controls in control_framework_map
  4. The framework will automatically appear in the tenant framework selection UI and readiness dashboards
Use the existing SOC 2 or ISO 27001 mappings as a reference for how to structure the control_framework_map entries.

​
AI Features

AI is powered by Anthropic Claude and used in two places:
  1. Evidence Classification (evidence_classify Edge Function): Automatically categorizes uploaded evidence and suggests control mappings based on content analysis.
  2. Assessment Analysis: Processes assessment responses to generate recommendations and risk insights.
All AI calls are server-side only. The ANTHROPIC_API_KEY is stored as a Supabase Edge Function secret and is never exposed to the client.To extend AI capabilities, add new Edge Functions or Server Actions that call the Anthropic API.

​
Assessments

When a prospect completes an assessment:
  1. rpc_complete_assessment calculates scores and generates recommendations
  2. A partner or admin calls rpc_convert_assessment_to_tenant to create a tenant
  3. The conversion function:
    • Creates a tenants record from the company info
    • Sets up tenant_memberships for the owner
    • Pre-populates tenant_controls based on assessment answers
    • Selects recommended frameworks
    • Updates the assessment status to 'converted'
See the Assessment Engine docs for details.

​
Development

supabase gen types typescript --project-id hcyyegiialkkjcdxpfat > packages/supabase/src/database.types.ts
Run this after every migration to keep types in sync with the schema.
  1. Start Supabase locally: supabase start
  2. Create a test user via the Auth dashboard at localhost:54323
  3. Use the authenticated client to make queries
  4. Verify that queries only return data for the user’s tenant
For quick validation, compare results between getSupabaseServerClient() (RLS enforced) and getSupabaseServerAdminClient() (RLS bypassed).