Skip to content

supercheck-io/supercheck / .agents/skills/architecture

supercheck-architecture

Verified

Work on Supercheck system architecture, Next.js routes and actions, React data hooks and query keys, Drizzle schemas, tables, columns, indexes and migrations, app-worker boundaries, or cross-package contracts.

Supercheck architecture

Supercheck is a multi-tenant testing, monitoring, and reliability platform. The repository contains a Next.js application, NestJS execution worker, CLI, browser recorder, documentation, and self-hosted deployment assets.

flowchart LR
  UI[Next.js UI] --> API[Routes and server actions]
  CLI[CLI] --> API
  REC[Recorder extension] --> API
  API --> AUTH[Better Auth and RBAC]
  AUTH --> DB[(PostgreSQL and Drizzle)]
  API --> Q[(Redis and BullMQ)]
  Q --> WORKER[NestJS worker]
  WORKER --> JOB[gVisor execution Job]
  WORKER --> OBJ[(S3 or RustFS)]

Repository map

PathResponsibility
app/src/appNext.js 16 App Router pages and route handlers
app/src/actionsServer-side UI mutations
app/src/componentsFeature and shared React components
app/src/hooksReact Query data access and cache contracts
app/src/db/schemaDrizzle schema definitions
app/src/db/migrationsPostgreSQL migration history
app/src/libAuth, RBAC, queues, schedulers, validation, security, billing, and SRE services
app/src/sreAI SRE agents, tools, skills, evaluation, and orchestration
worker/srcNestJS execution, monitor, notification, and private-agent workers
worker/src/monitor-controlSeparate NestJS entrypoint (main.ts) for durable monitor check cycles
worker/src/queue-alertingQueue health alerting
cli@supercheck/cli monitoring-as-code client
recorderApache-licensed Playwright CRX recorder and browser extension
docsPublic Fumadocs site
deploy/dockerPublic Docker Compose and self-hosted assets

Start here

FileWhy
app/src/db/schema/index.ts, app/src/db/schema/types.tsSchema barrel and shared JSON column types
app/src/db/migrations/, app/drizzle.config.tsMigration history and generator config
app/src/lib/queue.tsQueue names, payload types, and Redis connections for every BullMQ queue
app/src/lib/auth-context.ts, app/src/lib/rbac/Identity, tenant context, and permission checks (see supercheck-security-auth)
worker/src/app.module.tsWorker module wiring

Request and data boundaries

flowchart TD
  PAGE[Page or client component] --> HOOK[React Query hook]
  HOOK --> ROUTE[Route handler]
  PAGE --> ACTION[Server action]
  ROUTE --> CTX[Authentication and tenant context]
  ACTION --> CTX
  CTX --> RBAC[Resource/action authorization]
  RBAC --> VALIDATE[Zod validation]
  VALIDATE --> SERVICE[Business logic]
  SERVICE --> DB[(Drizzle)]
  SERVICE --> QUEUE[BullMQ]
  • Prefer Server Components until browser state, effects, or event handlers require "use client".
  • Keep business rules below transport and UI layers. Routes/actions translate auth, input, status codes, and public errors.
  • Use bearer-compatible auth helpers for routes called by CLI/API keys (requireAuthContext and hasPermissionForUser); cookie-only helpers such as hasPermission break those callers.
  • Validate request bodies, params, search params, uploads, provider events, and browser messages at their trust boundary.
  • Reject malformed UUID route params before any database access (isUuid in app/src/lib/uuid.ts; regression suite app/src/app/api/malformed-identifiers.spec.ts).
  • Deleting jobs and monitors: a target with deleting_at set must read as missing (404, not counted, not acted on). Build every read, list, count, aggregate, by-id load and write against monitors, jobs or runs from the helpers in app/src/lib/deletion/visibility.ts (liveMonitor, liveJob, liveRunOfLiveJob, notFoundIfDeleting; worker twin in worker/src/db/deletion-visibility.ts), never a hand-written deleting_at filter. Only purge/admin/cleanup code that must see deleting rows is exempt: add it to the allowlist in app/src/lib/deletion/visibility.spec.ts with a reason, which also fails the build when a new query skips the helper.
  • Use the owning schema to determine scope. Organization-owned resources need organization scoping; project-owned resources need verified organization and project ownership. Do not mechanically add both IDs to tables that do not own both.

Database and migration rules

  • PostgreSQL 18+ and Drizzle ORM are current (the schema relies on the PostgreSQL 18-native uuidv7()). Do not introduce Prisma, MySQL assumptions, or NextAuth patterns.
  • Follow neighboring schema conventions for UUIDs, timestamps, indexes, foreign keys, uniqueness, and delete behavior.
  • Migration conventions: every timestamp is timestamptz (since 0053); every foreign key has a deliberate ON DELETE rule (0048); status/type columns get CHECK constraints (0052). A file starting with -- supercheck:no-transaction runs after the migration transaction commits (use it for CREATE INDEX CONCURRENTLY, e.g. 0054); behind a connection pooler it skips the session statement_timeout, which would otherwise leak to other clients.
  • Add indexes for real filters, joins, ordering, and uniqueness—not as a template exercise.
  • Generate and inspect migrations. New non-null columns need safe behavior for existing rows.
  • Analyze destructive changes, backfills, transaction duration, locks, rollback/recovery, and rolling app/worker compatibility.
  • Keep app and worker schema representations compatible where both packages read the same tables. worker/src/db/schema/ (including types.ts) is a separate, smaller copy: when you change a table, column, or JSON type the worker reads, update the worker copy too; app-only tables stay app-only.

React Query and client data

  • Query keys are contracts. Prefetch (app/src/lib/prefetch-utils.ts), hooks (app/src/hooks/), invalidation, and parameter object shapes must match exactly. Hooks export *_QUERY_KEY constants and append scope ([...KEY, projectId]); cached data must also be isolated per project and account.
  • Render cached query data directly. Do not mirror it into component state using an effect unless editing semantics require a deliberate snapshot.
  • Preserve current freshness/refetch behavior when changing hooks; do not remove refetchOnMount or cache settings without tracing UX impact.
  • Bound and paginate growing collections. Avoid N+1 requests and per-row database lookups.
  • Mutations must invalidate or update every affected cache key and preserve loading, empty, error, and accessibility states.

Cross-package compatibility

  • App and worker deploy independently. Queue names, payloads, status values, retries, and result schemas must tolerate version skew.
  • CLI and recorder are public clients. Preserve documented API and output compatibility or provide an explicit migration/version strategy.
  • Cloud and self-hosted behavior must remain explicit. UI visibility does not substitute for server-side feature, entitlement, or security enforcement.

Verification

  • Trace every changed contract through callers, persistence/queue, consumers, tests, and docs.
  • Run checks from each affected package directory.
  • Schema changes require migration/schema-contract tests; shared contracts require producer and consumer coverage.
  • Distinguish code verification from browser, provider, deployment, billing, and production acceptance.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall