Senior Backend Engineer

Backend development patterns, API design, database optimization, and security practices.

Quick Start

# Generate API routes from OpenAPI spec

python scripts/api_scaffolder.py openapi.yaml --framework express --output src/routes/

# Analyze database schema and generate migrations

python scripts/database_migration_tool.py --connection postgres://localhost/mydb --analyze

# Load test an API endpoint

python scripts/api_load_tester.py https://api.example.com/users --concurrency 50 --duration 30

Tools Overview

1. API Scaffolder

Generates API route handlers, middleware, and OpenAPI specifications from schema definitions.

Input: OpenAPI spec (YAML/JSON) or database schema

Output: Route handlers, validation middleware, TypeScript types

Usage:

# Generate Express routes from OpenAPI spec

python scripts/api_scaffolder.py openapi.yaml --framework express --output src/routes/

# Output: Generated 12 route handlers, validation middleware, and TypeScript types

# Generate from database schema

python scripts/api_scaffolder.py --from-db postgres://localhost/mydb --output src/routes/

# Generate OpenAPI spec from existing routes

python scripts/api_scaffolder.py src/routes/ --generate-spec --output openapi.yaml

Supported Frameworks:

• Express.js (--framework express)

• Fastify (--framework fastify)

• Koa (--framework koa)

2. Database Migration Tool

Analyzes database schemas, detects changes, and generates migration files with rollback support.

Input: Database connection string or schema files

Output: Migration files, schema diff report, optimization suggestions

Usage:

# Analyze current schema and suggest optimizations

python scripts/database_migration_tool.py --connection postgres://localhost/mydb --analyze

# Output: Missing indexes, N+1 query risks, and suggested migration files

# Generate migration from schema diff

python scripts/database_migration_tool.py --connection postgres://localhost/mydb \

  --compare schema/v2.sql --output migrations/

# Dry-run a migration

python scripts/database_migration_tool.py --connection postgres://localhost/mydb \

  --migrate migrations/20240115_add_user_indexes.sql --dry-run

3. API Load Tester

Performs HTTP load testing with configurable concurrency, measuring latency percentiles and throughput.

Input: API endpoint URL and test configuration

Output: Performance report with latency distribution, error rates, throughput metrics

Usage:

# Basic load test

python scripts/api_load_tester.py https://api.example.com/users --concurrency 50 --duration 30

# Output: Throughput (req/sec), latency percentiles (P50/P95/P99), error counts, and scaling recommendations

# Test with custom headers and body

python scripts/api_load_tester.py https://api.example.com/orders \

  --method POST \

  --header "Authorization: Bearer token123" \

  --body '{"product_id": 1, "quantity": 2}' \

  --concurrency 100 \

  --duration 60

# Compare two endpoints

python scripts/api_load_tester.py https://api.example.com/v1/users https://api.example.com/v2/users \

  --compare --concurrency 50 --duration 30

Backend Development Workflows

API Design Workflow

Use when designing a new API or refactoring existing endpoints.

Step 1: Define resources and operations

# openapi.yaml

openapi: 3.0.3

info:

  title: User Service API

  version: 1.0.0

paths:

  /users:

    get:

      summary: List users

      parameters:

        - name: "limit"

          in: query

          schema:

            type: integer

            default: 20

    post:

      summary: Create user

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/CreateUser'

Step 2: Generate route scaffolding

python scripts/api_scaffolder.py openapi.yaml --framework express --output src/routes/

Step 3: Implement business logic

// src/routes/users.ts (generated, then customized)

export const createUser = async (req: Request, res: Response) => {

  const { email, name } = req.body;

  // Add business logic

  const user = await userService.create({ email, name });

  res.status(201).json(user);

};

Step 4: Add validation middleware

# Validation is auto-generated from OpenAPI schema

# src/middleware/validators.ts includes:

# - Request body validation

# - Query parameter validation

# - Path parameter validation

Step 5: Generate updated OpenAPI spec

python scripts/api_scaffolder.py src/routes/ --generate-spec --output openapi.yaml

Database Optimization Workflow

Use when queries are slow or database performance needs improvement.

Step 1: Analyze current performance

python scripts/database_migration_tool.py --connection $DATABASE_URL --analyze

Step 2: Identify slow queries

-- Check query execution plans

EXPLAIN ANALYZE SELECT * FROM orders

WHERE user_id = 123

ORDER BY created_at DESC

LIMIT 10;

-- Look for: Seq Scan (bad), Index Scan (good)

Step 3: Generate index migrations

python scripts/database_migration_tool.py --connection $DATABASE_URL \

  --suggest-indexes --output migrations/

Step 4: Test migration (dry-run)

python scripts/database_migration_tool.py --connection $DATABASE_URL \

  --migrate migrations/add_indexes.sql --dry-run

Step 5: Apply and verify

# Apply migration

python scripts/database_migration_tool.py --connection $DATABASE_URL \

  --migrate migrations/add_indexes.sql

# Verify improvement

python scripts/database_migration_tool.py --connection $DATABASE_URL --analyze

Security Hardening Workflow

Use when preparing an API for production or after a security review.

Step 1: Review authentication setup

// Verify JWT configuration

const jwtConfig = {

  secret: process.env.JWT_SECRET,  // Must be from env, never hardcoded

  expiresIn: '1h',                 // Short-lived tokens

  algorithm: 'RS256'               // Prefer asymmetric

};

Step 2: Add rate limiting

import rateLimit from 'express-rate-limit';

const apiLimiter = rateLimit({

  windowMs: 15 * 60 * 1000,  // 15 minutes

  max: 100,                   // 100 requests per window

  standardHeaders: true,

  legacyHeaders: false,

});

app.use('/api/', apiLimiter);

Step 3: Validate all inputs

import { z } from 'zod';

const CreateUserSchema = z.object({

  email: z.string().email().max(255),

  name: z.string().min(1).max(100),

  age: z.number().int().positive().optional()

});

// Use in route handler

const data = CreateUserSchema.parse(req.body);

Step 4: Load test with attack patterns

# Test rate limiting

python scripts/api_load_tester.py https://api.example.com/login \

  --concurrency 200 --duration 10 --expect-rate-limit

# Test input validation

python scripts/api_load_tester.py https://api.example.com/users \

  --method POST \

  --body '{"email": "not-an-email"}' \

  --expect-status 400

Step 5: Review security headers

import helmet from 'helmet';

app.use(helmet({

  contentSecurityPolicy: true,

  crossOriginEmbedderPolicy: true,

  crossOriginOpenerPolicy: true,

  crossOriginResourcePolicy: true,

  hsts: { maxAge: 31536000, includeSubDomains: true },

}));

Reference Documentation

Common Patterns Quick Reference

REST API Response Format

{

  "data": { "id": 1, "name": "John" },

  "meta": { "requestId": "abc-123" }

}

Error Response Format

{

  "error": {

    "code": "VALIDATION_ERROR",

    "message": "Invalid email format",

    "details": [{ "field": "email", "message": "must be valid email" }]

  },

  "meta": { "requestId": "abc-123" }

}

HTTP Status Codes

Database Index Strategy

-- Single column (equality lookups)

CREATE INDEX idx_users_email ON users(email);

-- Composite (multi-column queries)

CREATE INDEX idx_orders_user_status ON orders(user_id, status);

-- Partial (filtered queries)

CREATE INDEX idx_orders_active ON orders(created_at) WHERE status = 'active';

-- Covering (avoid table lookup)

CREATE INDEX idx_users_email_name ON users(email) INCLUDE (name);

Common Commands

# API Development

python scripts/api_scaffolder.py openapi.yaml --framework express

python scripts/api_scaffolder.py src/routes/ --generate-spec

# Database Operations

python scripts/database_migration_tool.py --connection $DATABASE_URL --analyze

python scripts/database_migration_tool.py --connection $DATABASE_URL --migrate file.sql

# Performance Testing

python scripts/api_load_tester.py https://api.example.com/endpoint --concurrency 50

python scripts/api_load_tester.py https://api.example.com/endpoint --compare baseline.json

Assumptions and Verifiable Success Criteria (Karpathy discipline)

Before this skill scaffolds, recommends a pattern, or modifies a schema, the following four assumptions MUST be surfaced. If any are unknown, the skill stops and walks the [Forcing-question library](#forcing-question-library-matt-pocock-grill) instead.

• Read/write ratio + one-year p99 QPS — drives DB, cache, queue, and partitioning choices. Kleppmann, DDIA (2017).

• Tenancy model — single-tenant, shared multi-tenant, isolated multi-tenant. Drives data-access pattern.

• Data sensitivity tier — public / internal / PII / PHI / PCI. Drives compliance floor.

• SLO + named error-budget consumer — Google SRE Workbook canon. No SLO = no reliability work prioritization.

Verifiable success criteria (Karpathy #4) — every recommendation this skill emits must include:

• Latency targets (p50, p95, p99 in ms)

• Uptime / SLO target

• RPO + RTO

If any of those three is not stated, the recommendation is incomplete — return to Q7 of the forcing-question library.

The scripts/backend_decision_engine.py tool encodes these checks: it refuses to recommend a profile without read/write ratio + QPS + tenancy + data sensitivity + pattern preference.

Customization profiles

Four built-in profiles in profiles/ calibrate every recommendation:

| node-express | TS team, .json and adjust constraints + success_thresholds + named_approver_chain.

Composition map

This skill does NOT reimplement scope owned by the POWERFUL-tier specialists. It forks into them. See references/composition_map.md for the full routing table. Key forks:

The cs-backend-engineer agent orchestrates these forks via context: fork. Invoke it from another agent with Agent({subagent_type: "cs-backend-engineer", prompt: "..."}) or via /cs:backend-review <your problem>.

Forcing-question library (Matt Pocock grill)

Before locking any backend decision, walk the seven forcing questions in references/forcing_questions.md. Discipline:

• One question per turn. No bundling.

• Always recommend the answer with cited canon.

• Track answers in /tmp/backend-grill-<date>.md.

• If a kill criterion trips, stop. Don't scaffold around an unresolved gap.

• After Q7, run backend_decision_engine.py with the seven answers.

Summary:

• Read/write ratio + p99 QPS forecast?

• Tenancy model — single / shared / isolated?

• Sync / async / event-driven — default + exceptions?

• Data sensitivity tier — PII / PHI / PCI?

• Monolith / modular monolith / microservices — team-size justification?

• RPO + RTO?

• SLO + named error-budget consumer?

Invocation from other agents and skills

Three surfaces:

• Slash command: /cs:backend-review <prompt> — full grill + decision engine + composition routing.

• Agent subagent: Agent({subagent_type: "cs-backend-engineer", prompt: "..."}) — forks context, returns ≤ 200-word digest.

• Direct tool call: python scripts/backend_decision_engine.py ... — deterministic profile match when inputs are known.

See agents/engineering/cs-backend-engineer.md for the full invocation contract.