CivicLoop by Ta-Tech Solutions All documents

Operations Runbook

How to run, deploy, monitor, and recover CivicLoop County OS. Companion to COUNTY_OS.md.

Environments

Production app: https://civicloop-pgc.netlify.app (Netlify site e1d84f28-2e39-4f34-98ab-5749dd77e286).
Docs site: https://civicloop-docs.netlify.app (Netlify site 465824a0-d562-40aa-84b7-178dcf79b3d7).
Database: Supabase project fxhcphtwnicrypsznsxa (us-east-1). RLS on every table. Service-role key + Anthropic key in web/.env.local.
Repo: github.com/tangwafor/civicloop, working dir ~/Desktop/projects/civicloop (web/ docs/ site/ scripts/ at root).

Manual CLI (the app site does NOT auto-deploy from GitHub and a build hook does not trigger a build):

cd web && netlify deploy --build --prod --site=e1d84f28-2e39-4f34-98ab-5749dd77e286

Always pass --site=<id> so a missing .netlify/state.json cannot deploy to the wrong site.
Always run npm run build (or let --build do it) and confirm exit 0 before trusting a deploy.
Docs: cd .. && npm run docs && node scripts/build-docs.mjs --pdf && netlify deploy --prod --dir=site --site=465824a0-d562-40aa-84b7-178dcf79b3d7.

npm run build locally, exit 0.
node scripts/ui-sweep.mjs against the deploy (or local) - zero uncaught JS errors.
Click through the changed surface in dev.
Deploy. Re-run node scripts/prod-smoke.mjs against prod. No em-dashes anywhere (the docs builder fails the build on one).

Var	Purpose	If unset
`ANTHROPIC_API_KEY`	AI co-pilot, bid scoring, County assistant	AI features fail safe (no crash)
`AUTOMATION_SECRET`	gate `/api/automations` + `/api/cron/synthetic`	endpoints return 503
`FEEDS_INGEST_SECRET`	gate `/api/feeds/ingest`	endpoint returns 503
`SENTRY_DSN` / `NEXT_PUBLIC_SENTRY_DSN`	error tracking	Sentry is a no-op
`SYNTHETIC_BASE_URL`	synthetic monitor target	defaults to prod URL
Twilio / Resend keys	SMS + email notifications	notifications log as "provider not configured"

Point any scheduler (Supabase pg_cron + pg_net, a Netlify scheduled function, GitHub Action) at:

POST /api/automations with header x-automation-secret: $AUTOMATION_SECRET - hourly. Runs reminders, janitor, and feed forecasts.
POST /api/cron/synthetic with the same header - every 5-10 min. Uptime/latency checks.
POST /api/cron/self-heal - existing data-integrity sweep.

Platform health panel on /dashboard shows the latest synthetic check per public surface.
Sentry (once DSN set) captures server + client + edge errors; global-error.tsx catches React render crashes.
Automations panel on /dashboard shows open flags (overdue permits, expiring contracts, down monitors, forecast breaches) for an officer to resolve.
Manual: node scripts/prod-smoke.mjs (20 checks across app + docs + Open311).

Check the dashboard health panel + Sentry issues.
Reproduce with node scripts/ui-sweep.mjs DEMO_APP_URL=https://civicloop-pgc.netlify.app.
If a deploy regressed: roll back to the previous deploy in the Netlify UI (Deploys -> Publish deploy), then fix forward.
DB issues: inspect via the Supabase dashboard / MCP get_logs + get_advisors. RLS is on; never disable it to "fix" a read - grant the right policy.

Supabase provides automated daily backups (point-in-time on the project plan).
No PII is exposed on any /public page (public-record aggregates only).
Schema source of truth: web/sql/civicpulse-schema.sql. Pull a fresh dump before writing new SQL.

CivicLoop - Ta-Tech Solutions - Architecture & Design Documentation