Eve library

ADR-0001: Microservices Architecture with Fastify

Guide

Revision 1

On this page

Date: 2025-09-14
Status: Accepted
Deciders: Architecture Team

Context#

The Lilith platform requires a scalable architecture to support multiple AI-powered services including chat, content delivery, speech synthesis, and user management. Key requirements:

  • Independent deployment and scaling of components
  • Team autonomy for parallel development
  • High availability and fault isolation
  • Sub-second response times for chat
  • Integration with multiple AI providers

Decision#

Adopt a microservices architecture using Fastify as the web framework with a Backend-for-Frontend (BFF) pattern.

Key Components#

  • Individual services: auth, content, conversation, ai, media, notification, moderation
  • BFF service for client aggregation
  • Istio service mesh for inter-service communication
  • Event-driven communication for async operations

Rationale#

Why Microservices#

  • Enables independent scaling (AI vs. user management)
  • Supports technology diversity where needed
  • Provides fault isolation
  • Matches Kubernetes deployment target

Why Fastify#

  • Superior performance vs Express.js
  • Built-in schema validation
  • Strong TypeScript support
  • Good observability hooks

Why BFF#

  • Different clients need different data shapes
  • Reduces client-server round trips
  • Centralizes cross-cutting concerns

Alternatives Considered#

  1. Monolith: Rejected due to scaling requirements
  2. Express.js: Rejected for performance reasons
  3. GraphQL Federation: Rejected due to caching complexity

Consequences#

Positive#

  • Better scalability and resilience
  • Team autonomy
  • Technology flexibility

Negative#

  • Distributed system complexity
  • Network latency between services
  • More complex debugging

Mitigations#

  • Comprehensive distributed tracing
  • Circuit breakers and retries
  • Service mesh for reliability