Key facts

Everything on this page is stable, non-secret reference data. When an answer needs a specific name or id, it should come from here.

URLs

Surface	URL
Web application	https://app.policycodex.cloud
Marketing site	https://www.policycodex.cloud
User docs	https://docs.policycodex.cloud
Demo console	https://demo.policycodex.cloud
Growth console (internal)	Pages project `policycodex-growth` — no custom domain confirmed; default is `policycodex-growth.pages.dev`
Worker (REST `/v1/*`, MCP `/mcp`, GitHub webhook `/github/webhook`)	https://mcp.policycodex.cloud
Supabase project	https://gcfhhymqqlbmomkxrxuj.supabase.co (Edge Functions under `/functions/v1/<name>`)

Identifiers

Thing	Value
Supabase project ref	`gcfhhymqqlbmomkxrxuj`
Postgres schema	`codex`
Clerk instance (development, shared by all SPAs)	`active-cheetah-78`
GitHub App	slug `policy-codex`, App ID `4542396`, check-run name `PolicyCodex`
Production GitHub org / repo	`Policy-Codex` / `policycodex`
Demo GitHub org	`acme-policycodex-demo` (repos: `acme-payments-api`, `acme-web`, `acme-handbook`)
Demo Clerk org	`org_3HqU0509WZL6SJoTSPyrbMJnfOi` (ACME Corp, slug `acme-corp`)
Demo codex org id	`cc8d928f-0410-44b1-a6d9-d07cabc4acb6`
Demo GitHub App installation	`153344346`
Demo users	`owner` / `author` / `viewer` `+clerk_test@acme.example.com`, email OTP `424242`
Retired seed org	`11111111-1111-4111-8111-111111111111` (`retired-demo-fintech`; audit rows + husk row only, memberless)
API key format	`pcx_` + 48 hex chars; stored as sha256 in `api_keys.key_hash`; 12-char prefix shown in UI
Reference LLM for compliance checks	`openai/gpt-4.1` via OpenRouter (`response_format: json_object` required)

Worker endpoints

Route	Auth	Purpose
`GET /`	none	Health / route listing
`GET /v1/domains`, `/v1/statements`, `/v1/rfcs/:slug`, `/v1/compile/agents-md`, `/v1/audit/export`	org API key	Read paths
`POST /v1/check`	org API key	Compliance check (diff evidence; `repo` optional — omitting it keeps probes out of Coverage)
`POST /v1/scan`	org API key	Queue full-repo scan (cooldown; `github_scanning` entitlement at execution)
`POST /v1/violations`	org API key	Action posts findings
`POST /github/webhook`	HMAC (`GITHUB_WEBHOOK_SECRET`)	App events → pending_checks
`/mcp`	org API key	MCP: `list_domains`, `get_statements`, `get_rfc`, `check_compliance`
cron `* * * * *`	—	Sweeps `pending_checks` + `pending_scans`

Edge Functions

Function	Trigger	Auth
`clerk-webhook`	Clerk events (identity/billing sync)	Svix `CLERK_WEBHOOK_SIGNING_SECRET`
`clerk-to-resend`	Clerk events (email triggers — separate endpoint)	Svix `CLERK_TO_RESEND_SIGNING_SECRET`
`resend-webhook`	Resend delivery events	Svix `RESEND_WEBHOOK_SIGNING_SECRET`
`cal-webhook`	Cal.com `BOOKING_CREATED`	Cal.com HMAC `CAL_WEBHOOK_SECRET`
`extract-statements`	Invoked by web app on RFC approval	Clerk JWT
`import-spec`	Invoked by web app	Clerk JWT
`github-scan`	Repo-inventory scan	Clerk JWT
`growth-api`	Growth SPA reads	Clerk JWT + internal-org domain_owner
`demo-api`	Demo console actions	Clerk JWT + demo/internal-org domain_owner
`clerk-plans`	Marketing-site live pricing	public read

All functions set verify_jwt = false in config.toml and verify Clerk tokens (or webhook signatures) themselves — the platform gateway cannot validate Clerk JWTs.

Tables (schema `codex`)

orgs, members, user_profiles, domains, rfcs, rfc_versions, statements, audit_log, rfc_comments, role_groups, role_group_members, api_keys, github_installations, service_checks, pending_checks, pending_scans, repo_coverage, violations, llm_calls, org_llm_config, org_subscriptions, website_leads, email_subscribers, email_sends, email_events. Details: Database schema.

Invariants (never violated by any support action)

audit_log is append-only and hash-chained (entry_hash = sha256(prev_hash || canonical_json(entry))); orgs are retired, never deleted.
rfc_versions rows are immutable; body_md holds the full composed document including the YAML frontmatter block.
Statement slugs are stable forever; removed statements are retired, not deleted.
Every tenant table has org_id + RLS; identity in SQL is codex.current_user_id() (Clerk user_…), never auth.uid().
One GitHub App installation belongs to exactly one org (github_installations unique on both org_id and installation_id).
Migrations are additive; the six deployables each need their own deploy step.

Roles and gates

Gate	Rule
Web app data	RLS via Clerk JWT; role checks inside SECURITY DEFINER RPCs
Approve an RFC	reviewer sign-off first (hard gate), then approver group or domain owner
Enforce / deprecate / settings / keys / GitHub connect	domain_owner
growth-api	domain_owner of `GROWTH_INTERNAL_CLERK_ORG_ID` org
demo-api	domain_owner of `DEMO_CLERK_ORG_ID` org, or of `DEMO_ADMIN_CLERK_ORG_ID` org
Plan features	`codex.has_entitlement(org_id, feature)`; `/v1/check` is deliberately ungated

Resend account (email)

7 custom events (codex:*), 7 automations, 14 templates, 1 segment (“General”), 1 webhook (resend-webhook, full event set). Full as-built with automation diagrams and known gaps: Resend environment.

Environment variables (names only; values never in the repo)

Worker (8, exactly): SUPABASE_URL, SUPABASE_SECRET_KEY, OPENAI_BASE_URL, OPENAI_API_KEY, MODEL, GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET
Functions: CLERK_SECRET_KEY, CODEX_SECRET_KEY, webhook signing secrets (see the functions table), GROWTH_INTERNAL_CLERK_ORG_ID, DEMO_CLERK_ORG_ID, DEMO_ADMIN_CLERK_ORG_ID, RESEND_API_KEY, LLM fallback trio
SPA builds (VITE_*, per Pages project): VITE_CLERK_PUBLISHABLE_KEY, VITE_SUPABASE_URL, VITE_SUPABASE_PUBLISHABLE_KEY, VITE_APP_URL, VITE_SITE_ORIGIN, VITE_GROWTH_API_BASE, VITE_DEMO_API_BASE, VITE_DEMO_APP_URL, VITE_GITHUB_APP_URL, VITE_CAL_DEMO_URL

Start here

Architecture (C4)

Database

URLs

Identifiers

Worker endpoints

Edge Functions

Tables (schema `codex`)

Invariants (never violated by any support action)

Roles and gates

Resend account (email)

Environment variables (names only; values never in the repo)

​URLs

​Identifiers

​Worker endpoints

​Edge Functions

​Tables (schema codex)

​Invariants (never violated by any support action)

​Roles and gates

​Resend account (email)

​Environment variables (names only; values never in the repo)

URLs

Identifiers

Worker endpoints

Edge Functions

Tables (schema `codex`)

Invariants (never violated by any support action)

Roles and gates

Resend account (email)

Environment variables (names only; values never in the repo)