fastify: Architecture

Architecture health: 67/100 (D)

Overview

fastify is a JavaScript/TypeScript project. It is a library of 1 package. The main structural risks to watch: 5 oversized "god" files. The file with the widest blast radius is fastify.js: 37 files depend on it at runtime; oversized and doing too much.

_This entire analysis runs on your machine with no AI required. Connect a model provider to also narrate the reasoning and recover decisions._

Where to start

1. fastify.js Start here: how the system boots and wires its subsystems together.
2. lib/symbols.js Core module: 50 other modules depend on it, so it shapes much of the system.
3. test/helper.js Core module: 28 other modules depend on it, so it shapes much of the system.
4. lib/errors.js Core module: 27 other modules depend on it, so it shapes much of the system.
5. examples/benchmark/webstream.js Key flow: Background jobs, a medium-risk path that enters at GET / (examples/benchmark/webstream.js).

System map

flowchart TD
  subgraph sys_boundary["fastify"]
    fastify["fastify"]
  end
  class fastify library
  classDef frontend fill:#2563eb,stroke:#93c5fd,color:#fff,stroke-width:2px;
  classDef service fill:#059669,stroke:#6ee7b7,color:#fff,stroke-width:2px;
  classDef store fill:#d97706,stroke:#fcd34d,color:#fff,stroke-width:2px;
  classDef queue fill:#9333ea,stroke:#d8b4fe,color:#fff,stroke-width:2px;
  classDef job fill:#4f46e5,stroke:#a5b4fc,color:#fff,stroke-width:2px;
  classDef external fill:#475569,stroke:#cbd5e1,color:#fff,stroke-width:2px;
  classDef aiprovider fill:#e11d48,stroke:#fda4af,color:#fff,stroke-width:2px;
  classDef library fill:#0891b2,stroke:#67e8f9,color:#fff,stroke-width:2px;
  classDef cli fill:#0d9488,stroke:#5eead4,color:#fff,stroke-width:2px;
  classDef user fill:#64748b,stroke:#e2e8f0,color:#fff,stroke-width:2px;
  classDef muted fill:#334155,stroke:#64748b,color:#cbd5e1,stroke-width:1px;

Critical flows

Application startup high risk

Entry: process start (fastify.js)

moves work onto a queue (queue); returns a response to the caller (client)

Boot wires every subsystem together; a fault here stops the whole process from starting. It also passes through a fragile zone (fastify.js), widening the blast radius.

sequenceDiagram
  actor C0 as Process
  participant F0 as fastify.js
  participant F1 as symbols.js
  participant F2 as server.js
  participant F3 as reply.js
  participant F4 as request.js
  participant F5 as context.js
  participant Queue as queue
  C0->>F0: process start
  F0->>Queue: moves work onto a queue
  F0->>F1: calls
  F0->>F2: calls
  F0->>F3: calls
  F3-->>C0: returns a response to the caller
  F0->>F4: calls
  F0->>F5: calls

Background jobs medium risk

Entry: GET / (examples/benchmark/webstream.js)

moves work onto a queue (queue)

Background jobs run unattended; failures are silent and can pile up unnoticed.

sequenceDiagram
  actor C0 as Scheduler
  participant F0 as webstream.js
  participant Queue as queue
  C0->>F0: GET /
  F0->>Queue: moves work onto a queue

Fragile zones

• fastify.js (score 83): 37 files depend on it at runtime; oversized and doing too much
• lib/symbols.js (score 44): 22 files depend on it at runtime
• lib/errors.js (score 34): 17 files depend on it at runtime
• lib/hooks.js (score 14.5): 7 files depend on it at runtime
• lib/reply.js (score 12.3): 3 files depend on it at runtime; oversized and doing too much
• lib/content-type.js (score 10): 5 files depend on it at runtime
• lib/warnings.js (score 10): 5 files depend on it at runtime
• lib/error-handler.js (score 9.5): 4 files depend on it at runtime
• lib/logger-factory.js (score 9): 4 files depend on it at runtime
• lib/schemas.js (score 8.8): 4 files depend on it at runtime
• lib/decorate.js (score 8.5): 4 files depend on it at runtime
• lib/route.js (score 8): 1 file depends on it at runtime; oversized and doing too much

Architecture rules