supercheck-io/supercheck / .agents/skills/architecture
supercheck-architecture
VerifiedWork 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
| Path | Responsibility |
|---|---|
app/src/app | Next.js 16 App Router pages and route handlers |
app/src/actions | Server-side UI mutations |
app/src/components | Feature and shared React components |
app/src/hooks | React Query data access and cache contracts |
app/src/db/schema | Drizzle schema definitions |
app/src/db/migrations | PostgreSQL migration history |
app/src/lib | Auth, RBAC, queues, schedulers, validation, security, billing, and SRE services |
app/src/sre | AI SRE agents, tools, skills, evaluation, and orchestration |
worker/src | NestJS execution, monitor, notification, and private-agent workers |
worker/src/monitor-control | Separate NestJS entrypoint (main.ts) for durable monitor check cycles |
worker/src/queue-alerting | Queue health alerting |
cli | @supercheck/cli monitoring-as-code client |
recorder | Apache-licensed Playwright CRX recorder and browser extension |
docs | Public Fumadocs site |
deploy/docker | Public Docker Compose and self-hosted assets |
Start here
| File | Why |
|---|---|
app/src/db/schema/index.ts, app/src/db/schema/types.ts | Schema barrel and shared JSON column types |
app/src/db/migrations/, app/drizzle.config.ts | Migration history and generator config |
app/src/lib/queue.ts | Queue 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.ts | Worker 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 (
requireAuthContextandhasPermissionForUser); cookie-only helpers such ashasPermissionbreak 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 (
isUuidinapp/src/lib/uuid.ts; regression suiteapp/src/app/api/malformed-identifiers.spec.ts). - Deleting jobs and monitors: a target with
deleting_atset must read as missing (404, not counted, not acted on). Build every read, list, count, aggregate, by-id load and write againstmonitors,jobsorrunsfrom the helpers inapp/src/lib/deletion/visibility.ts(liveMonitor,liveJob,liveRunOfLiveJob,notFoundIfDeleting; worker twin inworker/src/db/deletion-visibility.ts), never a hand-writtendeleting_atfilter. Only purge/admin/cleanup code that must see deleting rows is exempt: add it to the allowlist inapp/src/lib/deletion/visibility.spec.tswith 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 deliberateON DELETErule (0048); status/type columns get CHECK constraints (0052). A file starting with-- supercheck:no-transactionruns after the migration transaction commits (use it forCREATE INDEX CONCURRENTLY, e.g. 0054); behind a connection pooler it skips the sessionstatement_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/(includingtypes.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_KEYconstants 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
refetchOnMountor 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |