System context (C4 level 1)

The C1 view: PolicyCodex as one system, its people, and its external dependencies.

What each relationship means in practice

Counterparty	Direction	Mechanism	Breaks how?
Clerk	inbound sessions; inbound webhooks	Users sign in via Clerk; `clerk-webhook` syncs orgs/members/roles/subscriptions into Postgres; `clerk-to-resend` (a second, separate webhook endpoint) forwards signup/billing events to Resend	Sign-in failures, missing roles, wrong entitlements — see Auth and roles
GitHub	inbound webhooks; outbound API	The policy-codex GitHub App (App ID `4542396`) delivers `pull_request` webhooks to the worker, which enqueues checks; the worker posts completed check runs named `PolicyCodex` back, and rulesets pin that check as required	Checks never appear, or PRs mergeable when they shouldn’t be — see Enforcement
LLM provider	outbound	`checkCompliance` (diff checks, full scans) and `extract-statements` call an OpenAI-compatible chat-completions API. Per-org Settings → LLM overrides the worker’s fallback secrets	Checks pass that should fail, extraction rejects output — see Enforcement and Web troubleshooting
Resend	outbound events; inbound webhooks	`clerk-to-resend` fires trigger events; Resend Automations do all sequencing; `resend-webhook` syncs delivery/open/click events back into Postgres	Emails not sending or events missing — see Growth data flows
Cal.com	inbound webhook	`cal-webhook` converts `BOOKING_CREATED` into a `website_leads` row (HMAC-verified, Cal.com’s own scheme — not Svix)	Bookings not appearing as leads — see Growth troubleshooting
Cloudflare	hosting	Pages serves the four SPAs and the docs; Workers runs the API/MCP worker with a 1-minute cron	Deploy confusion — see Environments

One system, many front doors. The web app, demo console, growth app, marketing site and docs are all thin surfaces over the same two backends: the Supabase Postgres database (with its Edge Functions) and the Cloudflare worker. If two surfaces disagree about data, the database is the truth; if an action fails on every surface at once, suspect the worker or an Edge Function rather than the SPAs.

Start here

Architecture (C4)

Database

What each relationship means in practice

​What each relationship means in practice

What each relationship means in practice