CertScore
CertScore (certscore.ai) is a production-minded MVP for scanning public websites for potential accessibility, privacy, cookie, policy, and disclosure risk signals. It is a risk signal and monitoring product, not a legal certification platform.
Monorepo structure
website-signal-risk-scanner/
├─ apps/
│ ├─ web/
│ └─ validation-worker/
├─ packages/
│ ├─ shared/
│ ├─ web-bot-auth/
│ ├─ db/
│ └─ ui/
├─ docs/
├─ .env.example
├─ turbo.json
├─ package.json
└─ pnpm-workspace.yaml
Workspace packages
apps/web: product-facing web app and control-plane workflowsapps/validation-worker: active validation runtime owned byWC01packages/shared: shared constants, types, validators, scoring config, and scheduling helperspackages/web-bot-auth: server-only Web Bot Auth signing and key-directory helperspackages/db: PostgreSQL query helpers, migrations, seed SQL, and env helperspackages/ui: reusable UI primitives
Repo boundary
WC01 is now the product/control-plane repo.
- product web flows, scan creation, reporting, and validation stay here
- the standalone scanner runtime now lives in
WS01 - scanner operational changes, crawler identity work, and scanner deploy flow should originate in
WS01
What the MVP includes
- public homepage with preview scan funnel
- Better Auth with Google OAuth and email/password login flows
- organization bootstrap and protected workspace routes
- domain management, plan limits, and client grouping
- DB-backed scan creation with scanner-service claiming
- crawl/discovery, accessibility, privacy, and legal heuristics
- deterministic scoring, canonical report payloads, and authenticated report UI
- scanner-generated PDF generation and upload
- regression summaries and scheduled rescans
- lightweight branding for reports and PDFs
Environment variables
This monorepo should use apps/web/.env.local as the single local development runtime env:
Use .env.example only as a reference template for shared keys. Do not rely on a root .env.local for app runtime configuration.
Recommended environment split inside WC01:
- local web + local validation runtime: dedicated dev PostgreSQL database plus S3-compatible storage
- production web + production validation runtime: dedicated production PostgreSQL database plus S3-compatible storage
Do not point localhost at the production database or production auth credentials unless you are intentionally testing production behavior.
Required for the web app:
NEXT_PUBLIC_APP_URLDATABASE_URLBETTER_AUTH_SECRETGOOGLE_CLIENT_IDGOOGLE_CLIENT_SECRETS3_BUCKETS3_REGIONS3_ACCESS_KEY_IDS3_SECRET_ACCESS_KEY
Required for the validation runtime in WC01:
DATABASE_URLOPENAI_API_KEY
Optional but recommended:
WORKER_CONCURRENCYPLAYWRIGHT_BROWSERS_PATHVALIDATION_OPENAI_MODELVALIDATION_NANO_MODELWEB_BOT_AUTH_ENABLEDWEB_BOT_AUTH_PRIVATE_KEY_PEMWEB_BOT_AUTH_SIGNATURE_AGENT_URL
Local development setup
Use Node 20 or Node 22 LTS for local development. Node 25 is not supported here and can fail DNS resolution for app routes and external service calls on localhost.
- Install dependencies:
pnpm install
- Copy the environment template:
cp apps/web/.env.example apps/web/.env.local
- Start a dedicated PostgreSQL instance for local development.
- Apply the SQL migrations from packages/db/migrations.
- Seed local development data when needed with packages/db/seed/0001_dev_seed.sql.
- Configure Better Auth provider settings:
- Google OAuth if enabled
- email/password and verification settings as needed
- Configure auth redirect URLs:
- Google OAuth must allow Better Auth's provider callback route:
http://localhost:3000/api/auth/callback/googlehttp://127.0.0.1:3000/api/auth/callback/googlehttps://certscore.ai/api/auth/callback/google/auth/callbackis only an app alias route; it is not the redirect URI Better Auth initiates with Google
- Keep local and production auth isolated:
- local
NEXT_PUBLIC_APP_URLshould behttp://localhost:3000 - local database and auth secrets should come from the dev environment
- production secrets should exist only in the active AWS/web or worker deployment settings
- local
- Create the S3-compatible bucket referenced by
S3_BUCKET. - Install Playwright Chromium for the validation runtime:
pnpm --filter @website-signal-risk-scanner/validation-worker exec playwright install chromium
- Start validation local development with a watched validation worker:
pnpm dev:validation
- Start the main local app by itself when needed:
pnpm --filter @website-signal-risk-scanner/web dev
- Use
WS01when you need the standalone scanner locally. - Start the standalone scanner locally against the same dev database and storage env as
localhost:3000:
pnpm dev:scanner:local
- Use the combined local runner only when you want web + validation together in
WC01:
pnpm dev:all
- Run a validation scheduler sweep manually when needed:
pnpm dev:validation:scheduler
Development verification
Use these commands before shipping changes:
pnpm turbo run typecheckpnpm turbo run build
Validation-specific checks:
pnpm --filter @website-signal-risk-scanner/validation-worker typecheckpnpm test:scan-pipeline
The scan pipeline test is deterministic and runs locally from apps/validation-worker/src/validation/pipeline.test.ts.
The normalized concern lifecycle in WC01 is documented in docs/normalized-concern-pipeline.md.
CI validation
GitHub Actions workflow: .github/workflows/accessibility-validation.yml
worker-scan-pipeline-testsruns on pushes tomain, pull requests, and manual dispatch. It installs Chromium, typechecksvalidation-worker, and runspnpm test:scan-pipeline.live-validation-smokeruns after the deterministic job and executespnpm --filter @website-signal-risk-scanner/validation-worker smoke:validationonly when the runtime secrets are configured.- If those secrets are missing, the live smoke job is skipped and only the deterministic scan pipeline job runs.
Runtime validation tooling
Use these lightweight checks before first deployment validation:
pnpm dev:storage:localpnpm --filter @website-signal-risk-scanner/web check-envpnpm check-env:validationpnpm --filter @website-signal-risk-scanner/validation-worker check-envpnpm --filter @website-signal-risk-scanner/validation-worker check-runtime
For local validation runs, pnpm dev:storage:local starts MinIO against the apps/web/.env.local S3 settings and creates the configured bucket when needed.
Run it alongside pnpm dev:scanner:local and pnpm dev:validation:worker.
Use this runtime smoke helper:
pnpm --filter @website-signal-risk-scanner/validation-worker scheduler
The full runtime QA sequence is documented in docs/runtime-validation.md. The validation pipeline design and deployment shape are documented in docs/validation-pipeline-plan.md. The validation crawler deployment and VM runbook is documented in docs/validation-ops-runbook.md. Cloudflare Verified Bot setup is documented in docs/cloudflare-web-bot-auth.md.
Web Bot Auth
ConsentCheck can expose a signed HTTP Message Signatures key directory and sign outbound HTTP crawler requests for Cloudflare Verified Bot workflows.
Required configuration:
WEB_BOT_AUTH_ENABLEDWEB_BOT_AUTH_PRIVATE_KEY_PEMWEB_BOT_AUTH_SIGNATURE_AGENT_URLWEB_BOT_AUTH_EXPIRES_SECONDSWEB_BOT_AUTH_INCLUDE_NONCE
Common commands:
pnpm web-bot-auth:generatepnpm web-bot-auth:printpnpm web-bot-auth:test-requestpnpm test:web-bot-auth
Production deployment
Web runtime
- the live public web deployment target is the AWS ECS/Fargate path for
certscore.ai consentcheck.siteis owned outside WC01 and must not be deployed by this repomaindeploys through /.github/workflows/web-aws-ecs-deploy.yml- run
pnpm ops:check:deploybefore or after topology changes to catch stale local assumptions - run
pnpm ops:check:liveagainst the public hosts to verify runtime target and revision alignment after deploy - treat docs/aws-web-ecs-cutover-plan.md as the active web deployment runbook
- treat docs/deploy-amplify.md as future-state reference material only
Validation And Scanner Runtime
- do not use
WC01for the primary scanner deploy path - use
WS01for scanner runtime deployment - keep
WC01deployment guidance scoped to web and validation only - keep web production, validation worker, and scanner runtime as three distinct deployment paths
- use the AWS validation deployment lane for
WC01validation runtime changes
Database, Auth, and Storage
- create production PostgreSQL, Better Auth, and S3-compatible storage resources separate from local development
- apply all migrations in order
- configure the production site URL and production redirect URLs only
- create the report storage bucket referenced by
S3_BUCKET
Scheduler
Recommended production trigger:
- run the validation scheduler sweep every hour if the validation runtime is enabled
Command:
pnpm dev:validation:scheduler
The primary scanner scheduler now lives in WS01.
Deployment readiness checklist
- Environment variables configured
- PostgreSQL database created
- database migrations applied
- Better Auth providers configured
- S3-compatible storage bucket created
- Playwright browsers installed
- Worker process running
- Scheduler cron configured
- First domain scanned successfully
- Report generated successfully
- PDF export generated successfully
First production validation
After deployment, validate in this order:
- run the env and runtime checks above
- verify login and organization bootstrap
- verify preview scan flow
- verify full scan completion
- verify findings, scores, and report persistence
- verify PDF export
- verify regression on a second scan
- verify the hourly scheduler sweep path
Operational notes
- The standalone scanner in
WS01owns crawl, auditing, scoring, reporting, PDF generation, and scheduled sweep logic. - PDF generation failures do not invalidate the scan or web report.
- Regression calculation failures do not invalidate the scan or report.
- The app validates critical env vars at runtime and now fails fast with clearer messages when required configuration is missing.