Governance Patterns Gallery

Real examples of what governance catches — with before/after code showing the exact fix. These patterns are drawn from the most common issues found across projects.

Direct SDK Import in Route Handler

highAPI

Importing database SDKs directly in route handlers creates tight coupling and makes testing difficult.

Before

typescript

import { createClient } from '@supabase/supabase-js';

// dead-export-exempt: test-only-consumer
export async function GET() {
  const supabase = createClient(url, key);
  const { data } = await supabase.from('users').select('*');
  return Response.json(data);
}

After

typescript

import { getUsers } from '@/lib/supabase/users';

export async function GET() {
  const data = await getUsers();
  return Response.json(data);
}

Why this matters: The adapter pattern isolates vendor dependencies. If you switch databases, only the adapter changes — not every route handler.

Missing Error Destructuring

criticalAPI

Supabase queries can fail silently if you don't check the error field. This leads to null data passed to clients.

Before

typescript

const { data } = await supabase
  .from('scans')
  .select('*')
  .eq('org_id', orgId);

return Response.json(data);
// If the query fails, data is null — client gets null with 200 OK

After

typescript

const { data, error } = await supabase
  .from('scans')
  .select('*')
  .eq('org_id', orgId);

if (error) {
  return Response.json(
    { error: { code: 'DB_ERROR', message: error.message } },
    { status: 500 },
  );
}

return Response.json(data);

Why this matters: Always destructure both data and error. This prevents silent failures where clients receive null data with a 200 status code.

Hardcoded Secrets in Source

criticalSecurity

API keys and secrets committed to source code are exposed in version history forever, even after deletion.

Before

typescript

const stripe = new Stripe('sk_live_abc123xyz...');

const openai = new OpenAI({
  apiKey: 'sk-proj-abc123...',
});

After

typescript

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
});

Why this matters: Secrets belong in environment variables, never in source code. Keep .env files out of version control and rotate any key that was ever committed.

Missing Auth Middleware on API Route

criticalSecurity

API routes without authentication middleware are publicly accessible. This is the most common security vulnerability in web applications.

Before

typescript

export async function POST(req: Request) {
  const body = await req.json();
  // No auth check — anyone can call this endpoint
  await createScan(body);
  return Response.json({ ok: true });
}

After

typescript

import { withAuth } from '@/lib/middleware/auth';

// dead-export-exempt: test-only-consumer
export const POST = withAuth(async (req, { user, org }) => {
  const body = await req.json();
  await createScan({ ...body, orgId: org.id, userId: user.id });
  return Response.json({ ok: true });
});

Why this matters: Every mutating endpoint needs authentication. A canonical auth middleware ensures consistent user/org context and prevents bypass.

Missing Accessible Label on Interactive Element

highAccessibility

Icon-only buttons without accessible labels are invisible to screen reader users — they hear "button" with no context.

Before

tsx

<button onClick={handleDelete}>
  <Trash className="h-4 w-4" />
</button>

After

tsx

<button onClick={handleDelete} aria-label="Delete item">
  <Trash className="h-4 w-4" aria-hidden="true" />
</button>

Why this matters: Every interactive element needs an accessible name. Use aria-label for icon-only buttons and aria-hidden on decorative icons.

Unbounded Database Query

highPerformance

Queries without LIMIT can return thousands of rows, causing memory spikes and slow responses.

Before

typescript

const { data } = await supabase
  .from('violations')
  .select('*')
  .eq('scan_id', scanId);
// Could return 10,000+ rows

After

typescript

const { data } = await supabase
  .from('violations')
  .select('*')
  .eq('scan_id', scanId)
  .range(0, 99);
// Always bounded — paginate for more

Why this matters: Every array-returning query must include .limit() or .range(). Use pagination for unbounded result sets.

Console.log in Production Code

mediumCode Quality

console.log calls bypass structured logging, making production debugging nearly impossible in multi-service environments.

Before

typescript

console.log('Processing scan', scanId);
console.error('Scan failed:', error);

After

typescript

import { logger } from '@/lib/logger';

const log = logger.child({ scanId });
log.info('Processing scan');
log.error({ err: error }, 'Scan failed');

Why this matters: Structured logging (Pino) ensures every log entry has trace IDs, timestamps, and structured metadata. This enables production debugging across distributed services.

Showing 7 of 7 patterns. Browse the full governance catalog

Governance Patterns Gallery

Real examples of what governance catches — with before/after code showing the exact fix. These patterns are drawn from the most common issues found across projects.

Direct SDK Import in Route Handler

highAPI

Importing database SDKs directly in route handlers creates tight coupling and makes testing difficult.

Before

typescript

import { createClient } from '@supabase/supabase-js';

// dead-export-exempt: test-only-consumer
export async function GET() {
  const supabase = createClient(url, key);
  const { data } = await supabase.from('users').select('*');
  return Response.json(data);
}

After

typescript

import { getUsers } from '@/lib/supabase/users';

export async function GET() {
  const data = await getUsers();
  return Response.json(data);
}

Why this matters: The adapter pattern isolates vendor dependencies. If you switch databases, only the adapter changes — not every route handler.

Missing Error Destructuring

criticalAPI

Supabase queries can fail silently if you don't check the error field. This leads to null data passed to clients.

Before

typescript

const { data } = await supabase
  .from('scans')
  .select('*')
  .eq('org_id', orgId);

return Response.json(data);
// If the query fails, data is null — client gets null with 200 OK

After

typescript

const { data, error } = await supabase
  .from('scans')
  .select('*')
  .eq('org_id', orgId);

if (error) {
  return Response.json(
    { error: { code: 'DB_ERROR', message: error.message } },
    { status: 500 },
  );
}

return Response.json(data);

Why this matters: Always destructure both data and error. This prevents silent failures where clients receive null data with a 200 status code.

Hardcoded Secrets in Source

criticalSecurity

API keys and secrets committed to source code are exposed in version history forever, even after deletion.

Before

typescript

const stripe = new Stripe('sk_live_abc123xyz...');

const openai = new OpenAI({
  apiKey: 'sk-proj-abc123...',
});

After

typescript

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
});

Why this matters: Secrets belong in environment variables, never in source code. Keep .env files out of version control and rotate any key that was ever committed.

Missing Auth Middleware on API Route

criticalSecurity

API routes without authentication middleware are publicly accessible. This is the most common security vulnerability in web applications.

Before

typescript

export async function POST(req: Request) {
  const body = await req.json();
  // No auth check — anyone can call this endpoint
  await createScan(body);
  return Response.json({ ok: true });
}

After

typescript

import { withAuth } from '@/lib/middleware/auth';

// dead-export-exempt: test-only-consumer
export const POST = withAuth(async (req, { user, org }) => {
  const body = await req.json();
  await createScan({ ...body, orgId: org.id, userId: user.id });
  return Response.json({ ok: true });
});

Why this matters: Every mutating endpoint needs authentication. A canonical auth middleware ensures consistent user/org context and prevents bypass.

Missing Accessible Label on Interactive Element

highAccessibility

Icon-only buttons without accessible labels are invisible to screen reader users — they hear "button" with no context.

Before

tsx

<button onClick={handleDelete}>
  <Trash className="h-4 w-4" />
</button>

After

tsx

<button onClick={handleDelete} aria-label="Delete item">
  <Trash className="h-4 w-4" aria-hidden="true" />
</button>

Why this matters: Every interactive element needs an accessible name. Use aria-label for icon-only buttons and aria-hidden on decorative icons.

Unbounded Database Query

highPerformance

Queries without LIMIT can return thousands of rows, causing memory spikes and slow responses.

Before

typescript

const { data } = await supabase
  .from('violations')
  .select('*')
  .eq('scan_id', scanId);
// Could return 10,000+ rows

After

typescript

const { data } = await supabase
  .from('violations')
  .select('*')
  .eq('scan_id', scanId)
  .range(0, 99);
// Always bounded — paginate for more

Why this matters: Every array-returning query must include .limit() or .range(). Use pagination for unbounded result sets.

Console.log in Production Code

mediumCode Quality

console.log calls bypass structured logging, making production debugging nearly impossible in multi-service environments.

Before

typescript

console.log('Processing scan', scanId);
console.error('Scan failed:', error);

After

typescript

import { logger } from '@/lib/logger';

const log = logger.child({ scanId });
log.info('Processing scan');
log.error({ err: error }, 'Scan failed');

Why this matters: Structured logging (Pino) ensures every log entry has trace IDs, timestamps, and structured metadata. This enables production debugging across distributed services.

Showing 7 of 7 patterns. Browse the full governance catalog