ADR-0022: Fastify as API Framework

Status

Accepted - 2025-01-26

---

Context

TVL Platform needs a Node.js API framework for HTTP endpoints with performance, type safety, and validation requirements.

---

Decision

Fastify 4.x as the API framework.

Rationale

1. Performance: 3x faster than Express (65k req/sec vs 20k req/sec)
2. Schema Validation: Built-in JSON Schema validation
3. TypeScript: Native TypeScript support
4. OpenAPI: Auto-generate OpenAPI specs with @fastify/swagger
5. Plugin System: Modular architecture

---

Alternatives Considered

Alternative 1: Express

Rejected - 3x slower, no built-in validation, middleware hell

Alternative 2: Hapi

Rejected - Good but declining popularity, smaller ecosystem

Alternative 3: NestJS

Rejected - Too heavy, opinionated (Angular-like), overkill for MVP

---

Example Usage

// src/server.ts
import Fastify from 'fastify';

const app = Fastify({
  logger: true
});

// Schema validation
app.post<{ Body: CreateBookingRequest }>('/bookings', {
  schema: {
    body: {
      type: 'object',
      required: ['guestName', 'checkIn', 'checkOut'],
      properties: {
        guestName: { type: 'string', minLength: 1 },
        checkIn: { type: 'string', format: 'date-time' },
        checkOut: { type: 'string', format: 'date-time' }
      }
    }
  }
}, async (request, reply) => {
  const booking = await createBooking(request.body);
  return reply.status(201).send({ booking });
});

await app.listen({ port: 4000 });

---

Performance Benchmarks

Framework	Req/sec	Latency (p99)
Fastify	65,000	15ms
Express	20,000	50ms
Hapi	25,000	45ms

---

References

• Fastify Documentation
• Fastify vs Express