backend-flight-recorder

backend-flight-recorder captures request-scoped backend activity and turns it into an LLM-ready debugging bundle.

The package is built for the workflow where a developer, QA system, e2e test, or AI agent reproduces a bug while recording:

• incoming API request metadata
• request body, params, and selected headers
• request-scoped timeline entries
• Prisma mutations attributed to that request
• a final prompt optimized for GPT, Claude, or Codex

What it does

• Creates a request context with AsyncLocalStorage
• Captures Express request and response data
• Hooks Prisma mutations back to the active request
• Persists records to memory or PostgreSQL
• Generates a debugging prompt that assumes the model already has repository read access

Install

npm install backend-flight-recorder

Optional peers:

npm install express @prisma/client

Quick start

import express from "express";
import { createFlightRecorder, createPostgresFlightRecorderStore } from "backend-flight-recorder";
import { createExpressMiddleware } from "backend-flight-recorder/express";
import { attachPrismaFlightRecorder } from "backend-flight-recorder/prisma";
import { Pool } from "pg";
import { PrismaClient } from "@prisma/client";

const app = express();
app.use(express.json());

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const prisma = new PrismaClient();

const recorder = createFlightRecorder({
  environment: process.env.NODE_ENV,
  appVersion: process.env.APP_VERSION,
  includeRequestHeaders: ["x-request-id", "user-agent"],
  includeResponseHeaders: ["content-type"],
  redact: {
    headers: ["authorization", "cookie"],
    bodyPaths: ["password", "token", "creditCard.number"],
    replacement: "[REDACTED]"
  },
  store: createPostgresFlightRecorderStore({
    executor: {
      query: (sql, params) => pool.query(sql, params)
    }
  })
});

app.use(
  createExpressMiddleware(recorder, {
    actorExtractor: (req) => ({
      id: req.user?.id,
      role: req.user?.role
    })
  })
);

attachPrismaFlightRecorder(recorder, prisma, {
  captureBefore: true
});

app.post("/api/orders", async (req, res) => {
  const order = await prisma.order.create({
    data: {
      sku: req.body.sku
    }
  });

  res.status(201).json(order);
});

Targeted recording helpers

Most teams do not want to record every request. The package exports composable helpers so you can target a route, actor, or debug header without writing the filter plumbing yourself.

import {
  allRecordFilters,
  createFlightRecorder,
  matchActorIds,
  matchHeader,
  matchRoutes
} from "backend-flight-recorder";

const recorder = createFlightRecorder({
  shouldRecord: allRecordFilters(
    matchRoutes([/^\/api\//], { methods: ["POST", "PATCH", "DELETE"] }),
    matchHeader("x-debug-session", ["on"])
  )
});

const userScopedRecorder = createFlightRecorder({
  shouldRecord: allRecordFilters(
    matchRoutes(["/api/orders"]),
    matchActorIds(["user_42"])
  )
});

Available helpers:

• matchRoutes(routes, { methods })
• matchActorIds(actorIds)
• matchHeader(headerName, expectedValues?)
• allRecordFilters(...filters)
• anyRecordFilter(...filters)
• notRecordFilter(filter)

LLM-ready output

Each completed record includes:

• structured JSON fields for the request, response, timeline, and mutations
• llmPrompt, a debug prompt tailored for repository-aware coding agents

The prompt tells the model to:

• trace the code path from route handler to data layer
• identify the most likely root cause
• propose the smallest safe fix
• list the tests that should be added

PostgreSQL tables

The PostgreSQL store auto-creates these tables by default:

• flight_recorder_sessions
• flight_recorder_db_mutations
• flight_recorder_errors

If you want to manage migrations yourself:

import { getPostgresSchemaSql } from "backend-flight-recorder/sql";

const statements = getPostgresSchemaSql("public");

API

createFlightRecorder(options)

Core options:

• enabled
• environment
• appVersion
• includeRequestHeaders
• includeResponseHeaders
• recordBody
• recordResponseBody
• redact
• shouldRecord
• store

createExpressMiddleware(recorder, options)

Express middleware that:

• starts a request-scoped recording session
• captures response bodies by patching res.send and res.json
• finalizes the record on finish

attachPrismaFlightRecorder(recorder, prisma, options)

Prisma middleware that:

• records write operations such as create, update, upsert, and delete
• optionally captures a before snapshot for where-addressable mutations
• appends the mutation to the active request timeline

Example app

A minimal example lives at examples/express-prisma.ts. It shows:

• Express integration
• Prisma mutation attribution
• PostgreSQL-backed storage
• route and header-based recording activation

The example is illustrative and is not included in the published runtime exports.

Current MVP boundaries

This first version is intentionally narrow:

• Node.js only
• Express middleware only
• Prisma attribution only
• PostgreSQL storage helper only
• in-process causality only

Async work that leaves the request lifecycle, such as queues or separate workers, needs explicit propagation if you want those mutations tied back to the original request.