Ciiteddocs

Architecture

How the web app, CLI, and MCP server share one core.

One core, three surfaces

lib/queries.ts      ← Supabase reads (RLS via user JWT)
lib/agent-ops.ts    ← FastAPI writes (Bearer token)
lib/headless.ts     ← token + Supabase client factory
        ↑
  Next.js app   scripts/cli.ts   scripts/mcp.ts

The dashboard UI uses @supabase/ssr in server components. The CLI and MCP server use createClient from @supabase/supabase-js with CIITED_ACCESS_TOKEN — same RLS boundaries.

Writes (prompt edits, topics, alert acks) must go through lib/api.ts → FastAPI so plan limits and audit events stay enforced. Do not write benchmark orchestration from the frontend repo.

Out of scope (v1 headless)

  • Triggering benchmark runs
  • Workspace creation / onboarding
  • Competitor CRUD

Self-serve funnel (web only)

/audit (marketing)  → POST /public/instant-audits (Turnstile) → poll GET /public/instant-audits/{id}
                    → "Claim this report" → /sign-up?audit=<id>#claim=<token>
/sign-up, /sign-in  → /auth/continue (or /auth/callback after email confirm)
                    → POST /public/instant-audits/{id}/claim → /dashboard
/pricing            → POST /billing/checkout (signed in) or /sign-up?plan=growth|agency
/settings/plan      → GET /billing/summary, POST /billing/portal; Stripe returns to ?checkout=success

The claim token travels in the URL fragment because the marketing apex and app.* are different origins (separate localStorage); /sign-up also stashes it in user_metadata so confirming the email in another browser still claims the audit.

Env varPurpose
NEXT_PUBLIC_TURNSTILE_SITE_KEYCloudflare Turnstile widget on /audit
NEXT_PUBLIC_POSTHOG_KEY / NEXT_PUBLIC_POSTHOG_HOSTPostHog events: audit_started, audit_completed, signup_from_audit, checkout_started, subscription_active. No-op when unset

Stripe keys and price IDs live only on the backend.

Backend: authority-signal-backend.

On this page