Skip to main content
Status: Accepted Date: 2026-02-06 Deciders: Reflections Maintainers

​
Context

This repository combines application logic, database migrations, and deployment automation. Regressions can arise from type drift, formatting/lint drift, schema drift, or startup/deployment misconfiguration.

​
Decision

Use layered CI/CD gates:
  • PR quality gate: format check, lint, architecture guard, design guard, typecheck, tests, build.
  • Release migration gate: merge-to-main triggers reusable Supabase migration workflow before the release gate can pass.
  • Database gate: migration SQL lint (enforced at commit time via lint-staged), local reset + lint + migration contracts.
  • Deployment health gate: Railway startup smoke checks and deployed synthetic checks; Railway must wait for the release gate.
  • Migration workflow gate: explicit Supabase dry-run before applying linked migrations, with guarded manual break-glass dispatch.
  • Security gate: CodeQL static analysis and AI security review on non-draft PRs.
  • Dependency audit: pnpm audit --audit-level=high in CI.

​
Alternatives considered

​
Alternative 1: Minimal CI (lint + test only)

Pros:
  • Faster CI runtime.
Cons:
  • Misses schema/migration drift and build-time issues.
  • Increased risk of broken deployments.

​
Alternative 2: Manual release checklist only

Pros:
  • Flexible human control.
Cons:
  • Inconsistent and error-prone.
  • Poor scalability as repository grows.

​
Alternative 3: Single monolithic CI gate without DB/deployment checks

Pros:
  • Simpler pipeline definition.
Cons:
  • Fails to catch environment-specific migration/deployment regressions.

​
Consequences

Benefits:
  • Higher confidence in merged/deployed changes.
  • Early detection of migration drift and runtime startup failures.
  • Repeatable release discipline.
Costs:
  • Longer CI time.
  • Ongoing maintenance of workflow scripts and synthetic checks.

​
Implementation notes

  • PR validation executes format check, lint, architecture guard, design guard, typecheck, tests, and build in sequence.
  • The release workflow includes a policy check that blocks releases for commits not associated with a merged pull request.
  • The migration deployment workflow supports both automated and guarded manual dispatch with a production confirmation gate.
  • Architecture guard validates boundary and complexity constraints. Design guard enforces visual invariants (hex colors, inline style semantics, meta-label consistency, transition timing, WebGL budget). Both run as fast-fail structural gates (~1.3s combined).