Docs/Backend Core/Backend Architecture

Backend Architecture

ENGINE

Firebreak's backend follows a strict layered pattern dividing responsibilities into HTTP Gateways, Security Guards, Domain Services, Infrastructure Adapters, and Persistence.

4 min read

•

Production Verified

Gateways and Ingestion Endpoints

External signals enter Firebreak through two hardened endpoints:

apps/web/src/app/api/v1/alerts/[serviceId]/route.ts

// HMAC SHA-256 validation using constant-time comparison
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
  return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
}

// Deduplicate alert & dispatch durable workflow
const incident = await AlertService.ingestAlert(serviceId, payload);
await inngest.send({ name: "firebreak/incident.created", data: { incidentId: incident.id } });
return NextResponse.json({ status: "accepted", incidentId: incident.id }, { status: 202 });

Core Domain Services

Service	Path	Core Responsibility
alerts.ts	packages/core/src/services/alerts.ts	Alert ingestion, sliding window deduplication, and fingerprint calculation.
trace.ts	packages/core/src/services/trace.ts	Coordinates deployment identification and commit delta retrieval.
ranking.ts	packages/core/src/domain/ranking.ts	The 8-factor commit blame scoring algorithm and path normalizer.
preflight.ts	packages/core/src/domain/preflight.ts	Pure evaluation of the 6 rollback safety checks.
actions.ts	packages/core/src/services/actions.ts	Stages proposals with 15-min TTL, enforces approval, and executes rollback.
probe.ts	packages/core/src/adapters/probe.ts	Runs automated canary health checks requiring a 3x consecutive 200 OK streak.

Development & Repos

Database & Drizzle ORM