/Getting Started
v1.2Architecture
System design, data flow, security boundaries, and deployment topology.
Getting started
Architecture
How PreFlight is built, how data flows through the system, and where each component lives. This page helps you reason about security boundaries, deploy topology, and extension points.
PreFlight is a Next.js 16 application backed by Supabase (PostgreSQL with Row Level Security), encrypted credential vaults, and an external scheduler for continuous monitoring. Every read and write passes through workspace-scoped access checks.
System overview
| Layer | Technology | Responsibility |
|---|---|---|
| Frontend | Next.js 16 App Router, React 19, Tailwind CSS v4 | Dashboard, docs, Trust Center, public pages |
| API | Next.js Route Handlers (/api/v1/*) | REST surface for CI, bots, and agents |
| MCP Server | @modelcontextprotocol/sdk (stdio) | AI agent access to the same API |
| Database | Supabase PostgreSQL + Row Level Security | All project, check, sample, and incident state |
| Auth | Supabase Auth (email + magic link) | Session management and workspace membership |
| Scheduler | External cron (Vercel Cron / GitHub Actions) | Monitoring, Sentinel, Revenue Watch, Vercel Watch |
| AI engine | Cerebras inference API | Optional diagnosis and checklist generation |
| Encryption | AES-256-GCM with ENCRYPTION_KEY | Provider credential storage at rest |
| Resend / Postmark / SendGrid | Alert delivery and transactional messages | |
| Payments | Stripe (Checkout + webhooks) | Subscription billing and shadow verification |
Data flow
Check execution
User or CI triggers POST /api/v1/projects/:id/checks
→ Server resolves project + connected integrations
→ Provider probes execute in parallel (Stripe, Supabase, Clerk, etc.)
→ App URL probes scan DNS, TLS, SEO, secrets, legal pages
→ Consistency probes compare cross-provider state
→ Results stored as check_run + check_results rows
→ Optional AI diagnosis from Cerebras appended
→ Response returned with status, counts, and probe rows
Monitoring cron tick
External scheduler calls GET /api/cron/monitoring
→ Authenticated via CRON_SECRET bearer token
→ Active Monitoring sessions sampled
→ Due Sentinel projects sampled (batch limited)
→ Revenue Ledger Watch snapshots taken
→ Custom checks executed
→ Vercel Watch conditions evaluated
→ Alerts routed through configured channels
→ Activity events written to Flight Recorder
Deploy gate evaluation
CI calls GET /api/v1/projects/:id/deploy-gate?mode=strict
→ Server loads latest check run, Sentinel state, revenue snapshot
→ Policy rules evaluated (max age, pass rate, drift, etc.)
→ Returns allowed: true (200) or allowed: false (409) with blockers
Security boundaries
| Boundary | Enforcement |
|---|---|
| Workspace isolation | RLS policies + server-side workspace membership checks |
| API authentication | Bearer tokens (pf_live_*) validated per request |
| Credential encryption | AES-256-GCM; decryption only at probe execution time |
| Cron authentication | Separate CRON_SECRET token; not shared with API keys |
| Rate limiting | Per-key, per-project, and per-bucket limits on all routes |
| CSP headers | Strict Content-Security-Policy on all responses |
| Secret scanning | App URL probes detect leaked keys in public HTML/JS |
Defense in depth
Even if an API key leaks, it only accesses projects the creating user owns. Credentials stored in the vault require the server-side ENCRYPTION_KEY to decrypt — they are never returned in API responses.
Deployment topology
Hosted (getpreflight.dev)
- Compute: Vercel Edge + Serverless Functions
- Database: Supabase managed PostgreSQL
- Scheduler: Vercel Cron (10-minute cadence)
- CDN: Vercel Edge Network for static assets and docs
- Monitoring: Internal Sentinel + Sentry error tracking
Self-hosted
PreFlight can run on any Node.js 20+ environment:
- Deploy the Next.js app to your preferred host (Docker, AWS, GCP, bare metal).
- Provision Supabase — hosted or self-hosted with the required schema migrations.
- Configure environment variables for database, encryption, email, and payment providers.
- Set up a scheduler (cron job, GitHub Actions, CloudWatch Events) hitting
/api/cron/monitoringevery 10 minutes. - Point DNS and configure TLS for your custom domain.
Extension points
| Extension | How |
|---|---|
| Custom integrations | Add a provider probe module under the check engine |
| Custom checks | HTTP assertions on arbitrary URLs, scheduled via the cron |
| MCP tools | Extend src/sdk/mcp/server.ts with new tool handlers |
| Alert channels | Add delivery adapters (PagerDuty, OpsGenie, Teams, webhooks) |
| Export formats | Add renderers to the export pipeline |
| Trust Center themes | Customize the public /trust/:slug template |
Database schema highlights
| Table | Purpose |
|---|---|
workspaces | Billing, seats, and membership container |
projects | Per-app configuration, URLs, and environment labels |
integrations | Encrypted credential bundles per provider |
check_runs | Aggregate run metadata (status, counts, timestamps) |
check_results | Individual probe rows with messages and fix suggestions |
health_checks | Sentinel and Monitoring samples with response times |
project_sentinel_settings | Per-project cadence, threshold, and pause state |
runbook_states | Incident lifecycle (open → acknowledged → resolved) |
activity_events | Flight Recorder audit trail |
alert_deliveries | Delivery attempts and outcomes per channel |
revenue_snapshots | Revenue Watch reconciliation results |
deploy_gate_policies | Per-project gate requirements |
All tables enforce RLS policies scoped to workspace membership. Service-role access is used only by the cron and server-side API routes.
Performance considerations
- Probe parallelism: Provider and App URL probes execute concurrently within a check run.
- Batch limits: Sentinel cron processes up to N projects per tick to avoid timeout.
- Rate limiting: External API calls (Stripe, Supabase, Clerk) respect provider rate limits.
- Caching: Trust Center pages and status responses are cached at the edge with short TTLs.
- Cold starts: Serverless functions warm on first request; Vercel Edge routes have sub-50ms cold starts.